diff --git a/docs/extensibility/skills.mdx b/docs/extensibility/skills.mdx index d19b0b006..2ded8056b 100644 --- a/docs/extensibility/skills.mdx +++ b/docs/extensibility/skills.mdx @@ -1,221 +1,123 @@ --- -title: "Skills 技能系统 - Prompt 即能力的架构哲学" -description: "深入剖析 Claude Code Skills 系统的完整实现：从磁盘加载、Frontmatter 解析、预算感知描述截断、双模式执行（inline/fork）、权限白名单、条件激活、动态发现到远程技能加载，揭示一条完整的 Skill 生命周期链路。" -keywords: ["Skills", "SkillTool", "技能加载", "Frontmatter", "whenToUse", "allowedTools", "fork执行", "动态发现"] +title: "Skills 技能系统" +description: "Prompt 即能力。Skill 不是代码，而是高质量的 Prompt + 权限配置的声明式封装。理解加载链路、两条执行路径和条件激活机制。" +keywords: ["Skills", "技能加载", "Prompt 即能力", "条件激活"] --- -{/* 本章目标：揭示 Skill 系统从文件到执行的全链路实现 */} +## 核心洞见：Prompt 即能力 -## Tool vs Skill：本质差异 +Skill 的核心设计哲学：**复杂任务的关键不在代码逻辑，而在 Prompt 质量**。 + +一个代码审查 Skill 不需要审查引擎，只需告诉 AI "审查什么、按什么顺序、输出什么格式"。Skill 把这种"经验"封装为可复用的 Markdown 文件。 | | Tool | Skill | |---|---|---| -| 粒度 | 单个原子操作（读文件、执行命令） | 一套完整的工作流（代码审查、创建 PR） | -| 触发方式 | AI 自主选择 | 用户 `/skill-name` 或 AI 通过 `SkillTool` 自动匹配 | -| 本质 | TypeScript 执行逻辑 | **Prompt + 权限配置**的声明式封装 | -| 注册位置 | `src/tools.ts` → `getTools()` | `src/commands.ts` → `getCommands()` | -| 执行器 | 各 Tool 的 `call()` 方法 | `SkillTool.call()` → 两条分支（inline / fork） | +| 粒度 | 单个原子操作（读文件、执行命令） | 完整工作流（代码审查、创建 PR） | +| 本质 | TypeScript 执行逻辑 | Prompt + 权限配置的声明式封装 | +| 创建 | 需要写代码 | 写 Markdown 文件即可 | -Skill 的核心洞见：**复杂任务的关键不在代码逻辑，而在 Prompt 质量**。一个代码审查 Skill 不需要审查引擎，只需告诉 AI "审查什么、按什么顺序、输出什么格式"——Skill 把这种"经验"封装为可复用的 Markdown。 +## Skill 的来源 -## Skill 的五个来源与加载链路 +| 来源 | 路径 | 特点 | +|------|------|------| +| **内置命令** | 硬编码 | `/commit`、`/compact` 等 70+ 命令 | +| **Bundled Skills** | 编译时打包 | 延迟解压，享有不可截断特权 | +| **磁盘 Skills** | `.claude/skills/` | 最重要的来源，支持多层级 | +| **MCP Skills** | MCP Server 提供 | 远程内容，禁止内联 shell 命令 | +| **Legacy Commands** | `.claude/commands/` | 向后兼容旧格式 | -### 1. 内置命令（Built-in Commands） - -硬编码在 `src/commands.ts:299` 的 `COMMANDS` memoize 数组中，包含 70+ 条命令（`/commit`、`/review`、`/compact` 等）。这些是 TypeScript 模块而非 Markdown，但实现了相同的 `Command` 接口（`src/types/command.ts`）。 - -### 2. Bundled Skills（编译时打包） - -通过 `registerBundledSkill()`（`src/skills/bundledSkills.ts:53`）在模块初始化时注册。关键特性： - -- **延迟文件提取**：如果 Skill 声明了 `files`（参考文件），首次调用时才解压到临时目录（`getBundledSkillExtractDir()`），使用 `O_NOFOLLOW | O_EXCL` 防止符号链接攻击（`safeWriteFile`，第 186 行） -- **闭包级 memoize**：并发调用共享同一个 extraction promise，避免竞态写入 -- 来源标记为 `source: 'bundled'`，在 Prompt 预算中享有**不可截断**的特权 - -### 3. 磁盘 Skills（`.claude/skills/`） - -由 `loadSkillsFromSkillsDir()`（`src/skills/loadSkillsDir.ts:407`）加载，这是最重要的加载路径： +### 多层级磁盘加载 ``` -管理策略: $MANAGED_DIR/.claude/skills/ (policySettings) -用户全局: ~/.claude/skills/ (userSettings) -项目级: .claude/skills/ (projectSettings, 向上遍历至 home) -附加目录: --add-dir 指定的路径下 .claude/skills/ +管理策略: $MANAGED_DIR/.claude/skills/ （企业管理） +用户全局: ~/.claude/skills/ （个人偏好） +项目级: .claude/skills/ （团队共享） +附加目录: --add-dir 指定的路径 （额外来源） ``` -**加载协议**：只识别 `skill-name/SKILL.md` 目录格式，不再支持单文件 `.md`。加载流程： +每个 Skill 是一个 `skill-name/SKILL.md` 目录。加载时解析 YAML frontmatter 提取配置。 -1. `readdir` 扫描目录 → 仅保留 `isDirectory()` 或 `isSymbolicLink()` 的条目 -2. 在每个子目录中查找 `SKILL.md`，未找到则跳过 -3. `parseFrontmatter()` 解析 YAML 头部，提取 `whenToUse`、`allowedTools`、`context` 等字段 -4. `parseSkillFrontmatterFields()`（第 185 行）统一解析 16 个 frontmatter 字段 -5. `createSkillCommand()`（第 270 行）构造 `Command` 对象 +### 安全边界 -**去重机制**：使用 `realpath()` 解析符号链接获得规范路径（`getFileIdentity`，第 118 行），避免通过符号链接或重叠父目录导致的重复加载。 +MCP Skills 的 Prompt 内容**禁止执行内联 shell 命令**。因为远程内容不可信——如果允许，恶意 MCP Server 就可以通过 Skill 注入执行任意命令。 -### 4. MCP Skills（动态发现） +## Frontmatter 配置 -通过 `registerMCPSkillBuilders()` 注册构建器，MCP Server 的 prompt 被 `mcpSkillBuilders.ts` 转换为 `Command` 对象。标记为 `loadedFrom: 'mcp'`。 - -**安全边界**：MCP Skills 的 Prompt 内容**禁止执行内联 shell 命令**（`loadSkillsDir.ts:374` 的 `loadedFrom !== 'mcp'` 守卫），因为远程内容不可信。 - -### 5. Legacy Commands（`/commands/` 目录） - -向后兼容的旧格式，由 `loadSkillsFromCommandsDir()`（第 566 行）加载。同时支持 `SKILL.md` 目录格式和单 `.md` 文件格式。 - -## Frontmatter 字段全景 - -一个 `SKILL.md` 的完整 frontmatter（`parseSkillFrontmatterFields`，第 185 行）： +一个 SKILL.md 的完整配置： ```yaml --- -name: code-review # 显示名称（覆盖目录名） -description: 系统性代码审查 # 描述（或从 Markdown 首段提取） -when_to_use: "用户说审查代码、找 bug" # AI 自动匹配依据 -allowed-tools: # 工具白名单 +name: code-review +description: 系统性代码审查 +when_to_use: "用户说审查代码、找 bug" +allowed-tools: - Read - Grep - Glob -argument-hint: "" # 参数提示 -arguments: [path] # 声明式参数名（用于 $ARGUMENTS 替换） -model: opus # 模型覆盖 -effort: high # 努力级别 -context: fork # 执行模式：inline（默认）| fork -agent: code-reviewer # 指定 Agent 定义文件 -user-invocable: true # 用户是否可 /调用 -disable-model-invocation: false # 禁止 AI 自主调用 -version: "1.0" # 版本号 -paths: # 条件激活的文件路径模式 +context: fork # 执行模式：inline | fork +model: opus # 模型覆盖 +effort: high # 努力级别 +paths: # 条件激活 - "src/**/*.ts" -hooks: # Hook 配置 - PreToolUse: - - command: ["echo", "checking"] -shell: ["bash"] # Shell 执行环境 --- ``` -解析后有 16 个字段被提取，其中 `allowedTools`、`model`、`effort` 在执行时动态修改 `toolPermissionContext`。 +- `when_to_use` — AI 根据此描述自动匹配用户意图 +- `allowed-tools` — 限制 Skill 可用的工具白名单 +- `context` — 控制执行模式（见下文） +- `paths` — 条件激活，只在操作匹配文件时出现 -## 两条执行路径：Inline vs Fork - -SkillTool（`packages/builtin-tools/src/tools/SkillTool/SkillTool.ts:332`）在 `call()` 中根据 `command.context` 分流： +## 两条执行路径 ### Inline 模式（默认） -Skill 的 Prompt 内容被注入为 **UserMessage**，在主对话流中继续执行： +Skill 的 Prompt 内容被注入为用户消息，在主对话流中继续执行。AI "穿上"了 Skill 的经验，但仍在同一个对话中。 -1. `processPromptSlashCommand()` 处理参数替换（`$ARGUMENTS`）和 shell 命令展开（`` !`...` ``） -2. `${CLAUDE_SKILL_DIR}` 被替换为 Skill 所在目录的绝对路径 -3. `${CLAUDE_SESSION_ID}` 被替换为当前会话 ID -4. 返回 `newMessages`（注入到对话流）+ `contextModifier`（修改权限上下文） - -`contextModifier`（第 776 行）做了三件事： -- **工具白名单注入**：将 `allowedTools` 合并到 `alwaysAllowRules.command` -- **模型切换**：`resolveSkillModelOverride()` 处理模型覆盖，保留 `[1m]` 后缀以避免 200K 窗口截断 -- **努力级别覆盖**：修改 `effortValue` +**优点**：共享主对话的完整上下文，可以引用之前的讨论。 +**缺点**：Skill 的中间过程会污染主对话的上下文。 ### Fork 模式（`context: fork`） -Skill 在**独立子 Agent** 中执行（`executeForkedSkill`，第 122 行）： +Skill 在独立子 Agent 中执行，拥有独立的 token 预算和工具权限。执行完成后只返回最终结果，中间过程不保留。 -1. `prepareForkedCommandContext()` 构建隔离的 Agent 定义和 Prompt -2. `runAgent()` 启动子 Agent 循环，拥有独立的 token 预算 -3. 通过 `onProgress` 回调报告工具使用进度 -4. 结果通过 `extractResultText()` 提取，子 Agent 的全部消息在提取后被释放（`agentMessages.length = 0`） -5. 最终通过 `clearInvokedSkillsForAgent()` 清理状态 +**优点**：不污染主对话，适合长时间运行的任务。 +**缺点**：子 Agent 看不到主对话的完整上下文。 -Fork 模式适用于需要强隔离的场景（如长时间运行的审查任务），避免污染主对话的上下文。 +**设计考量**：大多数 Skill 使用 inline 模式就够了——它们需要主对话的上下文。Fork 模式适合"重型"任务（如完整的代码审查），这些任务的中间步骤很多，留在主对话中会浪费大量 token。 -## 权限模型：Safe Properties 白名单 +## 权限模型 -`checkPermissions()`（第 433 行）实现了一个五层权限检查： +Skill 有五层权限检查： ``` -1. Deny 规则匹配（支持精确匹配和 prefix:* 通配符） - ↓ 未命中 -2. 远程 canonical Skill 自动放行（EXPERIMENTAL_SKILL_SEARCH + USER_TYPE === 'ant'） - ↓ 未命中 -3. Allow 规则匹配 - ↓ 未命中 -4. Safe Properties 白名单检查（skillHasOnlySafeProperties，第 911 行） - ↓ 有非安全属性 -5. Ask 用户确认（附带精确匹配和前缀匹配两条建议规则） +Deny 规则 → 远程 Skill 自动放行 → Allow 规则 → Safe Properties 白名单 → Ask 用户确认 ``` -**Safe Properties**（`SAFE_SKILL_PROPERTIES`，第 876 行）是一个包含 30 个属性名的白名单（覆盖 `PromptCommand` 和 `CommandBase` 两个类型的所有安全属性）。任何不在白名单中的**有意义的属性值**（排除 `undefined`、`null`、空数组、空对象）都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限。 +**Safe Properties 白名单**是一个包含 30 个安全属性名的列表。任何不在白名单中的属性都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限，而非默认允许。 -## Prompt 预算：1% 上下文窗口的截断策略 +## Prompt 预算 -Skill 列表注入 System Prompt 时有严格的字符预算（`prompt.ts`）： +Skill 列表注入 System Prompt 时有严格预算（约上下文窗口的 1%）： +1. 优先保留 bundled Skills 的完整描述 +2. 非 bundled Skills 按剩余预算均分 +3. 预算不足时只保留名称 -- **预算计算**：`contextWindowTokens × 4 chars/token × 1%`（约 8000 字符） -- **单条上限**：`MAX_LISTING_DESC_CHARS = 250` 字符（超出截断为 `…`） -- **Bundled Skills 不可截断**：它们始终保留完整描述，预算不足时只截断非 bundled 的 -- **降级策略**： - 1. 尝试完整描述 → 超预算？ - 2. Bundled 保留完整，非 bundled 均分剩余预算 → 每条描述低于 20 字符？ - 3. 非 bundled 仅保留名称 +**设计考量**：Skill 列表只是让 AI "知道有什么可用"。完整的 Skill Prompt 在 AI 选择后才加载，不需要全部塞进 System Prompt。 -`formatCommandsWithinBudget()`（`prompt.ts:70`）实现了这个三级降级。 +## 条件激活 -## 动态发现与条件激活 +带有 `paths` 模式的 Skill 在加载时不会立即可用。只有当被操作的文件路径匹配模式时，该 Skill 才被激活。 -### 基于文件路径的动态发现 +一个只在 `*.test.ts` 上激活的测试 Skill，平时完全不可见，只有当 AI 读取或编辑测试文件时才会出现。 -`discoverSkillDirsForPaths()`（`loadSkillsDir.ts:861`）在文件操作时触发： - -1. 从被操作的文件路径开始，**向上遍历**至 CWD（不包含 CWD 本身） -2. 在每层查找 `.claude/skills/` 目录 -3. 使用 `realpath` 去重，`git check-ignore` 过滤 gitignored 目录 -4. 按路径深度排序（**深层优先**），更接近文件的 Skill 优先级更高 - -### 条件激活（paths frontmatter） - -带有 `paths` 模式的 Skill 在加载时不会立即可用，而是存入 `conditionalSkills` Map。当被操作的文件路径匹配某个 Skill 的 paths 模式时（使用 `ignore` 库做 gitignore 风格匹配），该 Skill 才被**激活**——从 `conditionalSkills` 移入 `dynamicSkills`。 - -这意味着一个只在 `*.test.ts` 上激活的测试 Skill，平时完全不可见，只有当 AI 读取或编辑测试文件时才会出现。 +**设计洞察**：这解决了"Skill 泛滥"问题——项目可能定义了几十个 Skill，但一次对话通常只需要其中几个。条件激活让 Skill 按需出现，而不是全部堆在 AI 面前让它选择。 ## 使用频率排名 -`recordSkillUsage()`（`skillUsageTracking.ts`）使用指数衰减算法计算 Skill 排名分数： +Skill 的排序使用指数衰减算法：一周前的使用权重减半。这确保常用的 Skill 排在前面，但偶尔用的老 Skill 也不会完全沉底。 -``` -score = usageCount × max(0.5^(daysSinceUse / 7), 0.1) -``` +## 接下来 -- **7 天半衰期**：一周前的使用权重减半 -- **最低 0.1 保底**：避免老但高频使用的 Skill 完全沉底 -- **60 秒去抖**：同一 Skill 在 1 分钟内的多次调用只计一次，减少文件 I/O - -排名数据持久化在全局配置的 `skillUsage` 字段中。 - -## 远程技能加载（Experimental） - -通过 `EXPERIMENTAL_SKILL_SEARCH` feature flag 控制，支持从远程（AKI/GCS/S3）加载 `_canonical_` 格式的 Skill： - -1. `validateInput()` 中 `stripCanonicalPrefix()` 拦截 canonical 名称 -2. `executeRemoteSkill()`（第 970 行）从远程 URL 加载 SKILL.md -3. 支持 `gs://`、`https://`、`s3://` 等 URL 协议 -4. 内容经过 frontmatter 剥离、`${CLAUDE_SKILL_DIR}` 替换后直接注入 -5. 通过 `addInvokedSkill()` 注册到 compaction 保留状态，确保压缩后仍可恢复 -6. 远程 Skill 不经过 `processPromptSlashCommand`——无 `!command` 替换、无 `$ARGUMENTS` 展开 - -## 完整生命周期总结 - -``` -磁盘 SKILL.md - ↓ parseFrontmatter() - ↓ parseSkillFrontmatterFields() → 16 个字段 - ↓ createSkillCommand() → Command 对象 - ↓ 去重（realpath + seenFileIds） - ↓ 条件 Skill → conditionalSkills Map（等待路径匹配激活） - ↓ getSkillDirCommands() memoize 缓存 - ↓ getAllCommands() 合并 local + MCP - ↓ formatCommandsWithinBudget() → 截断后的 Skill 列表注入 System Prompt - ↓ AI 选择匹配的 Skill - ↓ SkillTool.validateInput() → 名称校验 + 存在性检查 - ↓ SkillTool.checkPermissions() → 五层权限检查 - ↓ SkillTool.call() → inline 或 fork 执行 - ↓ contextModifier() → 注入 allowedTools + model + effort - ↓ recordSkillUsage() → 更新使用频率排名 -``` +- **Hooks** — 理解 Skill 中可以使用的 Hook 机制 +- **MCP 配置** — 理解 MCP Skills 的来源 +- **自定义 Agent** — 理解 Skill 中指定的 Agent 定义