Claude Code Skill 不触发或乱触发

团队的代码审查 Skill 放进 .claude/skills/review-changes/ 已经一周了。可你说“帮我 review 一下这个分支”，它没有出场；你问“这段代码是什么意思”，它反倒被加载了，Claude 开始按审查格式给一段解释代码的请求列风险等级。

Skill 该来时不来、不该来时却来，原因通常不在正文，而在 Claude 决定要不要用它的那一刻。会话平时看不到 Skill 的全文，只看得到它的名称和 description。Claude 拿你的请求去比对这段描述，比中了才加载正文。描述写得太宽，解释代码的请求也会命中；写得不贴近用户的说法，真正的审查请求又匹配不上。

还有一类问题出在调用方式上。部署、发布这类会改变外部状态的流程，你多半不希望 Claude 自己判断时机去启动。解决办法分三步：

把描述写成“做什么 + 什么时候用”，带上用户真实会说的词；
按副作用选择自动、手动或只供 Claude 使用三种调用方式；
用两类真实请求测试：一类该触发，一类不该触发。

01 Claude 靠名称和描述决定用不用

一个 Skill 从被看见到被执行，大致经过这几步：

会话平时只看到 Skill 名称与 `description`
  → 任务匹配或用户显式调用
加载 `SKILL.md`
  → 按需读取参考、示例或脚本
  → 按 Skill 规定的方法执行并验证

加载正文前，Claude 主要依据名称与 description 判断是否使用。Claude Code 的 Skills 文档对 description 字段的说明是：它写这个 Skill 做什么、什么时候用，Claude 据此决定何时应用它。官方还提醒把关键用途放在最前面，因为 description 和补充字段 when_to_use 合起来在 Skill 列表里会被截断到 1,536 个字符。

02 描述要写清任务和触发意图

描述应写清任务与触发意图，例如：

审查分支或未提交改动的正确性、安全性与回归风险；用户要求 review、检查 diff 或评估提交时使用。

“处理代码相关任务”太宽，可能让解释代码的请求也加载审查方法。开头那个误触发，多半就是这类宽泛描述造成的。

对比一下两种写法：

描述	结果
处理代码相关任务	解释、重构、审查的请求都可能命中
审查当前分支相对指定基线的代码改动，定位正确性、安全性和回归风险。用户要求审查 diff、提交或分支时使用	只在提到审查、diff、提交时命中

官方在排查“Skill 不触发”时给的第一条建议，就是检查描述里有没有用户会自然说出的关键词。“review”“检查 diff”“评估提交”这些词写进去，开头那句“帮我 review 一下这个分支”才对得上。

03 按副作用选调用方式

默认情况下，用户与 Claude 都可以调用 Skill：

设置	用户调用	Claude 自动调用	适合场景
默认	可以	可以	安全、可随时应用的方法
`disable-model-invocation: true`	可以	不可以	发布、提交、发消息等由用户决定时机的流程
`user-invocable: false`	不可直接调用，菜单隐藏	可以	只供模型按需调用的内部能力

部署、发布、删除和外部通知会改变外部状态，通常由用户决定何时启动。官方文档对 disable-model-invocation 的解释是：Claude 不能自行调用这个 Skill，适合 /commit、/deploy 这类有副作用或需要你控制时机的流程；设置后，它也不会被预加载进子代理。

user-invocable: false 只改变用户入口，Claude 照样可以用。要禁自动调用，用 disable-model-invocation 或权限规则。权限规则的写法是 Skill(名称)，例如在 deny 里写 Skill(deploy *)，Claude 就调用不了这个 Skill。

Claude Code 最佳实践举的例子是发版流程：真正执行发布这种有副作用的流程，加上 disable-model-invocation: true，Claude 就不能自己启动它，只有你输入 /release 时才会运行。

手动入口怎样接参数、缺参时怎样停下，见把常用流程做成 Claude Code 斜杠命令。

04 用两类请求测试筛选效果

用审查和解释两类请求分别测试，才能判断描述是否起到筛选作用：

用用户真实会说的话测试应该触发的情况，例如“帮我 review 这次提交”；
用相近但不该触发的请求测试，例如“解释一下这个函数”；
本例若设为手动调用，还要检查用户入口能否正常使用。

结果不对，按两个方向调整：

没触发：先看 description 有没有说明这类请求，再查调用限制和 frontmatter；
触发太多：收窄描述，或改成手动调用。

官方的排查清单还有几条可以补充：

问 Claude“有哪些可用的 Skill”，确认它出现在列表里；
换一种更贴近描述的说法再试一次；
设置了 paths 时，确认 Claude 读写的文件就在当前工作目录内；
frontmatter 的 YAML 写坏时，Skill 正文仍会加载但元数据为空，/skill-name 能用，Claude 却没法按描述匹配，用 --debug 启动可以看到解析错误。

一个 Skill 加载之后，正文会留在对话里。描述决定它什么时候进来，进来以后带多少内容，取决于正文和辅助文件怎么组织，做法见SKILL.md 太长时，拆成按需读取的文件。

回到开头：把描述从“处理代码相关任务”改成写明 review、diff、提交的版本，再用“帮我 review 这个分支”和“这段代码什么意思”各测一次。该来的来，不该来的不来，再决定它要不要交给 Claude 自动调用。