你的 agent skill body 写得再完美，代码示例和检索测试都通过，但模型可能压根没打开 skill body——它只看 frontmatter 那一行描述。描述只要让模型以为自己已经知道怎么做，它就执行一个简化版本；描述如果和相邻 skill 难以区分，深层的 skill 永远不会被加载。
两种故障模式要排查。一是描述本身成了可执行的步骤。例如「Verifies finished work by running tests…」模型读到就自己跑了一遍测试，不会去 body 里看更严格的 diff 检查逻辑。修复方向：描述只写触发条件（Use when…），不包含任何 procedure verb（run, check, verify）。二是描述首句相同导致一个 skill 永远掩盖另一个。例如 A「Testing best practices for this repo」、B「Testing best practices - integration harness…」，所有测试任务都匹配到 A，B 的 body 再精良也没用。需要在描述层加区分性触发词（比如明确 NOT for……）。
每一条 skill 的描述应该回答「现在要不要加载这个技能」，而不是「加载后它会做什么」。如果能从描述中直接执行，说明内容放错地方了。测试时可以让 subagent 只看描述列表，喂真实任务提示，看它选哪个 skill；如果选错、不选或觉得「描述已经告诉我怎么做」——那就是描述失败，改句子而不是改 body。
@DevToolboxHub