如果你每次都要重新告诉 Claude 一遍“应该先做什么、调用哪些工具、最后怎样检查”，那这套知识就值得被写成 Skill。
Skill 到底是什么 #
Skill 是一个目录。目录里放着一份主要指令，以及可选的脚本、参考文档和资源文件，用来教 Claude 稳定地完成某一类任务。
一个最小的 Skill 只有一个文件：
weekly-report/
└── SKILL.md一个更完整的 Skill 可以长这样：
weekly-report/
├── SKILL.md # 必需：核心指令和 YAML frontmatter
├── scripts/ # 可选：确定性的校验或处理脚本
│ ├── collect_metrics.py
│ └── validate_report.sh
├── references/ # 可选：按需阅读的详细资料
│ ├── style-guide.md
│ └── metric-definitions.md
└── assets/ # 可选：模板、字体、图标等资源
└── report-template.md这里有三个容易混淆的概念：
- Skill 提供“应该怎样做”的知识和流程。
- MCP 提供“可以调用什么”的连接能力和实时数据。
- 脚本 把需要精确执行的步骤交给代码，而不是交给模型猜。
可以把 MCP 想成厨房里的工具和食材，把 Skill 想成菜谱。只有厨房没有菜谱，用户知道“能做什么”，却不一定知道“怎样稳定地做出来”；只有菜谱没有工具，流程又没有真实的数据和执行能力。
先别写代码，先写用例 #
官方指南给出的第一步不是创建目录，而是列出 2-3 个具体用例。每个用例至少回答四个问题：
- 用户想完成什么结果？
- 触发 Skill 的请求会怎么说？
- 中间有哪些步骤和工具调用？
- 最后怎样判断任务成功？
例如，不要只写“做一个项目管理 Skill”，而要写成：
用例：规划下一轮迭代
触发：用户说“帮我规划这个 sprint”或“创建本轮任务”
步骤：
1. 读取当前项目状态
2. 分析团队容量和历史完成量
3. 给任务排序并说明取舍
4. 创建任务、标签和估时
结果：项目里出现一组可执行、彼此关联的 sprint 任务从用例出发，通常会落入三类：
文档和资产生成 #
例如生成报告、演示文稿、网页、设计稿或代码。这类 Skill 的重点是把风格规范、模板和交付前检查清单固化下来。
工作流自动化 #
例如创建 Skill、整理数据或完成一套项目初始化流程。这类 Skill 通常包含明确的步骤、验证门和失败后的处理方式。
MCP 增强 #
例如把错误监控、代码仓库和工单系统串起来完成一次代码审查。这类 Skill 的价值不只是“会调用工具”，而是知道工具应该以什么顺序调用、哪些结果需要传给下一步，以及遇到错误时如何停下来。
Skill 最重要的入口：frontmatter #
SKILL.md 开头必须有 YAML frontmatter。它是 Claude 判断“什么时候应该加载这个 Skill”的第一层信息：
---
name: weekly-report
description: Generate a weekly engineering report from repository activity and project metrics. Use when the user asks for a weekly report, sprint summary, or engineering status update.
---name 和 description 都不是装饰：
name必须使用 kebab-case，不能有空格、大写或下划线，并且要和目录名一致。- 文件名必须严格写成
SKILL.md，大小写也不能改。 description必须同时说明 Skill 做什么、什么时候使用。- 描述应该包含用户真实会说的触发词，而不是只写内部实现名。
description最长不超过 1024 个字符，不能放 XML 标签。- Skill 名称不要使用
claude或anthropic作为前缀；这类名称属于保留范围。
一个模糊的描述：
description: Helps with projects.一个能帮助触发判断的描述：
description: Create weekly engineering reports from Git history, issue trackers, and team metrics. Use when the user asks for a weekly report, sprint summary, project status, or release review.前者没有告诉模型任务边界，后者同时给出了能力、输入来源和用户可能使用的表达。
渐进式披露：不要把所有东西都塞进 SKILL.md #
Skill 的设计核心是 progressive disclosure，也就是渐进式披露。可以把它理解成三层加载：
- frontmatter：始终可见，只放“这个 Skill 是什么、什么时候用”。
- SKILL.md 正文：判断相关后加载，放核心流程和关键规则。
- 链接文件：只有执行需要时才读取，例如 API 细节、长篇规范和示例。
因此，SKILL.md 应该像操作手册，而不是知识库全文。稳定的主流程放在正文，具体的 API 参数、长示例和边缘情况放到 references/，并在正文中明确告诉 Claude 什么时候读取它。
## 生成报告
1. 先读取 `references/metric-definitions.md`，确认指标含义。
2. 收集数据并生成初稿。
3. 运行 `scripts/validate_report.py`。
4. 只有校验通过后，才写入最终文件。这样做既减少上下文负担，也让 Skill 更容易和其他 Skill 组合使用。
指令要像流程，不要像口号 #
“请认真处理”“完成后检查一下”都太模糊。好的指令应该让执行顺序、输入、成功条件和失败处理都可见。
## 生成报告
### 第一步：收集数据
调用项目数据工具，获取最近一个周期的提交、问题和发布记录。
### 第二步：生成初稿
按照 `references/style-guide.md` 的章节顺序生成报告。缺失数据必须标记为“暂无数据”，不要自行补写数值。
### 第三步：校验
运行：
```bash
python scripts/validate_report.py --input report.md
```
如果校验失败，先修复缺失章节、格式不一致或指标错误，再进入最终化步骤。关键规则应该靠近相关步骤。涉及外部工具时，最好写清楚：
- 工具调用的先后顺序；
- 上一步的哪些字段会传给下一步；
- 每一步的验证条件；
- 调用失败时是重试、回滚，还是暂停并询问用户。
能用脚本确定性完成的检查，就不要只写成一句自然语言要求。代码的判断比模型对“请正确校验”的理解更稳定。
测试 Skill：先测一个难题，再扩展覆盖面 #
Skill 不是写完 SKILL.md 就结束。官方建议先拿一个有代表性的、比较难的任务反复迭代，找到稳定成功的流程，再把它推广成通用指令。这样比一开始铺开几十个测试用例更容易得到有效反馈。
完整测试可以分成三层。
1. 触发测试 #
确认应该触发的表达会触发，换一种说法也能触发，而无关请求不会误触发。
应该触发：帮我做本周工程周报
应该触发：总结一下这轮迭代的研发状态
不应该触发：帮我写一个 Python 快排如果 Skill 总是不触发，通常是 description 太泛，或者缺少用户实际使用的同义表达；如果什么都触发，则需要收窄范围并补充负向边界。
2. 功能测试 #
功能测试关心最终结果是否正确：输出结构是否完整，工具调用是否成功，错误是否被处理，边界情况是否覆盖。
3. 基线和性能对比 #
不要只问“有 Skill 时感觉是不是更好”。可以把相同任务分别跑一遍，比较：
- 需要多少轮对话和工具调用；
- 失败或重试了几次；
- 用户需要补充多少次说明；
- 消耗了多少 token；
- 多次运行的结构和质量是否稳定。
触发率、工具调用次数和失败率可以作为量化指标；“用户不需要提醒下一步”“新用户第一次就能完成”则是同样重要的定性指标。指南里的数字更适合作为目标和起点，不应被误解成适用于所有 Skill 的硬性标准。
五种常见工作流模式 #
顺序编排 #
适合步骤严格依赖前一步结果的任务：创建账号、配置支付、创建订阅、发送欢迎邮件。每一步都要写清楚依赖和验证点，必要时提供回滚方式。
多 MCP 协同 #
适合跨服务流程，例如从设计工具导出资源，上传到云盘，再创建开发任务并发送通知。重点是划分阶段、传递中间数据，并在阶段切换前做验证。
迭代精炼 #
适合报告、代码或设计稿这类“检查一次后还能变好”的输出。典型流程是初稿、质量检查、修复、重新校验，直到达到预先定义的质量门槛，同时要定义什么时候停止迭代。
上下文感知的工具选择 #
同一个目标可能对应不同工具。例如大文件放云存储，协作文档放文档系统，代码放 Git 仓库，临时产物留在本地。Skill 应该写出决策依据和备选路径，并向用户解释为什么选择了某个位置。
领域知识驱动 #
在金融、医疗、合规等场景，工具调用前可能必须完成权限、风险或合规检查。Skill 的价值是把“先判断能不能做，再执行”的治理逻辑嵌入流程，并留下审计记录。
常见故障怎么排查 #
上传失败 #
先检查目录里是否存在大小写完全正确的 SKILL.md，frontmatter 是否有成对的 ---，name 是否符合 kebab-case。Skill 目录内部不要放 README.md；如果需要给 GitHub 人类读者写说明，应放在仓库根目录。
Skill 不触发或触发过多 #
优先修改 description，不要先把正文写得更长。补充真实触发词、明确任务边界，必要时写出“不用于哪些相似请求”。
MCP 已连接但调用失败 #
先不使用 Skill，直接测试 MCP 是否能独立完成同一个调用。如果独立调用也失败，问题在连接、鉴权、权限或工具名；只有 MCP 单独正常、组合流程失败时，才回头检查 Skill 的步骤和参数传递。
指令加载了却没有被遵守 #
把关键规则提前，减少冗长叙述，改用编号步骤和明确条件。对关键校验，优先用脚本实现。与其写“请正确检查项目名”，不如写成“调用 create_project 前确认项目名非空，至少有一名成员，开始日期不能早于今天”。
上下文过大 #
把长文档移动到 references/，让 SKILL.md 只保留执行必需的内容。一个 Skill 不应该试图囊括所有知识；同时启用太多 Skill 也会增加判断和上下文成本。
分发前的最小检查清单 #
在打包前，可以按下面的顺序过一遍：
- 是否已经定义 2-3 个具体用例？
- 目录是否使用 kebab-case？
- 是否存在拼写和大小写都正确的
SKILL.md？ - frontmatter 是否包含同时说明“做什么”和“什么时候用”的描述？
- 正文是否给出了可执行步骤、示例和错误处理？
- 详细资料是否被移到了
references/，并且链接清楚？ - 是否测试了明显请求、改写后的请求和无关请求？
- 功能测试和工具集成测试是否通过？
- 是否在真实对话中观察过误触发和漏触发？
- 是否记录版本并收集用户反馈？
分发层面，个人用户可以把 Skill 文件夹压缩后上传，也可以放进 Claude Code 的 Skill 目录；团队则可以通过组织级配置统一部署和更新。对于应用程序和自动化代理，指南还介绍了通过 API 管理 Skill 的方式。这里的 API 和产品界面会随版本变化，实际接入时应以当前官方文档为准。
最后：Skill 是一份会生长的操作手册 #
Skill 的本质不是“把提示词保存成文件”，而是把一套可重复的工作方法变成可组合、可测试、可迭代的资产。
一个实用的闭环是：
具体用例
-> 明确触发条件和成功标准
-> 写最小 SKILL.md
-> 用一个困难任务迭代
-> 做触发、功能和基线测试
-> 在真实对话中收集失败案例
-> 更新描述、步骤和验证脚本如果你已经在某件事上形成了稳定流程，下一次不妨问自己：这套流程是不是还要在每个新对话里重新解释？如果答案是“是”，那它可能已经到了应该被写成 Skill 的时候。
本文根据《The Complete Guide to Building Skills for Claude》整理和改写。原 PDF 为 2026 年 1 月版本。