Claude Code技能触发失败的真正原因

我管理一个开发团队，日常运行 Claude Code 已经好几个月了。我为我们构建了一套自定义 skills——代码审查、调试流程、团队约定——而我学到的最重要的一课出乎意料：

如果描述写错了，你的 skill 主体写得再好也没用。

没人警告你的失败模式

大多数发现 skills 的开发者都会经历以下过程。他们很兴奋，写了一份详尽的 200 行 SKILL.md，把所有关于代码审查的知识都编码进去……然后它从未被触发过。一次都没有。他们得出结论：skills"不太管用"，然后又回到每个会话都重新输入同样的提示词。

skill 本身可能没问题。是描述杀死了它。

描述是一个路由规则，不是文档

skill 的描述是 Claude 最先看到的内容。只有在描述匹配了你的请求之后，完整的指令才会加载。所以描述不是营销文案——它是一个路由规则，需要按照路由规则的方式来写。

# 弱——读起来不错，但永远不会触发
description: Helps with code quality and best practices.

# 强——命名了场景和措辞
description: Security-first code review for Python/FastAPI.
  Trigger when the user asks to "review", "check", or
  "look at" code, pastes a function or endpoint, mentions
  a bug, or asks "what's wrong with this". Also trigger
  on short requests like "review this".

区别在于：强版本包含了用户实际输入的词汇。包括那些偷懒的措辞。没人会在晚上 11 点写"请进行一次全面的质量评估"——他们写的是"review this"。如果你的描述没有覆盖这个两个词的疲惫版本，你的 skill 就会在大多数真实请求中沉睡。

三条规则修复了我的 skills

1. 列出你真实的触发短语。打开你的聊天记录，看看你是如何实际表述请求的。那些确切的短语要写进描述里——"fix it"、"what's wrong here"、"check this"。用你真实的词汇，而不是专业的词汇。

2. 命名产物，而不只是动词。"当用户粘贴 Python 代码时"、"当出现堆栈跟踪时"、"当分享了 diff 时"。我一半的请求根本不包含动词——我只是粘贴代码。描述必须能捕获这种情况。

3. 画出边界。说明这个 skill 不适用于什么："不适用于编写新功能——那是 builder skill 的职责"。没有边界的话，重叠的 skills 会互相遮蔽，然后你就会得到错误的专家来回答。

我现在的规则：写完一个 skill 之后，打开一个新会话，用我自然打字的方式做五个请求——疲惫的、简略的、任务中途的。如果 skill 在五个中触发了四个，它就上线。如果没有，描述需要更多我真实的措辞，而不是更多的形容词。

把每一次miss都当作一个 bug。修复方法几乎总是往描述里再加一个真实世界的措辞。

我把构建团队 skills 过程中学到的一切都打包成了一本简短 field guide：Stop Prompting. Start Building Claude Code Skills. 里面包含了解剖结构、五个经过实战检验的模式、一个可直接投入生产的安全审查 skill，还有我犯过的七个错误。也很乐意在评论区回答关于 skill 构建的问题。