@archon-claw/skills - npm Package Compare versions

Comparing version 0.4.2 to 0.4.3

skills/use-mcp/SKILL.md

+---
+name: use-mcp
+description: 了解 MCP 服务器配置后的工作机制。当用户想知道 mcp.json 配置后工具如何被发现、命名、路由和调用时使用。
+---
+
+介绍 `mcp.json` 配置后 MCP 工具的完整生命周期：从连接建立到工具发现、合并、调用。
+
+## 工作原理
+
+Agent 启动时，框架读取 `mcp.json` 并为每个 enabled 的服务器建立连接，发现其工具列表，经过过滤和命名后合并到 agent 的工具列表中。对 LLM 而言，MCP 工具与本地工具（`tools/*.json`）无任何区别。
+
+### 生命周期
+
+```
+agent 启动
+  → 读取 mcp.json
+  → 为每个 server 建立连接（支持 stdio / sse / streamable-http）
+  → 发现工具（listTools，支持分页）
+  → 应用 include/exclude 过滤
+  → 应用 rename / 自动前缀命名
+  → 合并到 agent 工具列表
+  → LLM 通过 function calling 正常调用
+  → 框架自动路由到对应 MCP server 执行
+```
+
+## 连接与协议协商
+
+### stdio（本地进程）
+
+有 `command` 字段时使用。框架启动子进程，通过 stdin/stdout 通信：
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+### 远程服务器（自动协商）
+
+有 `url` 字段且未指定 `transport` 时，框架先尝试 streamable-http，失败后自动降级为 SSE。控制台会打印协商结果：
+
+```
+[mcp] "remote_api": connected via streamable-http
+```
+
+或：
+
+```
+[mcp] "remote_api": streamable-http failed (...), falling back to SSE
+```
+
+如果确定服务器只支持 SSE，可显式指定 `"transport": "sse"` 跳过协商。
+
+## 工具命名
+
+### 默认：自动前缀
+
+格式为 `{serverName}__{toolName}`，两部分各自规范化为 `^[a-z][a-z0-9_]*$`：
+
+| serverName | MCP 工具名 | 最终名称 |
+|---|---|---|
+| `playwright` | `browser_navigate` | `playwright__browser_navigate` |
+| `my-api` | `searchUsers` | `my_api__searchusers` |
+
+### rename：自定义名称
+
+通过 `tools.rename` 可重命名工具（不加前缀）：
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"],
+      "tools": {
+        "rename": {
+          "browser_navigate": "goto",
+          "browser_snapshot": "screenshot"
+        }
+      }
+    }
+  }
+}
+```
+
+此时 LLM 看到的工具名是 `goto` 和 `screenshot`，没有 `playwright__` 前缀。
+
+## 工具过滤
+
+### include（白名单）
+
+只暴露匹配 glob 模式的工具：
+
+```json
+"tools": { "include": ["browser_*"] }
+```
+
+### exclude（黑名单）
+
+隐藏匹配的工具：
+
+```json
+"tools": { "exclude": ["browser_install", "*_deprecated"] }
+```
+
+### 组合使用
+
+先 include 再 exclude：
+
+```json
+"tools": {
+  "include": ["browser_*"],
+  "exclude": ["browser_install"]
+}
+```
+
+## 冲突处理
+
+MCP 工具与本地工具（`tools/*.json`）同名时，**本地工具优先**，MCP 工具被跳过并打印警告：
+
+```
+[mcp] Skipping tool "search" — conflicts with local tool
+```
+
+解决方式：
+- 用 `rename` 给 MCP 工具改名
+- 或依赖默认的 `{serverName}__` 前缀避免冲突
+
+## 环境变量
+
+`env`、`url`、`command`、`args`、`headers` 等字段都支持 `${VAR}` 语法引用环境变量：
+
+```json
+{
+  "url": "https://api.example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${API_TOKEN}"
+  },
+  "env": {
+    "DB_URL": "${DATABASE_URL:-postgresql://localhost:5432/mydb}"
+  }
+}
+```
+
+- `${VAR}` — 引用环境变量，未设置时打印警告并替换为空字符串
+- `${VAR:-default}` — 未设置时使用默认值
+
+## 超时
+
+默认工具调用超时 30 秒。对于耗时较长的工具（如浏览器操作），可调大：
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"],
+      "timeout": 60000
+    }
+  }
+}
+```
+
+## 错误处理
+
+- 单个 MCP server 连接失败**不会阻止 agent 启动**，只打印警告，其他 server 正常工作
+- `mcp.json` 不存在是正常的，agent 只使用本地工具
+- 工具调用超时会抛出错误，LLM 会收到错误信息
+
+## 调试
+
+- 启动时观察控制台日志，确认连接状态和注册的工具数量：
+  ```
+  [mcp] Connected to "playwright": 15 tool(s) registered
+  ```
+- 使用 `/api/agents/:agentId/health` 检查 agent 状态
+- 如果工具未出现，检查 `include`/`exclude` 过滤规则是否正确

skills/use-skill/SKILL.md

+---
+name: use-skill
+description: 了解 agent skill 的工作机制和使用方式。当用户想知道 skill 创建后如何生效、LLM 如何调用时使用。
+---
+
+介绍 agent skill 的运行机制：从文件放置到自动注入，再到 LLM 按需调用的完整流程。
+
+## 工作原理
+
+当 agent 目录下存在 `skills/` 且包含有效的 SKILL.md 文件时，框架在加载 agent 配置时会**自动注入**一个内置工具 `skill_load`。
+
+### 注入流程
+
+1. 框架扫描 `skills/` 目录，解析每个 SKILL.md 的 frontmatter（`name` + `description`）和 body
+2. 如果至少有一个有效 skill，自动生成 `skill_load` 工具定义并注册到 agent 的工具列表
+3. `skill_load` 的 `description` 中包含所有 skill 的名称和描述摘要（catalog）
+4. `input_schema` 的 `name` 参数为 enum，枚举所有可用 skill 名称
+5. LLM 通过 function calling 调用 `skill_load(name: "xxx")`，返回该 skill 的完整 body 内容
+
+### 自动生成的工具定义（示意）
+
+```json
+{
+  "name": "skill_load",
+  "description": "Load a skill's full instructions by name. Available skills:\n\n- code-review: 对代码进行 review\n- explain-code: 解释代码逻辑",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "type": "string",
+        "description": "Skill name",
+        "enum": ["code-review", "explain-code"]
+      }
+    },
+    "required": ["name"]
+  }
+}
+```
+
+## 使用方式
+
+### 1. 创建 skill 文件
+
+```
+agents/my-agent/
+└── skills/
+    └── code-review/
+        └── SKILL.md
+```
+
+SKILL.md 格式参见 `create-skill` 技能。
+
+### 2. 无需修改系统提示词
+
+`skill_load` 工具的 description 已包含完整的 skill catalog，LLM 通过工具列表自动发现可用 skill。**不需要**在 `system-prompt.md` 中手动列出 skill 列表。
+
+如果希望强化引导，可以在系统提示词中添加简短提示：
+
+```markdown
+## 技能
+
+当用户的请求匹配某个技能时，先调用 skill_load 获取完整指令再执行。
+```
+
+### 3. LLM 调用流程
+
+```
+用户提问 → LLM 识别需要某个 skill
+         → LLM 调用 skill_load(name: "code-review")
+         → 框架返回 skill body 内容
+         → LLM 按照 body 中的指令执行任务
+```
+
+这是一种**按需加载**的设计：skill 内容不会塞进系统提示词占用 token，只有 LLM 判断需要时才加载。
+
+## 最佳实践
+
+- **粒度适中**：一个 skill 对应一类任务，不要把所有指令塞进一个 skill
+- **description 写清楚**：LLM 靠 description 判断何时调用，描述要准确反映使用场景
+- **body 写具体步骤**：body 是 LLM 拿到后直接执行的指令，越具体越好
+- **不要重复系统提示词**：skill 是系统提示词的补充，不是替代；通用规则放系统提示词，特定任务放 skill
+
+## 调试
+
+- 启动 agent 后，在 `/api/agents/:agentId/health` 检查 agent 是否加载成功
+- 工具列表中应能看到 `skill_load`，description 中包含所有 skill 的 catalog
+- 如果 `skill_load` 未出现，检查 `skills/` 目录下是否有有效的 SKILL.md（frontmatter 必须有 `name` + `description`，body 不能为空）

package.json

 {
   "name": "@archon-claw/skills",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Claude Code skills for archon-claw workspace",
@@ -5,0 +5,0 @@ "type": "module",

No alert changes

Improved metrics

Total package byte prevSize

72929

11.74%

Number of package files

28

7.69%

No dependency changes