主题
08.2 SKILL.md 规范全解
SKILL.md 的全部 frontmatter 字段与语义。
读完你能做什么：精确控制一个 Skill 谁能调用、用什么工具、在什么上下文里运行。
一、基本结构
一个 Skill 是一个目录，核心是 SKILL.md：
text
.claude/skills/
└── my-skill/
├── SKILL.md # 必须：frontmatter + 指令正文
├── reference.md # 可选：参考资料（第 3 层，按需读）
├── scripts/ # 可选：脚本
│ └── run.sh
└── templates/ # 可选：模板
└── report.mdSKILL.md 本身：
markdown
---
name: my-skill
description: 这个技能做什么，以及什么时候用它
---
# 技能标题
这里是指令正文（第 2 层，被调用时加载）。二、Frontmatter 字段全表
| 字段 | 必填 | 作用 |
|---|---|---|
name | ✅ | 技能标识，决定斜杠命令名（/name）。小写+连字符 |
description | ✅ | 何时用这个技能。决定触发，最关键 |
disable-model-invocation | true 则只能手动 /name 调用，Claude 不会自动用 | |
user-invocable | false 则用户不能手动调，只能 Claude 自动调 | |
allowed-tools | 限制这个技能能用的工具 | |
context | fork 则在独立的分叉上下文里运行 | |
agent | 指定用哪个子代理运行这个技能 | |
argument-hint | 给用户的参数提示 |
字段集会随版本演进，以官方 skills 文档为准。
三、name 与 description
3.1 name
- 决定斜杠命令：
name: deploy→/deploy - 小写字母 + 连字符，不能含
:（保留给插件作用域） - 文件名不必和 name 一致（但建议一致，便于查找）
3.2 description
这是整个 Skill 里最重要的一行。 Claude 靠它决定要不要自动调用这个技能。
markdown
---
name: api-conventions
description: API design patterns for this codebase
---太简略的 description 会导致技能该触发时不触发。完整的写法见 08.3 编写高触发率的 description。
四、调用控制：谁能触发
4.1 两个维度
text
Claude 能自动调用？ 用户能手动 /name 调用？
默认 ✅ ✅
disable-model-invocation: true ❌ ✅（只能手动）
user-invocable: false ✅ ❌（只能自动）4.2 disable-model-invocation: true
用于你不希望 Claude 擅自触发的技能 —— 通常是有副作用的（部署、提交、发消息）：
markdown
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
# 部署到生产
（只有你明确 /deploy 才会执行，Claude 不会自作主张部署）4.3 user-invocable: false
用于纯粹给 Claude 参考、不该被用户当命令的技能，比如一段自动生效的领域知识。
五、allowed-tools：限制工具
约束这个技能能用哪些工具，缩小它的能力面：
markdown
---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---
# 提交改动
只用 git add / commit / status，不碰其他任何工具。这个技能即使运行，也只能跑这三类 git 命令 —— 一道额外的安全边界。
也可以约束到脚本：
markdown
---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---${CLAUDE_SKILL_DIR} 是技能目录的路径变量，见 08.4。
六、context: fork：隔离运行
让技能在独立的分叉上下文里运行，不污染主会话：
markdown
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
# 深度研究
（在分叉上下文里做大量搜索和阅读，只把结论带回主会话）用途：技能会产生大量中间内容（搜索、读文件）时，用 context: fork 把这些噪音隔离，主会话只收到最终结果。这和子代理的上下文隔离是同一思路（见 06.4）。
agent 字段指定用哪个子代理来跑，比如 Explore（只读搜索代理）。
七、argument-hint：参数提示
给用户提示这个技能接受什么参数：
markdown
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
argument-hint: <issue-number>
---
# 修复 issue
修复编号为 $ARGUMENTS 的 GitHub issue。用户输入 /fix-issue 234 时，234 作为参数传入。
八、传参给 Skill
8.1 位置参数
技能正文里可以引用传入的参数：
markdown
---
name: migrate-component
description: Migrate a component from one framework to another
argument-hint: <component-path> <target-framework>
---
# 组件迁移
把 $1 从当前框架迁移到 $2。调用：/migrate-component src/Button.vue react
8.2 技能链式调用（v2.1.199+）
多个技能可以链在一起，后面的文字作为参数传给每一个：
text
> /skill-a /skill-b 处理这批数据最多链 6 个技能。开头列出的技能都会加载，尾部文字传给每一个。
九、正文写法
9.1 结构
正文就是给 Claude 的指令。用清晰的结构：
markdown
# 技能名
## 什么时候用（可选，帮 Claude 判断）
## 步骤
1. ...
2. ...
## 约束
- ...
## 输出格式
...9.2 引用第 3 层资源
正文里可以指引 Claude 去读支持文件：
markdown
# API 设计
设计新接口前，先阅读 `reference.md` 了解本项目的 API 规范。
@reference.md@ 语法或直接指示 Claude 用 Read 工具读取。这些文件是第 3 层，只在需要时才进上下文（见 08.4）。
十、一个用全字段的示例
markdown
---
name: pr-summary
description: 总结一个 PR 的改动，生成结构化的评审摘要。当用户要审查 PR 或需要 PR 变更概览时使用。
context: fork
agent: Explore
allowed-tools: Bash(gh *) Read Grep Glob
argument-hint: <pr-number>
---
# PR 摘要
为 PR #$1 生成评审摘要。
## 步骤
1. 用 `gh pr view $1 --json ...` 获取 PR 元信息
2. 用 `gh pr diff $1` 获取改动
3. 分析改动，按 reference.md 的评审维度整理
## 输出
- 改动概述（3 句以内）
- 按文件的关键变更
- 需要 reviewer 特别注意的风险点
- 建议：approve / request changes / 需讨论
@reference.md这个技能：在分叉上下文运行（不污染主会话）、用 Explore 代理、只能用 gh 和只读工具、接受 PR 号参数、引用外部评审规范。
十一、创建和管理
text
> /reload-skills 改完文件后重新加载
> /skills 查看所有技能及其 token 占用Claude Code 还有专门的技能创建助手（skill-creator），能帮你从零创建、优化技能，甚至测试触发准确率。