北京
写了一个Skill，测试时怎么喊都不触发。翻遍正文找不到问题，最后发现是开头那段description写歪了。
架构师之路在分享Skill写法时，把这件事拆成了两个要点：写好description，以及正文做好路由。前者决定Skill能不能被触发，后者决定触发之后跑得顺不顺。
desc不是摘要，是触发器
很多人把description当成summary来写，交代这个Skill是干嘛的。但Claude Code团队的原话是：The description field is not a summary, it's a description of when to trigger this skill.
换个视角就通了：在agent眼里，Skill就是这段desc。它拿着这段话去和用户的消息做匹配，决定要不要触发。所以写desc，本质上是在写一段给模型的路由规则。
官方给的公式里，一段合格的desc至少要包含三样东西：
- 能力清单
- 具体场景
- 用户触发关键词
对比一下同一个周报助手的两种写法。差的写法是：这是一个写周报的skill，每周写周报时激活。好的写法是：该skill从聊天记录生成结构化周报，当用户要求写周报，或者提到"写周报"时激活。
差别在于，后者把"什么时候触发"写清楚了，而不只是"我是谁"。
正文是路由器，不是仓库
第二个要点是正文的路由。写正文时，很多人习惯把自己知道的全部塞进去，写得越全越有安全感。这个习惯在Skill里是反效果。
SKILL.md的正文不是知识仓库（warehouse），而是路由器（router）。路由器的职责是分发：告诉agent分几步做、每步去哪找细节。正文里不放细节内容，放的是细节内容的指针。
差的写法是把周报文风细节直接铺在正文里，好的写法是一句"周报文风细节详见style.md"。
语气上也有讲究。正文多用祈使句，少用"你可以……或许应该……"，少用第二人称。agent不需要被说服，它需要被指挥。官方规范里有明文要求：Write the entire skill using imperative/infinitive form, not second person.
还有一条实践有点反认知：别把一切都写得太死，要留一些余地。只有写成"目标+判断规则+坑点"，agent才能适配没预料到的场景。如果场景是100%确定的，那就写成程序，而不是Skill。
至于高质量的正文长什么样，Anthropic内部最佳实践给了一个骨架：定位、流程、边界、坑点、参考表。这套结构对应的是agent执行时的几个关键判断点，而不是知识点的罗列顺序。
回到开头那个问题：Skill不触发，先别改正文，去看desc里有没有写清楚"什么时候该触发"。
特别声明：以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布，本平台仅提供信息存储服务。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.
