AI编码
mp.weixin.qq.com ·
@架构师之路
写好 SKILL 的两个要点：description 是触发器，正文是路由器
文章总结编写 Claude Code Skill 的两个要点：一是 description 不是给人看的摘要，而是给模型的路由规则，需包含能力清单、具体场景和触发关键词；二是 SKILL.md 正文应作为路由器而非知识仓库，只放步骤与细节文件指针，并多用祈使句。文中引用官方规范称应使用祈使/不定式而非第二人称，并建议保留「目标+判断规则+坑点」的余地。文末为直播预告。
AI推荐理由 面向 Claude Code Skill 编写者的实操经验，提出 description 应作为模型触发路由规则、正文应作为路由器而非知识仓库，并引用官方规范中祈使句要求。内容具体、可操作，但属经验总结与直播预告，无独立验证数据，且部分引用无法在片段中核实。
62
正文
架构师之路 2026-10-03 11:46 北京
将在10月08日 21:00 直播
其一，写好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内部最佳实践给了一个骨架：定位，流程，边界，坑点，参考表...
限于篇幅，这里不再展开，节后我准备了一场直播：《如何30分钟写出一个好skill》。分享自己写skill的一些心得，以及自己对AI的一些思考。
欢迎预约，直播间不见不散。
[跳转微信打开](https://wechat2rss.bestblogs.dev/link-proxy/?k=d6eecb94&r=1&u=https%3A%2F%2Fmp.weixin.qq.com%2Fs%3F__biz%3DMjM5ODYxMDA5OQ%3D%3D%26mid%3D2651981704%26idx%3D1%26sn%3Deea508096408cb3c814b252e9a6a158d)