Anthropic 公布的 SKILL.md Body 编写规则 5 条

Skill 只需要两行 YAML frontmatter 就能创建。但 body 怎么写，直接决定了输出质量的天花板。

交叉比对 Anthropic 官方文档和工程博客后，我把运行机制和 body 编写原则整理成了五条规则。起因是我自己写的 Skill 偶尔加载失败，趁假期从头做了一遍验证。

不了解 Skill 执行顺序，body 设计就会跑偏

Skill 不会像 prompt 那样直接注入对话。启动时加载到系统提示词里的只有 name 和 description。

当用户请求与 description 匹配时，Claude 会通过 Bash 工具读取 SKILL.md 全文，然后在需要时才加载引用文件和脚本。Anthropic 工程博客把这个结构叫做”渐进式披露（progressive disclosure）”。

• 第 1 阶段：仅元数据（name + description）常驻加载，每个 Skill 约 100 token
• 第 2 阶段：SKILL.md body 仅在匹配时进入上下文窗口
• 第 3 阶段：scripts 和 references 文件夹中的文件在实际引用时加载
• 脚本执行时，代码本身不进入上下文，只有输出结果被消耗

不理解这个结构，body 里就会塞满多余信息，真正重要的内容反而被遗漏。

在 body 里写”什么时候用”就是浪费 token

很多人在 body 里加了”When to Use This Skill”章节。亲手试过之后发现完全没用, , body 是 Skill 已经被触发之后才读取的。

“什么时候用”只能写在 description 里。Anthropic 官方 skill-creator 仓库也明确了这一点。

• description 是唯一的触发入口（body 里写了 Claude 也不会参考）
• description 上限 1,024 字符，用第三人称写能提高被发现的准确率
• body 里该放的是任务规则、操作流程和预期输出格式
• 把”本 Skill 适用于……”这类句子从 body 中删除

body 控制在 500 行以内，其余内容拆分出去

Anthropic 指南的开头就说：上下文窗口是共享资源。Skill 加载后，要和对话记录、系统提示词分享 token。

官方建议 body 控制在 500 行以下，详细内容拆分到独立文件。SKILL.md 充当目录，引用文件充当各章节。

• body 500 行以下（Anthropic best practices 明确标注）
• 引用文件从 SKILL.md 只链接一层深度
• 超过两层嵌套引用时，Claude 可能只用 head -100 读取部分内容
• 超过 100 行的引用文件在开头加目录

假设 Claude 已经很聪明来写

在 body 里解释 PDF 是什么，纯粹浪费 token。Anthropic 指南反复强调一个原则：

“Claude 已经知道的东西就不要写。”

50 token 的精简代码示例比 150 token 的概念解释性能更好。在同样的 PDF 提取任务中，精简 body 比冗长 body 的准确率明显更高。

• 每句话都问自己：“这段说明值不值这些 token？”
• 用代码示例 + 预期输出格式代替概念说明
• 把任务自由度分成三级（高/中/低）来调节指令强度
• 数据库迁移类任务自由度设低，代码审查设高

在 body 中嵌入验证循环才能提升质量

执行 → 验证 → 修复 → 再验证。这是 Anthropic 推荐的 body 模式中最实用的部分。在 body 里加入检查清单后，Claude 跳步的情况明显减少。

官方指南还指出，“MUST filter”这样的强表达比”always filter”的遵循率更高。

• 复杂任务用检查清单格式列出步骤
• 在 body 中包含脚本验证 → 错误修复 → 再验证循环
• 用”MUST”替代”always”能提高 Claude 的遵循率
• 错误信息写得越具体，Claude 自动修复的能力越强

核心要点

description 决定”何时触发”，body 决定”如何执行”。两者职责一旦混淆，Skill 既不会正常触发，输出质量也会下降。

好的 Skill 就像好的入职文档。默认读者已经很聪明的文档，才是最有力量的。