CSKILLBOX.COM
Index live 839 skills 112 authors 10 categories Sourced from SKILL.md

排查

装了却不触发?SKILL.md 的常见错误

大多数「技能不生效」不是模型问题,而是结构问题:文件看起来是正常的 Markdown,但对代理来说不是合法技能。下面是五个最常见的失败和修法。

  • 5 个常见失败
  • 含修法

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 长度和占位文本,不上传任何内容。

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.