六步创建一个技能
下面的示例技能在 Claude Code 里审查 SQL 迁移文件，专找会删数据、或者没法回滚的步骤。这类每次都得跟智能体重新交代一遍的活，就该做成技能。每个任务都适用的规则就不一样了，该写进 CLAUDE.md，Claude Code 每次会话开始都会加载它。
先写描述，再写正文。请求对上之前，智能体只看得到技能的名称和描述。描述要写清技能做什么、什么时候用。Anthropic 的编写指南还要求用第三人称来写，因为描述会被注入系统提示。
---
name: reviewing-sql-migrations
description: Reviews SQL migration files for steps that drop data or cannot be rolled back. Use when the user adds or edits a migration or asks whether a schema change is safe.
---
# Reviewing SQL migrations
1. Run scripts/changed_migrations.sh to list the migration files changed on this branch.
2. Read each file in full. Note every DROP, every RENAME, every column type change and every NOT NULL added to an existing column.
3. For each one, say what happens to rows that already exist and whether the step can be undone.
4. For how our database locks tables during a migration, read references/locks.md.
5. Finish with a table: file, risky step, why it matters, suggested fix.
## Gotchas
- Migrations live in db/migrations/. Never edit one that has already shipped. Write a new migration instead.
- Some old migrations have no down step. Mention it once, then move on.
- 建文件夹，名字用动名词形式。Anthropic 的指南举的例子是
processing-pdfs，helper、utils这类含糊的名字不推荐。想在所有项目里用，运行mkdir -p ~/.claude/skills/reviewing-sql-migrations。只给一个仓库用，就在仓库里建.claude/skills/reviewing-sql-migrations。 - 把上面的内容存成这个文件夹里的
SKILL.md。name必须和文件夹同名。 - 正文写成编号步骤，说清你要什么样的输出，最后加一个 Gotchas 清单，列出不提醒就会弄错的事实。
- 技能用得到的话，加上正文提到的两个文件：
scripts/changed_migrations.sh和references/locks.md。 - 检查头信息。在 Claude Code v2.1.233 及以上版本里，
claude plugin validate ~/.claude/skills能找出 YAML 解析失败的 SKILL.md。参考工具skills-ref validate ./reviewing-sql-migrations则按规范检查一个文件夹。 - 在 Claude Code 里用自己的话提出任务，比如“这个迁移能合并吗？”，再运行
/reviewing-sql-migrations，按名字直接调用技能。
X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 3 日，时间为美国太平洋时间。点击截图可到 X 上打开原帖。
各产品不一样的头信息限制
Anthropic 的帮助文章规定，上传到 Claude.ai 的技能，描述最多 200 个字符，开放规范则放宽到 1,024 个。
Claude Code 自己还认几个字段，都列在它的技能文档里。设了 disable-model-invocation: true，技能就只在你输入命令时运行。有了 allowed-tools，技能在被调用的那一轮里可以直接用列出的工具，不用一个个问你。
| 规则 | 适用于 | 出处 |
|---|---|---|
name：最多 64 个小写字母、数字和连字符，与文件夹同名 | 所有遵循开放规范的智能体 | Agent Skills 规范 |
name 里不能有 anthropic 或 claude，两个字段都不能有 XML 标签 | Claude | Anthropic 技能编写指南 |
description：最多 1,024 个字符 | 开放规范 | Agent Skills 规范 |
description 和 when_to_use 合计：在技能清单里超过 1,536 个字符的部分会被截掉 | Claude Code | Claude Code 技能文档 |
description：最多 200 个字符 | 上传到 Claude.ai | Claude 帮助中心 |
description 和 when_to_use 加起来被截断的位置。来源：Claude 帮助中心：如何创建自定义技能 (2026年11月3日 查阅)；Agent Skills 规范 (2026年11月3日 查阅)；Claude Code 文档：技能 (2026年11月3日 查阅)
正文写什么，脚本放哪里
技能被调用时，Claude Code 把正文放进对话，就放这一次，后面几轮不会再读这个文件。所以要写“每次改完都跑测试”，别只写“跑测试”。
长会话压缩以后，Claude Code 可能只留下已调用技能的开头部分。必须一直生效的步骤写在 SKILL.md 最前面，背景说明放到后面。
Claude 是运行一个脚本还是阅读它，取决于 SKILL.md 里那一行怎么写。在 Anthropic 的指南里，“运行 analyze_form.py 提取字段”是让它执行，“参见 analyze_form.py 了解提取算法”是让它读。路径一律用正斜杠，Windows 上也一样，反斜杠在 Unix 系统上会出错。
示例里的路径都从技能文件夹算起。在 Claude Code 里，${CLAUDE_SKILL_DIR}/scripts/changed_migrations.sh 这样的路径，不管技能装在哪里都能找对，插件里也一样。
reviewing-sql-migrations/
├── SKILL.md
├── scripts/
│ └── changed_migrations.sh
└── references/
└── locks.mdClaude Code 从哪里找到你的技能
~/.claude/skills/ 和项目的 .claude/skills/ 里都有 deploy 的话，输入 /deploy 运行的是你个人的那个，同名的企业级技能则会压过这两个。插件里的技能不会撞名，因为名字前面带着插件名。
Claude Code 会监视 ~/.claude/skills/ 和项目的 .claude/skills/，在这两处新增、修改或删除技能都不用重启。只有一种情况例外：顶层的 skills 文件夹在会话开始时还不存在，这时要运行 /reload-skills 才能读到。
| 范围 | SKILL.md 放在哪里 |
|---|---|
| 企业级 | 托管设置目录里的 .claude/skills/my-skill/SKILL.md |
| 个人级 | ~/.claude/skills/my-skill/SKILL.md |
| 项目级 | .claude/skills/my-skill/SKILL.md |
| 嵌套 | 项目内的 some-folder/.claude/skills/my-skill/SKILL.md |
| 附加目录 | 用 --add-dir 传入的文件夹里的 .claude/skills/my-skill/SKILL.md |
| 插件 | my-plugin/skills/my-skill/SKILL.md |
测试它会触发，也测试它不乱触发
输入 What skills are available?，可以确认 Claude Code 看得到这个技能。要是你用自己的话提请求没反应，直接输入 /reviewing-sql-migrations 却能跑，技能本身就没问题，是匹配没成功。
同一个请求，这次触发了技能，下次可能就不触发。所以 Agent Skills 的描述优化指南建议准备 20 条左右的测试提示，应该触发和不该触发的各 8 到 10 条，每条都多跑几次。应该触发的提示，要在一半以上的运行里触发才算通过。模型也要逐个测：在 Opus 上好用的写法，换到 Haiku 可能还得写细，这是 Anthropic 编写指南里的提醒。
不该触发的那一组，最好挑近似提示。拿示例来说，“写一个加索引的迁移”和技能用词有重合，要的却是写迁移，不是审查。
- 按名字能跑，自己却从不触发：YAML 解析失败时，Claude Code 依然会加载正文，只是元数据全空，Claude 没有描述可以匹配。用
--debug启动 Claude Code，就能看到解析错误。 - 该触发时没触发：Claude Code 的排错清单第一条就是查描述里有没有用户会说的词。把描述放宽到这一类请求，别照搬失败提示里的词。
- 触发太频繁：把描述收窄，或加上
disable-model-invocation: true。 - 碰上不相干的请求也触发：在描述里写明技能不管什么，比如写新迁移，再写清哪些请求该交给相邻的技能。
常见问题
Claude Code 里的技能一定要有 name 字段吗？
Claude Code 不强制要求。头信息里的字段它都当作可选，名称默认取文件夹名，唯一推荐写的是描述。没写描述，它就拿正文第一行非空的文字顶上。开放规范则更严，两个字段都必须有。
怎样确认技能真的让结果变好，而不只是触发了？
同样的任务，用技能和不用技能各跑一遍，再比结果。技能装在插件里的话，claude plugin eval 会按你的测试用例两种情况各跑一遍，给差别打分。Anthropic 的 skill-creator 也有基准模式，把用和不用技能时的通过率、耗时和 token 数并排对比。
怎样让技能里的某条规则每次都生效？
交给 hook 来管。对应的事件每发生一次，比如每次编辑文件之前，Claude Code 就运行一次 hook，不管 Claude 这时还照不照着技能办事。技能自己也能在头信息的 hooks 字段里声明 hook，从被调用那一刻起，一直生效到会话结束。
可以让 Claude 帮我写技能吗？
Anthropic 说 Claude 本身就熟悉技能格式，所以可以让它把刚做完的任务整理成技能。它的指南建议开两个实例。第一个负责写技能、改技能。第二个是新开的，加载技能后拿真实任务去试。第二个哪里做漏了，就把情况带回给第一个去改。
为什么技能描述在 Claude Code 里被截断了？
因为技能清单的空间用完了。Claude Code 把所有描述塞进上下文窗口 1% 的预算里，超出时先去掉最少用的技能的描述。可以用 skillListingBudgetFraction 设置调大预算，或者在 skillOverrides 里把不常用的技能设成 "name-only"。
同一个技能能在 VS Code 或 Codex 里用吗？
多数情况下可以。Agent Skills 快速入门说，同一个技能能用在任何兼容的智能体里，Claude Code 和 OpenAI Codex 都算，它的 VS Code 示例则从 .agents/skills/ 读取技能。只是 allowed-tools 要小心：规范把它标为实验性字段，各家智能体支持程度不同。
资料来源
- Agent Skills 规范 https://agentskills.io/specification
- Agent Skills：快速入门 https://agentskills.io/skill-creation/quickstart
- Agent Skills：优化技能描述 https://agentskills.io/skill-creation/optimizing-descriptions
- Claude Platform 文档：技能编写最佳实践 https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- Claude Code 文档：技能 https://code.claude.com/docs/en/skills
- Claude Code 文档：创建 Claude Code 插件 https://code.claude.com/docs/en/plugins/create
- Claude Code 文档：有效管理成本 https://code.claude.com/docs/en/costs
- Claude 帮助中心：如何创建自定义技能 https://support.claude.com/en/articles/12512198-how-to-create-custom-skills
- Alex Albert 在 X 上：在 claude.ai、Claude Code 和 API 中推出技能 https://x.com/alexalbert__/status/1978877498411880550