写好 Skill 的两个要点：description 当触发器，正文当路由器

其一，写好description；

其二，正文做好路由。

先说第一个要点：写好desc。

正文写得再精彩，desc写歪了，skill也很难被触发。desc不是写给人看的摘要（summary），而是写给模型看的触发器（trigger）。desc描述的不只是这个skill是干嘛的，更重要的是什么时候被触发。

Claude Code团队的原话是：The description field is not a summary, it's a description of when to trigger this skill.

我们切换一下视角，就非常容易理解了：agent眼中，skill就是desc（见上篇，渐进式披露），它拿着这段话，和用户的消息做匹配，决定skill是否触发。

所以，写desc，我们实际上是在写一段[给模型的路由规则]。优秀的desc都长啥样？官方给了一个公式，desc至少要包含这些内容：

1. 能力清单；

2. 具体场景；

3. 用户触发关键词。

name: weekly-report-helper（周报助手）

description: ？

bad：这是一个写周报的skill，每周写周报时激活。

good：该skill从聊天记录生成结构化周报，当用户要求写周报，或者提到"写周报"时激活。

第二个要点：正文做好路由。

很多人写正文，习惯把自己知道的全部写进去，写得越全越有安全感，这个习惯不好。（见上篇，渐进式披露，这里不再展开）

SKILL.md正文不是知识仓库（warehouse），而是路由器（router）。

路由器的职责是分发：告诉agent分几步做、每步去哪找细节。SKILL.md里不放细节内容，放细节内容的指针。

bad：周报文风细节xxoo。

good：周报文风细节详见style.md。

另外，正文多用祈使句，少用"你可以…或许应该…"，少用第二人称。agent不需要被说服，它需要被指挥。官方规范里有明文要求，原话是：Write the entire skill using imperative/infinitive form, not second person.

还有一条实践：别把一切都写的太死，要留一些余地（有些反认知），只有写成"目标+判断规则+坑点"，agent才能适配没预料到的场景。如果是100%确定的场景，就写成程序，而不是skill。

说了这么多，高质量的正文都长啥样？

Anthropic内部最佳实践给了一个骨架：定位，流程，边界，坑点，参考表...