先说结论
Skill 不出活，九成不是模型笨，是“它根本没被加载”或“被加载了但描述把它引偏了”。记住一条铁律：默认情况下 skill 的 description 一直挂在上下文里，但完整内容只在被调用时才读进来；触发与否，几乎全看 description 写得对不对、以及它落在哪个目录。下面按“没触发 / 乱触发 / 更新后失效”三类给排查表。数据时间为 2026-09-26，来自 GitHub API 与 Claude Code 官方文档（anthropics/skills 约 17.8 万 star，是官方示例库）。本篇只讲机制，社区具体案例没查到可信来源，不编造引述。
第一类：装了没触发
先区分“没加载”还是“没自动匹配”。直接在会话里手敲 /skill-name 强制造一次：能跑通说明技能已加载，问题在 description 的自动匹配；报错“找不到”说明压根没被加载，得往目录和名字上查。
/code-review
# 能跑 = 已加载，问题在 description 自动匹配
# not found = 没加载，回去查目录和名字
| 现象 | 可能原因 | 怎么查 | 修复 |
|---|---|---|---|
| 手动能跑，自动不跑 | description 太窄，没覆盖用户原话 | 看 description 是否带“什么时候用”和关键词 | 按规范补关键词 |
| 完全 not found | 放错目录 | 确认在 .claude/skills/ 还是 ~/.claude/skills/ | 放到目标位置并提交仓库 |
| 完全 not found | 目录名与 frontmatter 的 name 不一致 | 比对名称和目录名 | 让 name 与目录同名、小写加连字符 |
| 自动从不触发 | 设了 disable-model-invocation: true | 检查 frontmatter | 删掉该字段，让 description 回上下文 |
| 个人机器不跑团队版 | 个人级覆盖了项目级 | 优先级：个人 > 项目 | 改名加前缀，避开撞车 |
“怎么看它有没有被加载”最实用的两个动作：其一，手动调用 /skill-name，这是最硬的判定；其二，来自插件市场的 skill 走 /plugin 菜单确认已安装、已启用，插件技能还带命名空间，命令是 /plugin-name:skill-name 而非裸名。文档还提到一个开关 disable-model-invocation: true：设了之后 description 不再进上下文，模型根本不会自动想起它，只能你手动调——很多“装了不触发”其实是被人顺手加了这个字段。举个真实点的例子：有人把团队 review 技能放在自己机器 ~/.claude/skills 上，同事 clone 仓库后跑 /code-review 用的是本机那份旧规则，评审口径对不上，吵了半天才发现是位置优先级在作怪。
官方文档原话：“The description helps Claude decide when to load the skill automatically.” 规范同时要求 description “should include specific keywords that help agents identify relevant tasks.”
第二类：触发了乱跑
乱触发的根因几乎都是 description 写成了“关键词垃圾堆”：想让它多被命中，就塞一堆八竿子打不着的词，结果任何含这些词的提问都把它叫起来。另一个常见原因是和别的 skill 职责重叠，两 skill 抢同一句话，模型随机挑一个。比如有个 pdf 技能 description 写了“文档、表格、报告、分析”，用户说“帮我分析一下这周的销售”，模型把 pdf 技能叫起来，其实人家要的是查数据库——这种误命中最容易被当成“模型抽风”，根子却在 description。
| 现象 | 原因 | 缩小触发范围的做法 |
|---|---|---|
| 无关问题也调它 | description 关键词太泛 | 删掉泛词，只留“做什么 + 何时用” |
| 两个 skill 抢同一句 | 职责重叠 | 按场景切分，description 写明边界 |
| 被短词命中 | description 含“pdf”“test”这种高频词 | 改成完整短语与动作描述 |
一个好 description 与坏 description 的对照，坏的那版把所有相关词堆上去，反而让“帮我写个测试”这种无关请求也命中：
# 坏：关键词堆砌，到处乱触发
description: 处理 PDF、文档、表格、报告、导出、转换、整理、分析。
# 好：说清做什么、何时用
description: 从 PDF 抽取文本与表格、合并或拆分 PDF、填表。当用户提到 .pdf 文件或要生成 PDF 时使用。
第三类：更新后失效
昨天还好好的，今天改了上游就废，通常出在这几处：上游改了 frontmatter 字段或目录结构；你本机跑的还是旧缓存；插件没重新安装；skill 里的脚本因为权限或依赖变了跑不起来。
| 现象 | 原因 | 排查 / 修复 |
|---|---|---|
| 改完 SKILL.md 不生效 | 当前会话已读入旧内容 | 开新会话再试 |
| 插件里的 skill 旧 | 插件没更新 | 重装：/plugin install <plugin>@<marketplace> |
| 脚本报错 | 依赖或执行权限变了 | 本地跑一遍脚本，补齐 allowed-tools |
| 字段被忽略 | 用了旧规范字段名 | 按 Agent Skills 规范比对 name/description |
为什么改完不生效：模型只在调用时才读完整 SKILL.md，但当前会话一旦读入就缓存住，你改了文件它还在用旧的——开个新会话是最常被忽略的一步。插件类 skill 则靠市场分发，上游发了新版，你本机不会自动变，得重新 /plugin install。格式校验能提前拦掉“字段写错”这类失效：
skills-ref validate ./my-skill
通用排查清单
- 第一步永远手动调用
/skill-name：区分“没加载”还是“没自动匹配”。 - 看它挂哪：项目级
.claude/skills/提交了吗？个人级~/.claude/skills/是不是抢了同名？ - 看名字：目录名是否等于 frontmatter 的
name，是否碰了保留名synced、anthropic-skills（这两个不会被加载）。 - 看 description：是否同时写了“做什么”和“何时用”，关键词是否精准。
- 看插件：来自市场的 skill 用
/plugin菜单确认已安装、已启用。 - 看会话：是不是改完没开新会话，还在跑旧缓存。
反模式清单：
- 用关键词堆砌换“高触发率”，最后变成哪里都乱跳。
- 靠个人目录测完就当团队可用，忘了个人级会盖过项目级。
- 改了 SKILL.md 不新建会话，以为模型“没更新”其实是缓存。
- 给 skill 起名
synced或anthropic-skills，加载器直接跳过。
什么人该装，什么人别装
正在写或维护团队 skill、被“为什么它不触发”折磨过的人，照上面四类逐条过一遍基本能定位。别装的是：指望靠一个 skill 解决所有触发问题——触发质量在 description，不在数量。下一篇（第 68 篇）讲清 skill 和 MCP 的边界，很多“总是不够用”的坑其实是该接服务而不是堆技能。