快速编写一个 Skill

掌握了基本结构与生态分布之后，编写一个可用的 Skill 遵循「先评估集、后写正文」的现代姿势。下面是完整的四步法，全部走下来不超过 10 分钟。

第 1 步：创建目录

在目标位置（例如 Claude Code 的 ~/.claude/skills/、或 CodeBuddy 的 ~/.codebuddy/skills/）下新建一个目录。目录名应能概括 Skill 的核心职责，使用 kebab-case：

text

~/.claude/skills/
└── pdf-form-filler/      ← 用职责命名，一眼可知用途

TIP

目录名 ≡ SKILL.md 中的 name 字段值——这是 spec 硬约束，忘记同步会导致加载失败。

第 2 步：先写评估集（现代姿势推荐）

在写任何代码之前，先列出两个清单：

jsonc

[
  // should-trigger: 希望被触发的真实用户表述
  { "query": "能帮我提取下这份 .pdf 里的表格吗？文件放在下载文件夹", "should_trigger": true },
  { "query": "老板发给我一份 PDF 合同，要汇总其中所有金额条款", "should_trigger": true },
  // should-not-trigger: 看似相关但不该被触发的
  { "query": "怎么把 Word 转 PDF？", "should_trigger": false },
  { "query": "帮我生一张 PDF 报告封面", "should_trigger": false },
]

建议 10–20 条 should-trigger + 5–10 条 should-not-trigger。queries 要真实，含错别字、口语、文件路径、个人背景。

IMPORTANT

先写评估集能帮你「以用户言语反向逼出 description」——这是 Anthropic skill-creator 推荐的姿势，远比「先拍脑袋写 description 再补测试」靠谱。

详细评估方法请看写好 description · 验证方法。

第 3 步：编写 `SKILL.md`

在目录下创建 SKILL.md，按两段式结构填写：

部分	关键内容	作用
Frontmatter	`name`、`description`（参第 2 步评估集提炼）、`allowed-tools`（可选）	决定 Skill 是否被触发
正文	SOP 步骤 + 典型示例（遵循五段式骨架）	决定 Skill 执行得好不好

IMPORTANT

description 是触发与否的唯一依据。请遵守五大规则：只说触发不说过程 / 第三人称 · 祈使句 / 含触发关键词 / 涵盖隐式触发 / 略带强势。详见写好 description。

完整字段说明与示例见 SKILL.md。

第 4 步：跑评估 + 迭代

拿第 2 步的评估集在你的 Agent 平台上跑一轮：

should-trigger 查看触发率 > 0.5 — 低于该阈值，说明 description 太窄或没包含关键词
should-not-trigger 查看触发率 < 0.5 — 高于该阈值，说明 description 太宽会误触发

未通过的 query 是黄金信息：把它们揭示的缺漏关键词补回 description，再跑一轮。Anthropic skill-creator 能自动化这个过程，建议在调试阶段使用。

第 5 步（隐式）：在对话中触发

上面四步走完，无需任何额外配置——只要在对话中使用与 description 匹配的自然语言表达，AI 即会自动加载并执行该 Skill。

至此，你的第一个 Skill 已经可以投入使用。后续若需要扩展能力，再按需引入 scripts/、references/、assets/ 等子目录即可。

进阶

想沉淀为团队资产？看四级生态决定放在哪
想了解 Skill 与 Rule / MCP / Subagent 的边界？看边界辨析
想避开所有坑？看反模式与坑
想看一份生产级范例的全貌？看 SKILL.md 的完整示例
想知道跨平台怎么装、怎么校验？看工具与生态

快速编写一个 Skill ​

第 1 步：创建目录 ​

第 2 步：先写评估集（现代姿势推荐） ​

第 3 步：编写 SKILL.md ​

第 4 步：跑评估 + 迭代 ​

第 5 步（隐式）：在对话中触发 ​

进阶 ​