Add demo guidance skill to Agent skills and link skills doc in README

ai/agent/README.md

@@ -6,6 +6,7 @@ Agent模块是一个**客户端/中间层**，提供工具管理和调用接口
 
 - [核心概念](#核心概念)
 - [快速开始](#快速开始)
+- [技能清单](#技能清单)
 - [API文档](#api文档)
 - [MCP集成](#mcp集成)
 - [最佳实践](#最佳实践)
@@ -125,6 +126,11 @@ result, _ := ag.Execute(ctx, "查询北京的天气")
 fmt.Println(result.Response)
 ```
 
+## 技能清单
+
+Agent 的能力边界与职责细分可以整理成可复用的技能说明，方便在系统提示词或产品文档中复用。
+详见：[技能清单](skills.md)。
+
 ## API文档
 
 ### Client

ai/agent/skills.md

@@ -0,0 +1,213 @@
+# Claude Skills（Agent）
+
+以下内容按 Claude Skills 格式输出，便于直接纳入系统提示词或能力说明文档。每个技能以一致的字段结构描述。
+
+```yaml
+skills:
+  - name: 任务理解与目标确认
+    description: 读取用户指令，识别业务目标与必要输入（如关键词、时间范围、账号/权限等）。
+    input:
+      - 用户自然语言问题或任务说明
+    output:
+      - 清晰的任务目标
+      - 必要时提出澄清问题
+    constraints:
+      - 避免隐式假设关键参数
+      - 当工具调用需要必填参数时优先澄清
+
+  - name: 工具能力发现与选择
+    description: 根据任务目标，从本地工具与 MCP 工具中选择合适的工具组合。
+    input:
+      - 工具清单（本地工具 + MCP 工具）
+      - 任务目标
+    output:
+      - 工具选择策略
+      - 候选工具名称
+    constraints:
+      - 优先匹配名称/描述语义一致的工具
+      - 不应调用未注册工具
+
+  - name: 参数组装与校验
+    description: 构建工具调用参数 JSON，遵守工具参数 schema。
+    input:
+      - 工具参数 schema
+      - 用户上下文
+      - 对话历史
+    output:
+      - 合法的参数 JSON 字符串
+    constraints:
+      - 遵循必填字段与类型约束
+      - 缺失字段需澄清
+
+  - name: 工具调用与结果整合
+    description: 发起工具调用，解析返回结果并转化为面向用户的自然语言。
+    input:
+      - 工具名称
+      - 参数 JSON
+      - 工具返回内容
+    output:
+      - 结构化的结论或行动建议
+    constraints:
+      - 如工具返回结构化数据，先摘要再输出
+      - 避免泄露敏感信息
+
+  - name: 多轮工具调用编排
+    description: 在单次任务中完成多轮工具调用与结果累积（最多 N 轮）。
+    input:
+      - 前序工具结果
+      - 下一步所需的查询条件
+    output:
+      - 逐步推进到最终答案的行动序列
+    constraints:
+      - 控制调用轮数
+      - 若达到上限，提示用户进行进一步确认
+
+  - name: 对话历史与上下文保持
+    description: 维护对话历史，保持上下文一致性与引用正确性。
+    input:
+      - 对话历史
+      - 系统提示词
+    output:
+      - 一致的上下文推理与连续性回答
+    constraints:
+      - 与系统提示词冲突时以系统提示词为准
+
+  - name: 错误处理与降级策略
+    description: 工具调用失败或结果异常时，给出可行的降级策略或人工确认。
+    input:
+      - 工具报错信息或异常返回
+    output:
+      - 可执行的替代方案或下一步指引
+    constraints:
+      - 明确失败原因与可重试步骤
+      - 避免编造结果
+
+  - name: 结构化输出与可复用结果
+    description: 需要时输出结构化结果（列表、表格、要点），便于被下游系统消费。
+    input:
+      - 工具结果
+      - 业务目标
+    output:
+      - 结构化摘要（如 JSON 风格列表或表格）
+    constraints:
+      - 结构化输出前确认用户需要
+      - 必要时先确认输出格式
+
+  - name: MCP 工具接入能力
+    description: 利用 MCP 适配器与外部工具生态协作（如爬虫、数据库、查询服务）。
+    input:
+      - MCP 工具清单
+      - 工具描述
+    output:
+      - MCP 工具调用结果的自然语言总结
+    constraints:
+      - 保持工具调用参数与协议要求一致
+      - 遵循工具返回数据的安全边界
+
+  - name: 流式输出与用户体验
+    description: 在流式输出时保持语义连贯、可被用户理解。
+    input:
+      - 流式响应片段
+    output:
+      - 连贯的最终响应
+    constraints:
+      - 避免在流式阶段输出尚未确认的结论
+
+  - name: Demo 示例引导与最小可运行说明
+    description: 为用户提供最小可运行的示例指引，说明如何组合 Client/Agent 与工具调用的关键步骤。
+    input:
+      - 用户的示例需求（如“如何接 MCP 工具”）
+      - 已注册工具或可用工具清单
+    output:
+      - 示例步骤清单或伪代码结构
+    constraints:
+      - 避免引用仓库中过期 demo 文件
+      - 仅输出与当前 API 约定一致的示例流程
+```
+
+---
+
+### 使用建议
+- 系统提示词可直接引用上述技能名称与职责范围，用于约束 Agent 行为。
+- 技能裁剪应与业务场景对应，例如“优惠券采集”可重点使用：工具能力发现与选择 / 参数组装与校验 / 工具调用与结果整合 / 多轮工具调用编排 / MCP 工具接入能力。
+
+### Mark3Labs MCP 最小可用流程（示例）
+以下流程从 Mark3Labs MCP 客户端创建开始，展示**可直接运行的最小链路**（需替换为真实 MCP Server 启动命令）。
+
+1. 创建 MCP Client（Stdio）。
+2. 启动并初始化 MCP Client。
+3. 创建 MCP Adapter 并注入到 Agent Client。
+4. 使用 Agent 或 Client 发起带工具的对话。
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/karosown/katool-go/ai"
+	"github.com/karosown/katool-go/ai/agent"
+	"github.com/karosown/katool-go/ai/agent/adapters"
+	"github.com/karosown/katool-go/ai/types"
+	"github.com/karosown/katool-go/xlog"
+	mcpclient "github.com/mark3labs/mcp-go/client"
+	"github.com/mark3labs/mcp-go/mcp"
+)
+
+func main() {
+	ctx := context.Background()
+
+	// 1) 创建 MCP Client（使用你自己的 MCP Server 启动命令）
+	mcpStd, err := mcpclient.NewStdioMCPClient(
+		"cmd",
+		nil,
+		"/c",
+		"npx",
+		"-y",
+		"your-mcp-server",
+	)
+	if err != nil {
+		panic(err)
+	}
+	defer mcpStd.Close()
+
+	// 2) 启动并初始化 MCP Client
+	if err := mcpStd.Start(ctx); err != nil {
+		panic(err)
+	}
+	initReq := mcp.InitializeRequest{}
+	initReq.Params.ProtocolVersion = mcp.LATEST_PROTOCOL_VERSION
+	initReq.Params.ClientInfo = mcp.Implementation{Name: "Agent Demo", Version: "1.0.0"}
+	if _, err := mcpStd.Initialize(ctx, initReq); err != nil {
+		panic(err)
+	}
+
+	// 3) 创建 Agent Client 并注入 MCP Adapter
+	logger := xlog.LogrusAdapter{}
+	aiClient, err := ai.NewClient()
+	if err != nil {
+		panic(err)
+	}
+	agentClient, err := agent.NewClient(aiClient)
+	if err != nil {
+		panic(err)
+	}
+	adapter, err := adapters.NewMark3LabsAdapterFromClient(ctx, mcpStd, logger)
+	if err != nil {
+		panic(err)
+	}
+	agentClient.SetMCPAdapter(adapter)
+
+	// 4) 发起带工具调用的对话（可替换为 Agent.Execute）
+	resp, err := agentClient.Chat(ctx, &types.ChatRequest{
+		Model:    "Qwen2",
+		Messages: []types.Message{{Role: types.RoleUser, Content: "调用工具完成任务"}},
+		Tools:    agentClient.GetAllTools(),
+	})
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(resp.Choices[0].Message.Content)
+}
+```