你装了或写了一个 Claude Skill，本该在「总结 PDF」「review 我的 PR」或「记到 CRM」时跑起来。trigger 短语打了、回车敲了——Claude 却用纯文字回了你，没跑 Skill、回复里也没提它的名字。原因几乎都是这几个：trigger 描述太泛、Claude 没认出来；Skill 在当前 surface（web vs Code vs API）没启用；或者另一个 Skill 描述更对路把这轮抢了过去。诊断方向就是看 trigger 文本、看 surface、看竞争者。
常见原因
按命中率从高到低。
1. Skill trigger 描述太泛
Claude 是把你的 prompt 跟每个 Skill 的「when to use」描述匹配的。「帮忙处理文档」这种描述太泛——几乎每段对话都能算「文档」。trigger 措辞更精确的 Skill 会赢。
怎么判断：把 Skill 的 trigger 描述读一遍——能套到你平时一半的 prompt 上，那就是太泛了。
2. 当前 surface 上 Skill 没启用
Skills 在 claude.ai、Claude Code、API 三个 surface 上是独立配置的。装在 claude.ai 上的 Skill 在 Claude Code 里不会跑，反之亦然。
怎么判断：去你实际用的那个 surface 的 Skills 设置，确认这个 Skill 是 enabled 状态、不只是已安装。
3. 这一轮被别的 Skill 抢了
两个 Skill trigger 有重叠（「review documents」和「summarize documents」），Claude 只会挑一个。跟你的 phrasing 匹配更精确的那个赢，另一个就静默。
怎么判断：看 Claude 这次回复——有没有提某个 Skill 名字？如果跑的是另一个，那就是你的竞争者。
4. trigger 措辞太隐式
「看一下这个 PR」比「用我的 code-review Skill review 这个 PR」要弱很多。Skill 一般需要清晰的动词 / 主题，太含糊容易 miss。
怎么判断：你的 prompt 里有没有出现该 Skill 描述里的关键词？没有的话，Claude 触发信号就弱。
5. Skill 的输入要求没满足
有些 Skill 要求附件、文件路径或特定结构化输入。没给齐，Claude 就回退到普通回答而不是大声报错。
怎么判断：看 Skill 的 required inputs 列表。缺必需的附件 / 参数 = 不会触发。
6. Skill 本身坏了 / 安装失败
不常见，但确实有：Skill 的可执行代码安装时报错了，或者 handler URL 不可达，Claude 就悄悄跳过。
怎么判断：Skills 设置里看这个 Skill 有没有红色 error 标识或者「上次运行失败」提示。
开始前
- 把本该触发 Skill 的那条 prompt 一字不差记下来。
- 标注 surface：claude.ai 网页、Claude Code、移动 app、API。
- 列出当前所有启用的 Skill——trigger 竞争是最常见的静默原因。
- 自定义 Skill 的话，把 Skill 定义文件或 dashboard 配置准备好。
需要收集的信息
- Skill 名字（怀疑多个就都列）。
- Skill trigger 描述的原话。
- 那条本该触发它的用户 prompt。
- 同 surface 上启用的别的 Skill。
- Skill 是从 Marketplace、dashboard 还是本地文件装的。
- surface 名字和版本（claude.ai 日期、Claude Code 版本、API SDK 版本）。
一步一步修复
Step 1：先点名让 Skill 跑一次
最快的诊断方法：直接报 Skill 名字。
用我的 code-review Skill 看一下这个 PR。跑起来：Skill 是好的，原 trigger 太弱。还是没跑：Skill 坏了或者当前 surface 没启用——跳到 Step 4。
Step 2：把 trigger 描述写紧
显式调用能跑、隐式不行，就把 Skill 的「when to use」改成动词 + 名词更精确的写法：
| 偏弱 | 偏紧 |
|---|---|
| 帮忙处理文档 | 用户要求「总结」「提取」「对比」PDF 或 doc 时触发 |
| 用于 code review | 用户贴出 PR URL、diff，或者说「review 这段代码」时触发 |
| 日志工具 | 用户说「记到 CRM」「保存 lead」「记下这段对话」时触发 |
紧的版本和真实用户措辞更容易对上。
Step 3：检查当前 surface 是否启用
去你正在测试的那个 surface 的 Skills 设置：
claude.ai → 设置 → Skills → 启用列表
Claude Code → /skills → 启用列表
Anthropic dashboard → Skills → scope：哪些 surface？某个 Skill 装了但当前 surface 没 toggle 上，是不会触发的。
Step 4：列出竞争 Skill
发一条可能引发多个 Skill 的探针 prompt：
你现在可用的 Skill 有哪些？面对这条 prompt 你会触发哪个：
「Review 这个 PR 并把总结记到我的 CRM」？Claude 会列候选。两个都可能触发的话，描述更紧的赢。把输的那个临时禁用，再试一次原 prompt。
Step 5：确认必需输入是否齐了
需要文件或附件的 Skill，确认你真的传了。一个期望本轮带 PDF 附件的 Skill，光打字是触发不了的。
Skill：「Summarize PDF」
Required input：扩展名为 .pdf 的附件
你的 prompt：只有文字 → 回退到普通回答Step 6：自定义 Skill 的话，去查 handler
你自己写的 Skill：打开 Skill repo 或 dashboard 配置，确认：
- 手动测试（curl 或本地跑）handler 能返回成功
name、description、inputs字段都能正确解析- trigger 描述没有语法错（YAML / JSON 坏掉会让 Skill 静默掉线）
Step 7：重装或 reload Skill
Marketplace 装的：禁用再启用。Claude Code Skill：重启编辑器。dashboard 上自定义的：推一个新版本（哪怕只是 no-op 提一下版本号）强制 reload。
怎么验证修好了
- 原始那条 prompt 重发一遍、不点名，Skill 应能触发。
- 测一条近似的、不应该触发的 prompt，Skill 不应触发——确认描述既紧又不过广。
- 多 surface 启用的话至少在两个 surface 上各测一次（web + Code）。
- 共享 Skill 让队友在他自己账号试同一 prompt，一致表现说明不是 per-account 状态问题。
长期预防
- Skill 描述用「用户要 X / Y / Z 时触发」的句式，动词领头、名词精确。
- 单个 surface 启用的 Skill 总数控制在 10 个以内，再多 trigger 竞争就严重了。
- 自定义 Skill 旁边写一份 TEST.md，列 5 条「应该触发」和 5 条「不该触发」的 prompt，改 description 后跑一遍。
- Skill 作者：在 server 端打每次调用日志，静默 skip 才能从数据里看出来。
- 同主题相关的几个 Skill 合并成一个多模式 Skill，比开 4 个 trigger 互撞的窄 Skill 好。
容易踩的坑
- 改了 Skill 描述忘了推 / reload，Claude 看到的还是旧文本。
- 两个 Skill 描述几乎一样，然后好奇为什么有个一次都没触发。
- 默认在 claude.ai 启用的 Skill 在 Claude Code 也能跑，其实不能——scope 是独立的。
- trigger 描述用了用户视角（「我想要……」）而不是系统视角（「用户要求……时触发」）。
- 忘了内置工具（web search、代码执行）也会抢这轮——它们看起来像 Skill 但其实是独立机制。
常见问答
- Claude 怎么决定触发哪个 Skill？ 用你的 prompt 跟每个 Skill 描述匹配、挑最贴的那个。描述更紧的赢。
- 能强制触发某个 Skill 吗？ 能——直接点名：「用我的 X Skill 做 Y」。
- Skill 触发会在回复里被提到吗？ Claude 一般会提到用了哪个 Skill。没提到，多半是没跑。
- 有 debug 模式能看 Claude 考虑了哪些 Skill 吗？ Claude Code 上有（verbose 日志）。claude.ai 上可以让 Claude「列出你这轮考虑过的 Skill」。
- Skill 像 Projects 那样跨 chat 维持上下文吗？ 不会——每次 Skill 调用独立。持久状态要放在 Skill 自己的 handler 里。