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.