SKILL.md 正文该怎么写？它是路由器，而不是知识仓库（3/7）

SKILL.md 正文的写法：祈使句、步骤化、指向第三层

本课要建立的肌肉记忆

第 1 课我们知道了三层加载，第 2 课搞定了第一层（description）。今天讲第二层——SKILL.md 正文，它是 skill 被触发后 agent 读到的第一份完整指令，写法上有一条主线：

什么时候该拆

官方规范和业界的实践，收敛成了一条经验：

SKILL.md 正文    → 控制在 500 行 / ~5000 tokens 以内
单条规则的说明    → 超过 100 行就拆分
拆分去向         → references/（按需加载的文档）
                  scripts/（确定性执行的代码）
                  assets/（被复制进产出的物料）

一个成熟的 skill 往往就是这么执行的：正文保持精简，详细的格式模板、参考规范各放各的文件，正文里只说”格式见 references/xxx.md”——模板的内容不在正文里，只有指针在正文里。

正文的语气：祈使句，是指示 agent 去执行的

这是很多人会忽略、但显著影响执行稳定性的细节。对比两种写法：

❌ 第二人称 / 描述性
"你可能会遇到用户给的 CSV 编码不对的情况，
 这时候你或许应该先检测编码再读取……"

✅ 祈使句 / 指令性
"读取 CSV 前先检测编码：
 1. 用 chardet 探测前 8KB
 2. 非 UTF-8 时按探测结果转码
 3. 转码失败则向用户确认源编码"

为什么？正文是指令，不是建议。祈使句（动词开头、”做 X 然后做 Y”）去掉了主语和情态动词的歧义，agent 执行时不需要做”这句话是在建议我还是要求我”的推理。官方的 skill-creator 规范里这条是明文要求：

正文推荐的骨架

综合官方规范和 Anthropic 内部实践，一个高质量正文通常是这几段（顺序可变，按需取舍）：

1. 一句话定位——这个 skill 干什么（1-2 句，不重复 description）
2. 分步流程——编号步骤，每步一行决策 + 必要时指向 references 的链接
3. 边界与禁忌——明确”不要做什么”（Don’t…），防止 agent 过度发挥
4. Gotchas（坑点）——Anthropic 内部评出的”信息密度最高的部分”，放反直觉的、和默认行为冲突的规则
5. 快速参考表——命令、参数、格式的速查表

一条压轴原则：Don’t Railroad

Claude Code 团队经验里另一条反直觉的原则：别把 agent 钉死在铁轨上——说白了，就是别把每一步都写死。

因为 skill 可能会遇到我们没预料到的场景。如果精确写死每一步，遇到变体场景就会僵化出错；只有写成”目标 + 判断规则 + 坑点”，agent 能自己适配。这和带新人一个道理：好的 SOP 给检查清单，而不是逐字稿。

检验一下

正文总量 > 500 行 / ~5000 tokens  → 拆
单条规则 > 100 行                 → 拆
查阅型资料（对照表/字段说明）      → references/
确定性重复劳动                    → scripts/
被复制进产出的物料                → assets/