skill 不工作的时候,毛病几乎总落在几个可预测的类别里:不触发、不加载、用错了、或者跑起来报错。好消息是大多数修法都很直接——关键是先对号入座,别一上来就瞎改正文。
先给一张总检索表:
| 症状 | 最可能的原因 | 第一步去哪看 |
|---|---|---|
| 该用时没用上(不触发) | description 没覆盖你的问法 | 加触发词 |
| 问”有哪些 skill”它不出现(不加载) | 文件结构/命名错了 | 查目录和文件名 |
| 用错了 skill | 几个 description 太像 | 把描述写得更不一样 |
| 我的 skill 被无视(被盖住) | 有同名的高优先级 skill | 查优先级,改名 |
| 插件的 skill 看不到 | 缓存/安装问题 | 清缓存重装 |
| 加载了但跑挂了(运行报错) | 依赖/权限/路径 | 查这三样 |
最容易忘的一条:改完或新建 skill 没重启。
name和description是启动那一刻读进去的,不重启,AI 看的还是旧的那份——这点前面反复强调过。往下排查之前,先确认你重启了。
第 0 步:先跑验证器
别急着调别的——先跑官方的 skills 验证器(skills validator)。安装方式按系统不同,用 uv 最快。装好后进到 skill 目录、或在任意位置运行它,它会先把结构性问题揪出来,省得你在别处瞎耗时间。
不触发:八成是 description
skill 存在、也通过验证了,但该用时 Claude 没用。原因几乎总是 description。
Claude 用的是语义匹配(第二篇讲过),你的请求得和 description 的意思有重叠,重叠不够就不匹配。怎么修:
- 拿你实际的问法去对 description,看覆盖到没有。
- 把你真会说的触发词加进去。
- 用几种变体测一遍:“帮我 profile 一下""为什么这么慢?""让它快点”——哪个变体没触发,就把那些词补进 description。
不加载:查目录结构和文件名
如果你问 Claude”有哪些 skill 可用”,你的 skill 根本不出现,那是结构问题,查两条硬要求:
SKILL.md必须放在一个有名字的子文件夹里,不能直接丢在 skills 根目录。- 文件名必须精确是
SKILL.md——SKILL全大写、md小写,一个字母都不能错。
还看不出来,跑 命令行里的 claude --debug,它会打印加载错误。搜你的 skill 名,经常一眼就定位了。
用错 skill:把描述写得更不一样
如果 Claude 用了错的 skill、或在几个 skill 之间犯迷糊,通常是它们的 description 太像了。把它们写得更不同、更具体。
描述越精确,不光帮 AI 判断该不该用你这个,还能避免和别的”听起来差不多”的 skill 撞车。
被盖住:查优先级,改名最省事
如果你的个人 skill 被无视了,很可能有个同名、优先级更高的 skill 压着它。比如企业有个 code-review,你个人也有个 code-review——企业版每次都赢。两个办法:
- 把你的 skill 改个更独特的名字(通常最省事)。
- 或者找管理员聊那个企业 skill。
插件 skill 不出现:清缓存重装
装了插件但看不到它的 skill?清缓存 → 重启 Claude → 重装,这一套先走一遍。
走完还不出现,多半是插件结构不对——这时候验证器最值钱。
运行报错:依赖、权限、路径
skill 加载了,但执行时挂了。三个常见原因:
- 缺依赖:skill 用到的外部包必须先装好。把依赖信息写进 skill 的 description,让 Claude 知道需要什么。
- 权限:类 Unix 系统上,脚本要有执行权限,跑
chmod +x给它加上。(Windows 上一般不涉及这一步。) - 路径分隔符:到处都用正斜杠
/,哪怕在 Windows 上也用。 这条对 Windows 用户尤其要记牢——反斜杠\在很多地方会出问题。
速查清单
| 症状 | 修法 |
|---|---|
| 不触发 | 改 description,加触发词 |
| 不加载 | 查路径、文件名、YAML 语法 |
| 用错 skill | 让几个 description 彼此更不同 |
| 被盖住 | 查优先级,改名 |
| 插件 skill 没了 | 清缓存,重装 |
| 运行报错 | 查依赖、权限、路径 |
给 vibe-coder 的话
skill 不工作时,最该忍住的冲动是去重写正文——因为 90% 的毛病根本不在正文,而在 description(不触发/用错)或文件结构(不加载)。
按这篇的顺序对号入座:先确认重启了,再跑验证器排结构,然后看是不是 description 没匹配上,最后才查运行时的依赖和路径。养成这个习惯,你修一个不工作的 skill 通常几分钟就搞定,而不是对着正文改半天。