排查
装了却不触发?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.