你装了或写了一个 Claude Skill，本该在「总结这个 PDF」「review 我的 PR」或「把这条记到 CRM」时跑起来。trigger 短语打了、回车敲了——Claude 却用纯文字回了你，根本没跑 Skill。
最快的修法：先显式点名让它跑一次。在 Claude Code 里打 /your-skill-name；在 claude.ai 上说「用我的 your-skill Skill 做某事」。能跑起来，说明 Skill 是好的，真正的问题在 trigger 描述或 skill budget（看 Step 2 和 Step 4）。连显式调用都不跑，那就是当前 surface 没启用或者 Skill 坏了（看 Step 3、6、7）。
Skill 是拿你的 prompt 跟每个 Skill 的 description 文本去匹配的，而启动时只加载了这段描述。描述太泛、设了 disable-model-invocation、用错了 surface，或者 Claude Code 为了不超过 skill budget 把描述悄悄挤掉了——这几种都会造成静默 miss。下面按命中率从高到低过一遍各种原因，菜单路径、命令和设置项都按 2026 年 6 月的现状给出准确写法。
Skill 匹配到底怎么工作的
这个机制能解释绝大多数静默 miss。每个 Skill 都是一个带 YAML frontmatter 的 SKILL.md 文件。Anthropic 的渐进式加载（progressive disclosure）分阶段加载 Skill：
| 层级 | 何时加载 | 开销 | 内容 |
|---|---|---|---|
| 1. 元数据 | 一直加载，启动时 | 每个 Skill 约 100 tokens | system prompt 里的 name + description |
| 2. 指令 | 仅在 Skill 触发时 | 约 5k tokens 以内 | SKILL.md 正文 |
| 3. 资源 | 按需 | 基本无上限 | 通过 bash 读取的捆绑文件/脚本 |
匹配器永远只看得到第 1 层。所以如果你的 description 没把「什么时候用」讲清楚，Claude 就没东西可匹配，只能回退到普通回答。description（加上可选的 when_to_use）在列表里会被截断到 1,536 个字符，所以触发条件要写在最前面。
常见原因
按命中率从高到低。
1. SKILL.md 描述太泛
Claude 是把你的 prompt 跟每个 Skill 的 description 匹配的。「帮忙处理文档」太泛了，因为几乎每段对话都能算「文档」。Anthropic 自己的建议是：描述里要同时讲清楚 Skill 干什么、以及 Claude 什么时候该用它。
怎么判断：把描述读一遍。能套到你平时一半的 prompt 上，那就是太泛了——也太泛、压不过描述更精确的竞争 Skill。
2. Skill 设了 disable-model-invocation: true
在 Claude Code 里，frontmatter 带 disable-model-invocation: true 的 Skill（或合并进来的自定义命令）永远不会自动触发，只在你亲自打 /skill-name 时才跑。给手动工作流（部署、提交）写的 Skill，这是最容易被忽略的静默原因。
怎么判断：打开 SKILL.md 的 frontmatter，看有没有 disable-model-invocation: true。有的话，这个 Skill 按设计就是只能手动触发。
3. 当前 surface 上 Skill 没启用
Skills 不跨 surface 同步。传到 claude.ai 的 Skill 在 API 或 Claude Code 里用不了，反之亦然。claude.ai 的 skill 是按用户独立的；API 的 skill 是 workspace 级共享的；Claude Code 的 skill 是基于文件系统的。
怎么判断：在你正在测的那个 surface 上看 Skills 列表，确认它在这里显示出来了，而不只是在别处装了。
4. 被 Claude Code 的 skill budget 挤掉了
从 build 2.1.129（2026 年 5 月）起，Claude Code 把所有 skill 列表元数据的总量限制在 skillListingBudgetFraction 这个比例的上下文窗口以内，默认 0.01（1%）。如果你装的这些 Skill 描述加起来超了这个 budget，Claude Code 会保留优先级高的（按使用频率/近期使用），把其余的描述直接丢掉，于是它们就不再自动触发了。发生截断时启动会打一条 warning，点名是哪些 Skill。
怎么判断：跑 /context 看那行 Skills:，或者跑 /skills 看你的 Skill 是不是还显示完整描述。被丢掉了，那就是它不再匹配的原因。
5. 这一轮被别的 Skill 抢了
两个 Skill trigger 有重叠（「review documents」和「summarize documents」），Claude 会挑描述跟你 phrasing 匹配最好的那个，另一个就静默。
怎么判断：在 Claude Code 里，这一轮之后问「你用了哪个 Skill、为什么？」在 claude.ai 上，看回答像不像是另一个 Skill 的行为。
6. trigger 措辞太隐式
「看一下这个 PR」比「review 这个 PR」信号弱。Skill 一般需要动词/主题跟描述里的措辞对得上；就算描述写得好，太含糊的开头也常常 miss。
怎么判断：你的 prompt 里有没有出现该 Skill 描述里的关键词？没有的话，匹配信号就弱。
7. 必需输入没给齐，或受 paths 限制
有些 Skill 要求附件或文件路径。没给，Claude 就回退到普通回答而不是大声报错。在 Claude Code 里，带 paths: glob 的 Skill 只在你正操作匹配的文件时才自动加载。
怎么判断：看 Skill 的必需输入，以及 frontmatter 里的 paths:。缺附件、或文件路径不匹配，就不会自动触发。
8. Skill 本身坏了，或安装失败
不常见：frontmatter YAML 写坏了、name 超过 64 字符、description 超过 1,024 字符，或者 handler 安装时报错。解析不了的 Skill，Claude 会静默跳过。
怎么判断：校验 frontmatter（name：小写字母、数字、连字符，最多 64 字符，且不能是 “claude”/“anthropic”；description：非空，最多 1,024 字符）。在 claude.ai 上确认上传没报错；在 Claude Code 里看启动有没有解析 warning。
开始前
- 把本该触发 Skill 的那条 prompt 一字不差记下来。
- 标注 surface：claude.ai 网页、Claude Code、移动 app，还是 API。
- 列出该 surface 上当前所有启用的 Skill——trigger 竞争和 budget 挤压是两个最常见的静默原因。
- 自定义 Skill 的话，把
SKILL.md（或 dashboard 配置）打开。
一步一步修复
Step 1：先显式调用一次
最快的诊断方法是强制让 Skill 跑起来。
在 Claude Code 里：
/your-skill-name在 claude.ai 或 API 的 prompt 里：
Use my code-review Skill on this PR.跑起来：Skill 是好的，原 trigger 太弱（去 Step 2 / Step 4）。还是没跑：Skill 坏了或者当前 surface 没启用（跳到 Step 3、6 或 7）。
Step 2：把描述写紧
显式能跑、隐式不行，就把 description 改成动词 + 名词更精确的写法，并把关键触发词放最前面（列表里只保留前 1,536 个字符）：
| 偏弱 | 偏紧 |
|---|---|
| 帮忙处理文档 | 用户要求「总结」「提取」「对比」PDF 或文档时使用 |
| 用于 code review | 用户贴出 PR URL 或 diff，或者说「review 这段代码」时使用 |
| 日志工具 | 用户说「记到 CRM」「保存 lead」「记下这段对话」时使用 |
在 Claude Code 里你还可以加一个 when_to_use: 字段，写上明确的触发短语，它会被追加到列表里的描述后面。2026 年流传的研究发现，祈使式写法（「凡是用户问到 X 就用这个 skill」）比被动描述的触发率高得多，所以把触发条件直白写出来。
Step 3：确认当前 surface 已启用
去你正在测试的那个 surface 上确认：
claude.ai → Settings → Features → Skills（上传自定义 zip；需要 Pro/Max/Team/Enterprise + 开启 code execution）
Claude Code → /skills → 把该 Skill 切到开
API → skill 须经 /v1/skills 上传，并在 container 参数里用 skill_id 引用在 claude.ai 上，预置 skill（PowerPoint、Excel、Word、PDF）开箱即用、无需任何设置。自定义 skill 要打成 zip 上传到 Settings → Features，且只对你自己的账号生效，不会全组织共享。
在 Claude Code 里，自定义 skill 放在 ~/.claude/skills/<name>/SKILL.md（个人，所有项目）或 .claude/skills/<name>/SKILL.md（仅本项目）。同名冲突时，enterprise 覆盖 personal，personal 覆盖 project。
Step 4：检查 Claude Code 的 skill budget
如果你在 Claude Code 里，一个原本能用的 Skill 在你装了更多 Skill 之后不再自动触发，多半是超 budget 了。
/context → 看那行 "Skills:" 的 token 占用和上下文百分比
/skills → 打开 picker；被丢掉的 Skill 会显示截断/没有描述两种修法：
- 在
/skillspicker 里禁用你不用的 Skill。禁用的 Skill 会被整个移出列表、不再占 budget。这是零成本的修法。 - 在
settings.json里调高 budget（大概每个 session 多花约 3k tokens）：
{
"skillListingBudgetFraction": 0.02,
"skillListingMaxDescChars": 2048
}skillListingBudgetFraction 是 0 到 1 之间的小数（0.02 = 2%），不是百分比。skillListingMaxDescChars 默认 1536。
Step 5：列出并解决竞争 Skill
在 Claude Code 里，发一条多个 Skill 都可能匹配的探针，再问 Claude 会挑哪个：
面对这条 prompt 你会用哪个 Skill：「Review this PR and log a summary to my CRM」？说明理由。两个都可能触发的话，描述更紧的赢。在 /skills 里把输的那个临时禁用，再试一次原 prompt。在 claude.ai 上，去 Settings → Features 禁用竞争 skill。
Step 6：确认必需输入和 paths
需要文件的 Skill，确认你真的传了附件。一个「Summarize PDF」Skill 光打字是触发不了的：
Skill：「Summarize PDF」
Required input：本轮带一个 .pdf 附件
你的 prompt：只有文字 → 回退到普通回答在 Claude Code 里，检查 frontmatter 里有没有 paths: glob。范围限定在 paths: ["src/**/*.ts"] 的 Skill，只在你操作匹配文件时才自动加载。
Step 7：校验 frontmatter 和 handler
你自己写的自定义 Skill，打开 SKILL.md 确认：
name：只用小写字母、数字、连字符；最多 64 字符；不能是 “claude” 或 “anthropic”。description：非空；最多 1,024 字符；触发条件写在最前。- 没有
disable-model-invocation: true，除非你本来就想要只能手动触发。 - YAML 能正确解析（多一个冒号或没加引号的
:会让 Skill 静默掉线）。 - 对带可执行 handler 的 API/dashboard Skill，手动
curl或本地跑一遍，确认 handler 能返回成功。
Step 8：重新加载 Skill
- Claude Code：监听目录下对
SKILL.md的改动靠 live change detection，会在当前 session 内生效。但 session 启动时还不存在的全新顶层 skills 目录，需要重启 Claude Code。 - claude.ai：去 Settings → Features 重新上传 zip；上传不会热加载。
- API：通过 Skills API 推一个新版本，再引用更新后的
skill_id。
怎么验证修好了
- 原始那条 prompt 重发一遍、不点名，Skill 应能触发。
- 测一条近似的、不应该触发的 prompt，Skill 应保持静默——这能确认描述既紧又不过广。
- 在 Claude Code 里跑
/context，确认该 Skill 在Skills:budget 里仍有完整描述（没被再次丢掉）。 - Skill 在多个 surface 上启用的话，每个 surface 各测一次；它们不同步。
- 共享的 Claude Code 项目 skill，让队友拉一下 repo、试同一条 prompt。
长期预防
- 描述写成「用户要 X / Y / Z 时使用」。动词领头、名词精确、触发条件放最前。
- 单个 surface 上启用的 Skill 总数别太多。在 Claude Code 里盯着
/context的Skills:那行，在撞上 1% budget 上限前就用/skills清理。 disable-model-invocation: true只留给真正手动的工作流，并在 Skill 里写明，免得日后自己纳闷它为什么不自动触发。- 自定义 Skill 旁边留一份小测试清单：5 条「应该触发」、5 条「不该触发」的 prompt，改 description 后跑一遍。
- 把同主题的几个窄 Skill 合并成一个多模式 Skill，比开 4 个 trigger 互撞的好。
容易踩的坑
- 改了描述但忘了重新上传（claude.ai）或为新顶层目录重启（Claude Code），Claude 看到的还是旧文本。
- 两个 Skill 描述几乎一样，然后好奇为什么有一个一次都没触发。
- 以为 claude.ai 的 Skill 在 Claude Code 也能跑，其实不能——surface 之间不同步。
- 在一个你指望自动触发的 Skill 上留着
disable-model-invocation: true。 - 装了一堆 Skill 把 Claude Code 的 skill budget 悄悄撑爆，老 Skill 丢了描述。
- 描述用了用户视角（「我想要……」）而不是触发视角（「用户要求……时使用」）。
常见问答
- Claude 怎么决定触发哪个 Skill？ 用你的 prompt 跟每个 Skill 的
description（启动时唯一加载的文本）匹配，对最贴的那个再通过 bash 读取SKILL.md正文。描述更紧、触发条件靠前的赢。 - 一个本来能用的 Skill 怎么在 Claude Code 里不触发了？ 多半是你装了更多 Skill 超过了
skillListingBudgetFraction（默认 1%），Claude Code 把它的描述丢了。跑/context和/skills，禁用不用的 Skill 或调高 budget。 - 能强制触发某个 Skill 吗？ 能。在 Claude Code 里打
/skill-name；在 claude.ai 上说「用我的 X Skill 做 Y」。 - 我的 Skill 只在打斜杠命令时跑、从不自动触发，为什么？ 它的 frontmatter 多半有
disable-model-invocation: true，这一项按设计就会阻止自动加载。 - 在 claude.ai 上去哪里启用自定义 Skill？ Settings → Features，打成 zip 上传。需要 Pro、Max、Team 或 Enterprise 套餐并开启 code execution，且只对你自己的账号私有。
- Skill 像 Projects 那样跨 chat 维持上下文吗？ 不会。每次调用都独立；持久状态要放在 Skill 自己的文件或 handler 里。
相关
- Claude 工具调用卡在 pending
- Claude Projects 多会话上下文污染
- Claude Chrome connector 问题
- Claude connector 没权限
- Claude 新手入门
外部参考：Agent Skills overview（Anthropic 文档） 和 Use Skills in Claude Code。