第20章 · 技能系统：从入门到精通

第20章 · 技能系统：从入门到精通

Claude Code的技能（Skill）系统是其扩展能力的核心，允许用户和开发者将可复用的工作流封装为标准化的Markdown文件。源码分析揭示了一个远比文档公开内容更为复杂和强大的系统。

20.1 技能的本质：一个Markdown文件

一个技能的最小形态是一个包含YAML frontmatter的Markdown文件，存放在skill-name/SKILL.md路径下：

---
description: 代码审查助手
when_to_use: 当用户要求审查代码时
allowed-tools: Read, Grep, Glob
---
# 代码审查指南
请按以下步骤审查代码：
1. 检查代码风格...
2. 检查安全漏洞...

当模型调用该技能时，Markdown内容会被注入到对话中，作为模型的"操作手册"指导后续行为。

20.2 Frontmatter全字段解析（13+字段）

源码loadSkillsDir.ts中的frontmatter解析器支持以下全部字段：

核心字段：

• description — 技能描述，模型用此判断何时调用
• when_to_use — 触发条件描述，是自动调用的关键
• allowed-tools — 工具白名单，限制技能可使用的工具范围
• arguments — 参数定义，支持$arg_name变量替换

执行控制：

• context — 执行模式，inline（默认）或fork
• agent — 指定执行Agent类型
• effort — 努力级别（low/medium/high）
• model — 覆盖使用的模型（如sonnet/haiku/opus）

安全与权限：

• disable-model-invocation — 禁止模型自动调用，仅手动触发
• user-invocable — 是否可由用户通过/skill命令直接调用
• hooks — 执行前后的钩子脚本
• paths — 路径限制，技能只能操作指定路径下的文件

20.3 两种执行模式：Inline与Fork

技能执行分为两种截然不同的模式：

Inline模式（默认）：技能内容直接展开到当前对话中，模型在同一上下文中继续执行。适合轻量级指导性技能，如代码规范、写作风格指南。

Fork模式：创建一个完全隔离的子Agent，拥有独立的Token预算和上下文窗口。子Agent执行完毕后，结果被提取回主会话。适合重型任务，如完整的代码生成、多步骤工作流。

Inline:  用户 → [技能内容注入] → 模型继续在同一上下文中工作
Fork:    用户 → [创建子Agent] → 子Agent独立工作 → 结果返回主会话

Fork模式的关键实现细节（来自SkillTool.ts）：

• 子Agent的Token预算独立于主会话
• 工具白名单由allowed-tools严格控制
• 执行结果通过ContentBlock数组返回
• 失败不会影响主会话状态

20.4 技能发现与加载机制

loadSkillsDir.ts实现了多层级的技能发现：

加载优先级（从高到低）：
1. bundled    — 内置技能（29个，随二进制分发）
2. managed    — 企业策略管理（~/.config/.claude/skills）
3. user       — 用户级（~/.claude/skills）
4. project    — 项目级（.claude/skills）
5. plugin     — 插件携带的技能
6. mcp        — MCP服务器暴露的技能

加载器的智能行为：

• 符号链接去重：通过realpath()检测软链接，避免同一技能被加载多次
• GitIgnore感知：跳过.gitignore中排除的目录
• Token预算控制：技能列表占上下文窗口的1%上限
• Truncation策略：内置技能永不截断，用户技能描述限制250字符

20.5 SkillTool执行流程

当模型或用户调用一个技能时，SkillTool.ts（超过1000行）执行以下完整流程：

1. 验证  → 检查技能是否存在、是否可调用、是否被禁用
2. 权限  → Deny规则 → Allow规则 → Safe属性检测 → 询问用户
3. 参数  → $arg_name替换、${CLAUDE_SKILL_DIR}等特殊变量
4. 钩子  → 执行pre-hook（如有）
5. 执行  → Inline（注入内容）或Fork（创建子Agent）
6. 钩子  → 执行post-hook（如有）
7. 返回  → 内容块返回给模型继续处理

20.6 安全模型：Safe与Unsafe属性

