04 Skill 技能系统——Agent 的按需加载模块

原文：Extend Claude with Skills

什么是 Skill

Skill 是一个包含 SKILL.md 文件的文件夹，里面写着特定任务的最佳实践和指令。它是 Agent 的按需加载模块——不是每次会话都占用上下文，而是在需要时才加载。

类比：Skill 像是 npm 包或 Python 模块。你在 package.json 里声明依赖，但代码只在 import 时才加载。Skill 的 description 就像模块的 README——系统根据它判断何时加载。

两种类型的 Skill

参考型（Reference）

提供知识，Claude 在工作中参考它：

---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use kebab-case for URL paths
- Use camelCase for JSON properties

任务型（Task）

定义可执行的工作流，用 /name 触发：

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

存放位置与优先级

位置	适用范围	优先级
企业管理策略	组织所有人	最高
`~/.claude/skills/`	你的所有项目	高
`.claude/skills/`	当前项目	中
Plugin 的 `skills/`	安装了插件的地方	低

同名 Skill 高优先级覆盖低优先级。Plugin Skill 有命名空间（plugin:skill），不会冲突。

关键 Frontmatter 字段

字段	作用	重要程度
`name`	显示名和 `/` 命令名	推荐
`description`	告诉 Claude 何时使用（语义匹配）	核心
`disable-model-invocation`	`true` = 只能手动触发	有副作用的流程必须设
`context: fork`	在独立 SubAgent 中运行	大量文件操作时用
`allowed-tools`	限制可用工具	安全限制
`agent`	`context: fork` 时用哪个 SubAgent 类型	搭配 fork 用

Description 是灵魂

Claude 根据 description 的语义匹配来决定何时加载 Skill。写得好的 description 应该：

覆盖用户可能说的各种表达方式
有区分度（避免和其他 Skill 重叠）
像搜索引擎关键词一样思考

好例子："Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks 'how does this work?'"

高级特性

动态注入（ `!`command ）

在 Skill 内容发送给 Claude 之前，先执行 shell 命令并替换结果：

## Pull request context
- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`

变量替换

$ARGUMENTS — 用户传入的参数
$ARGUMENTS[0], $1 — 按位置访问参数
${CLAUDE_SESSION_ID} — 当前会话 ID
${CLAUDE_SKILL_DIR} — Skill 所在目录

支持文件

Skill 目录可以包含多个文件：

my-skill/
├── SKILL.md           ← 主指令（必须）
├── reference.md       ← 详细参考（按需加载）
├── examples/
│   └── sample.md
└── scripts/
    └── helper.py      ← 可执行脚本

Claude Code 内置 Skill

Skill	作用
`/batch <instruction>`	大规模并行改造，自动拆分任务+开 PR
`/claude-api`	加载 Claude API 参考文档
`/debug [description]`	排查当前会话问题
`/loop [interval] <prompt>`	定时重复执行某个 prompt
`/simplify [focus]`	审查最近修改的代码质量

知识检测

概念理解题

Skill 的 description 是”语义匹配”而非”精确匹配”——这意味着什么？有什么优缺点？
disable-model-invocation: true 为什么对有副作用的工作流（如部署）很重要？如果不设会怎样？
context: fork 让 Skill 在 SubAgent 中运行。为什么要这样做？直接在主会话里运行有什么问题？

应用题

你要为你的 Web 项目创建一个 /release Skill。它需要：跑测试、bumping 版本号、构建、发布到 npm registry、创建 Git Tag。写出这个 SKILL.md 的框架（frontmatter + 步骤大纲）。
你有两个 Skill：一个叫 code-review，一个叫 security-audit。两者的 description 都提到了”检查代码质量”。会发生什么？怎么解决？

迁移思考题

OpenClaw 的 Skill 格式和 Claude Code 几乎相同。但 OpenClaw 的 Skill 触发是通过 agent 在对话中语义匹配 description，或者在 cron prompt 中显式引用。对比两者的触发机制，哪个更灵活？

参见

03-扩展体系总览 — Skill 在整体扩展架构中的位置
07-SubAgent-子代理系统 — context: fork 和 SubAgent 的关系
SlipBox 相关：Skill、Claude Code

参考答案

1. 语义匹配的含义

Claude Code 用 LLM 判断用户意图和 description 的相关性，不是关键词精确匹配。优点：灵活，用户用不同表达方式都能触发正确的 Skill。缺点：不可预测——两个 description 相似的 Skill 可能互相干扰，且无法保证 100% 命中率。

2. disable-model-invocation 的重要性

如果不设，Claude 可能在它”觉得合适”的时候自动触发部署 Skill——比如你说”准备发布”时 Claude 可能理解为”执行部署”而不是”准备清单”。对有副作用的工作流（部署、数据迁移、发邮件），必须设 disable-model-invocation: true，确保只有你显式 /deploy 时才触发。

3. context: fork 的原因

Skill 默认在主会话中加载，内容会占主上下文。如果 Skill 涉及大量文件读取（如代码审查要读 50 个文件），直接在主会话运行会把上下文撑满。context: fork 在 SubAgent 中运行，读取的 50 个文件只存在于 SubAgent 上下文，主会话只收到摘要结果。

4. /release Skill 框架

---
name: release
description: Build and release the package to npm registry
disable-model-invocation: true
---
## Release Workflow
1. Run `npm test` — 全部通过才继续
2. Bump version: `npm version patch/minor/major`
3. Build: `npm run build`
4. Publish: `npm publish`
5. Push tag: `git push origin v{version}`
6. 输出发布摘要（版本号、registry 链接、changelog）

5. 两个 Skill 的 description 重叠

Claude 会根据当前上下文选它认为更相关的，但可能选错或两个都不触发。解决：(1) 让 description 有明确区分度——code-review 强调”代码质量、可读性、最佳实践”，security-audit 强调”安全漏洞、注入攻击、权限问题” (2) 用 disable-model-invocation: true 让两者都只能手动触发 (3) 用 skill-creator 的 eval 功能测试触发准确率。

6. 两者触发机制对比

Claude Code 更灵活——Skill 在每次请求时都有机会被语义匹配触发，且支持 /name 手动调用。OpenClaw 的 Skill 在 session 开始时做快照，后续不再重新评估（除非启用 watch），更稳定但灵活度较低。Claude Code 的 disable-model-invocation 提供了”只手动触发”的选项，是灵活性和可控性之间的平衡。