Claude Code 技能写好了却不触发？6 步排查：先看 /skills，再看 description，11 月 3 日实测版

写了个技能、保存了、问了它该干的事，结果什么都没发生。AI Parabellum 11 月 3 日用 Claude Code v2.1.316 在 macOS 上实测复现了这个问题：原因几乎总是四选一，照着顺序查，5 分钟就能定位。

排查顺序是这样的：先在 Claude Code 里敲 /skills，看技能到底加载了没有——文件夹必须是 .claude/skills/<技能名>/SKILL.md，文件名一个字不能错；加载了但不触发，用 claude plugin validate .claude/skills 检查 frontmatter 有没有坏掉，YAML 解析失败时描述会被悄悄丢掉，技能只能手动跑；再用一句带标记的测试提示词复现——描述写得太含糊是最常见的原因，比如只写“Helps with documents”，改成“做什么、什么时候用”两句话，同一句提示词换个新会话就能触发；最后查 disable-model-invocation: true（只允许手动调用）和 paths 字段（只在当前工作目录内生效）。

关键判断就一条：聊天里没出现 Skill(...) 这一行，就说明技能根本没加载，先修加载、别改措辞。想练手的话，照着原文在空白文件夹建一个带标记的测试技能，先看它漏触发、再改描述看它触发，两轮对比就明白机制了。相关阅读：自己写 Claude Code 技能先看这篇：SKILL.md 每个 frontmatter 字段是干嘛的、10 个现成 Claude Code Hooks 照着抄。原文：Claude Code Skill Not Triggering? How to Find Out Why

来源：AI Parabellum，原文：https://aiparabellum.com/claude-code-skill-not-triggering/