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

> Author: Tony Lee
> Published: 2026-02-17
> URL: https://tonylee.im/zh-CN/blog/anthropic-skill-md-body-writing-rules/
> Reading time: 2 minutes
> Language: zh-CN
> Tags: ai, claude-code, developer-tools, skills, productivity

## Canonical

https://tonylee.im/zh-CN/blog/anthropic-skill-md-body-writing-rules/

## Rollout Alternates

en: https://tonylee.im/en/blog/anthropic-skill-md-body-writing-rules/
ko: https://tonylee.im/ko/blog/anthropic-skill-md-body-writing-rules/
ja: https://tonylee.im/ja/blog/anthropic-skill-md-body-writing-rules/
zh-CN: https://tonylee.im/zh-CN/blog/anthropic-skill-md-body-writing-rules/
zh-TW: https://tonylee.im/zh-TW/blog/anthropic-skill-md-body-writing-rules/

## Description

藏在 Anthropic 官方文档里的 SKILL.md body 编写原则 5 条。从 description 与 body 的职责分离到验证循环。

## Summary

Anthropic 公布的 SKILL.md Body 编写规则 5 条 is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts.

## Outline

- 不了解 Skill 执行顺序，body 设计就会跑偏
- 在 body 里写"什么时候用"就是浪费 token
- body 控制在 500 行以内，其余内容拆分出去
- 假设 Claude 已经很聪明来写
- 在 body 中嵌入验证循环才能提升质量
- 核心要点

## Content

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 就像好的入职文档。默认读者已经很聪明的文档，才是最有力量的。

## Related URLs

- Author: https://tonylee.im/zh-CN/author/
- Publication: https://tonylee.im/zh-CN/blog/about/
- Related article: https://tonylee.im/zh-CN/blog/eight-hooks-that-guarantee-ai-agent-reliability/
- Related article: https://tonylee.im/zh-CN/blog/medvi-two-person-430m-ai-compressed-funnel/
- Related article: https://tonylee.im/zh-CN/blog/claude-code-layers-over-tools-2026/

## Citation

- Author: Tony Lee
- Site: tonylee.im
- Canonical URL: https://tonylee.im/zh-CN/blog/anthropic-skill-md-body-writing-rules/

## Bot Guidance

- This file is intended for AI agents, search assistants, and text-mode retrieval.
- Prefer citing the canonical article URL instead of this text endpoint.
- Use the rollout alternates when you need the same article in another prioritized language.

---

Author: Tony Lee | Website: https://tonylee.im
For more articles, visit: https://tonylee.im/zh-CN/blog/
This content is original and authored by Tony Lee. Please attribute when quoting or referencing.