技能权限系统区分"安全"和"不安全"属性：

安全属性（自动允许，无需用户确认）：

• name、description、version
• when_to_use、arguments、paths
• user-invocable、disable-model-invocation

不安全属性（需用户明确授权）：

• allowed-tools — 能力扩展
• hooks — 外部脚本执行
• context: fork — 隔离执行
• model — 模型覆盖
• effort — 努力级别覆盖

对于MCP来源的技能，额外限制：禁止内联Shell执行（!`command`语法被阻止），防止不受信任的远程技能执行任意命令。

20.7 29个内置技能

源码skills/bundled/目录揭示了29个内置技能，涵盖开发全流程：

20.8 变量替换系统

技能Markdown中支持多种动态变量：

• $arg_name — 用户传入的参数（在frontmatter arguments中定义）
• ${CLAUDE_SKILL_DIR} — 技能文件所在目录的绝对路径
• ${CLAUDE_SESSION_ID} — 当前会话ID
• !`command` — 内联Shell执行（仅本地技能）

内联Shell的用例：技能可以在Markdown中嵌入Shell命令，执行结果会替换到内容中。例如：

当前分支是 !`git branch --show-current`，
最近的提交是 !`git log --oneline -3`

20.9 系统提示词集成

技能在系统提示词中的呈现方式（来自constants/prompts.ts）：

<available_skills>
<skill>
  <name>commit</name>
  <description>智能Git提交...</description>
</skill>
...
</available_skills>

模型根据when_to_use字段判断何时自动调用。这意味着技能描述的质量直接决定了自动触发的准确率——这是编写高效技能的关键。

20.10 创建自定义技能指南

基于源码分析，创建高质量技能的最佳实践：

第一步：定义触发条件

---
description: React组件生成器
when_to_use: 当用户要求创建React组件、页面或UI元素时
allowed-tools: Write, Read, Glob, Bash
arguments: component_name
---

第二步：编写操作手册（Markdown正文）

• 清晰的步骤说明
• 具体的代码模板
• 质量检查清单
• 错误处理指南

第三步：选择执行模式

• 简单指导 → context: inline
• 复杂生成 → context: fork（独立Token预算）

第四步：放置到正确位置

• 个人通用 → ~/.claude/skills/my-skill/SKILL.md
• 项目专用 → .claude/skills/my-skill/SKILL.md
• 团队共享 → 通过Plugin分发

20.11 技能与插件的关系

技能是插件系统的核心组成部分。一个Plugin可以包含：

• 多个技能（skills/目录）
• MCP服务器配置
• 工具定义
• 安装钩子

插件中的技能继承插件的权限模型。官方Marketplace的插件获得更宽松的信任级别（isOfficialMarketplace标志），其技能的unsafe属性处理更为宽松。

20.12 MCP技能：远程技能分发

MCP服务器可以通过Prompts协议暴露技能，实现远程技能分发：

MCP Server → exposes prompts → Claude Code loads as skills → user invokes

MCP技能的特殊限制：

• 禁止内联Shell执行
• 不信任的MCP技能需要用户逐一授权unsafe属性
• 源码中存在实验性的"canonical skills"机制（_canonical_前缀），用于Anthropic官方远程技能分发

20.13 /skillify：AI自动创建技能

内置的skillify技能是一个"元技能"——它让Claude分析当前会话，自动生成一个新的可复用技能文件。这实现了技能的自举：用户不需要手动编写frontmatter，Claude会根据对话上下文推断出最佳的触发条件、工具白名单和操作流程。

20.14 技能系统的设计哲学

从源码可以看出几个核心设计理念：

1. Markdown即程序：用最简单的格式承载复杂的工作流逻辑
2. 渐进式复杂度：从简单的文本指导到Fork子Agent，复杂度按需递增
3. 安全默认：unsafe属性需要明确授权，MCP技能受额外限制
4. 生态开放：本地文件、插件、MCP三条分发渠道并存
5. AI原生：技能不是传统的脚本，而是"给AI的操作手册"