排查
裝了卻不觸發?SKILL.md 的常見錯誤
大多數「技能不生效」不是模型問題,而是結構問題:檔案看起來是正常的 Markdown,但對代理來說不是合法技能。以下是五個最常見的失敗與修法。
1. 沒有 frontmatter
技能檔案必須以 YAML 块开头:
---
name: pdf
description: 讀取、拆分、合併並填寫 PDF。當任務涉及 PDF 檔案時使用。
---
如果檔案以標題或段落開頭,代理既拿不到名字,也拿不到触发条件。修法:把这一段放到最前面,上面不要有任何內容,空行也不行。
2. name 不是合法标识
只用小写字母、数字和单个短横线:pdf、frontend-design、seo-audit。空格、大写、下划线和点号在部分代理里会导致路由失败。
3. description 没写「什么时候用」
description 就是触发器。「一个对文档有用的技能」几乎匹配不了任何具体请求。写法是「做什么 + 什么信号出现时用」:
讀取、拆分、合併並填寫 PDF。當任務涉及 PDF 檔案、表單或擷取文字時使用。
控制在 1024 字元以内,把动词放前面。
4. 檔案放錯了位置
技能是按路径发现的,不靠搜索。以 Claude Code 为例:
- 个人:
~/.claude/skills/<name>/SKILL.md - 项目:
<project>/.claude/skills/<name>/SKILL.md
放在 ~/skills/pdf.md 或者 ~/.claude/skills/pdf.md(是檔案不是資料夾)都不會被加载。資料夾名和 name: 应保持一致。
5. 正文是占位內容
描述写得好、正文空着,结果是「能被触发,但什么也不做」。正文是流程:步骤、顺序、檢查项、範例。少于一百个字元,就不算一个技能。
另外两个常见的坑
重名。 两个同名技能会互相覆盖,安装前先看一下技能目录。
脚本没有路径。 正文里只说「运行脚本」而不写相对技能目录的路径,代理只能靠猜。用相对路径,并在正文里说明。
十秒自检
把檔案粘进 SKILL.md 驗證器:它会在浏览器里檢查 frontmatter、name 格式、description 长度和占位文本,不上传任何內容。
Keep reading
Community notes
Found a broken install? Know a skill we missed?
One line is enough: the skill name, what happened, and the command you ran. We read every note and fix the index.