# 怎样创建 Agent Skill：写出你的第一个 SKILL.md

> 创建 Agent Skill，就是建一个以技能命名的文件夹，里面放一个 SKILL.md：开头是写着名称和描述的 YAML 头信息，后面用 Markdown 写操作说明。用在 Claude Code 里，文件夹放进 `~/.claude/skills/` 或项目的 `.claude/skills/`。智能体会不会自己加载这个技能，要看你的请求和描述对不对得上。

Mindket 编辑部 · 发布于 2026-10-26 · 更新于 2026-11-03 · https://mindket.com/cn/blog/how-to-create-agent-skill

## 要点

- 技能将来可能放到 Claude.ai 上，描述就从一开始按 Claude.ai 的上限来写。
- 挑一件你总得跟智能体反复交代的事，把它写成技能。
- 每条测试提示都多跑几遍，还要放进近似提示。

## 六步创建一个技能

下面的示例技能在 Claude Code 里审查 SQL 迁移文件，专找会删数据、或者没法回滚的步骤。这类每次都得跟智能体重新交代一遍的活，就该做成技能。每个任务都适用的规则就不一样了，该写进 [CLAUDE.md](https://mindket.com/cn/blog/claude-md-file)，Claude Code 每次会话开始都会加载它。

先写描述，再写正文。请求对上之前，[智能体只看得到技能的名称和描述](https://mindket.com/cn/blog/what-are-agent-skills)。描述要写清技能做什么、什么时候用。[Anthropic 的编写指南](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)还要求用第三人称来写，因为描述会被注入系统提示。

````markdown
---
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.

````

1. 建文件夹，名字用动名词形式。Anthropic 的指南举的例子是 `processing-pdfs`，`helper`、`utils` 这类含糊的名字不推荐。想在所有项目里用，运行 `mkdir -p ~/.claude/skills/reviewing-sql-migrations`。只给一个仓库用，就在仓库里建 `.claude/skills/reviewing-sql-migrations`。
2. 把上面的内容存成这个文件夹里的 `SKILL.md`。`name` 必须和文件夹同名。
3. 正文写成编号步骤，说清你要什么样的输出，最后加一个 Gotchas 清单，列出不提醒就会弄错的事实。
4. 技能用得到的话，加上正文提到的两个文件：`scripts/changed_migrations.sh` 和 `references/locks.md`。
5. 检查头信息。在 Claude Code v2.1.233 及以上版本里，`claude plugin validate ~/.claude/skills` 能找出 YAML 解析失败的 SKILL.md。参考工具 `skills-ref validate ./reviewing-sql-migrations` 则按规范检查一个文件夹。
6. 在 Claude Code 里用自己的话提出任务，比如“这个迁移能合并吗？”，再运行 `/reviewing-sql-migrations`，按名字直接调用技能。

[![Alex Albert（@alexalbert__）2025 年 10 月 16 日在 X 上的帖子：今天我们在 claude.ai、Claude Code 和 API 里推出 Skills，它让你把专业知识打包成可复用的能力，由 Claude 按需加载。下面是一张题为 Agent + Skills + Virtual Machine 的示意图，智能体的文件系统里有 bigquery、docx、pdf 等技能文件夹，每个文件夹里都有一个 SKILL.md 文件](https://mindket.com/blog/shots/x-alexalbert-skills-launch.webp?v=bbc2880b3e78)](https://x.com/alexalbert__/status/1978877498411880550)

Alex Albert 在 X 上，2025 年 10 月 16 日

> X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 3 日，时间为美国太平洋时间。点击截图可到 X 上打开原帖。

## 各产品不一样的头信息限制

Anthropic 的帮助文章规定，上传到 Claude.ai 的技能，描述最多 200 个字符，开放规范则放宽到 1,024 个。

Claude Code 自己还认几个字段，都列在它的[技能文档](https://code.claude.com/docs/en/skills)里。设了 `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 帮助中心 |

**描述能有多少个字符，取决于技能在哪里运行** 金色那条是最小的上限。Claude Code 的数字，是 `description` 和 `when_to_use` 加起来被截断的位置。

- 上传到 Claude.ai: **200 个字符**
- 开放规范: 1,024 个字符
- Claude Code 的技能列表: 1,536 个字符

来源：[Claude 帮助中心：如何创建自定义技能](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills) (2026-11-03 查阅)；[Agent Skills 规范](https://agentskills.io/specification) (2026-11-03 查阅)；[Claude Code 文档：技能](https://code.claude.com/docs/en/skills) (2026-11-03 查阅)

## 正文写什么，脚本放哪里

技能被调用时，Claude Code 把正文放进对话，就放这一次，后面几轮[不会再读这个文件](https://code.claude.com/docs/en/skills)。所以要写“每次改完都跑测试”，别只写“跑测试”。

长会话压缩以后，Claude Code 可能只留下已调用技能的开头部分。必须一直生效的步骤写在 SKILL.md 最前面，背景说明放到后面。

Claude 是运行一个脚本还是阅读它，取决于 SKILL.md 里那一行怎么写。在 [Anthropic 的指南](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)里，“运行 analyze_form.py 提取字段”是让它执行，“参见 analyze_form.py 了解提取算法”是让它读。路径一律用正斜杠，Windows 上也一样，反斜杠在 Unix 系统上会出错。

示例里的路径都从技能文件夹算起。在 Claude Code 里，`${CLAUDE_SKILL_DIR}/scripts/changed_migrations.sh` 这样的路径，不管技能装在哪里都能找对，插件里也一样。

````text
reviewing-sql-migrations/
├── SKILL.md
├── scripts/
│   └── changed_migrations.sh
└── references/
    └── locks.md
````

## Claude 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 的描述优化指南](https://agentskills.io/skill-creation/optimizing-descriptions)建议准备 20 条左右的测试提示，应该触发和不该触发的各 8 到 10 条，每条都多跑几次。应该触发的提示，要在一半以上的运行里触发才算通过。模型也要逐个测：在 Opus 上好用的写法，换到 Haiku 可能还得写细，这是 Anthropic 编写指南里的提醒。

不该触发的那一组，最好挑近似提示。拿示例来说，“写一个加索引的迁移”和技能用词有重合，要的却是写迁移，不是审查。

**Agent Skills 指南建议的测试方案**

- **20** 条查询组成一套测试，其中约 8 到 10 条应该触发技能，8 到 10 条不该触发 (来源：[Agent Skills：优化技能描述](https://agentskills.io/skill-creation/optimizing-descriptions), 2026-11-03 查阅)
- **3** 次：每条查询跑 3 遍是个合理的起点，因为同一条查询这次能触发技能，下次也可能不触发 (来源：[Agent Skills：优化技能描述](https://agentskills.io/skill-creation/optimizing-descriptions), 2026-11-03 查阅)
- **60** 次调用：20 条查询各跑 3 遍，指南说这最好写成脚本来跑 (来源：[Agent Skills：优化技能描述](https://agentskills.io/skill-creation/optimizing-descriptions), 2026-11-03 查阅)
- **40%** 的查询留出来当验证集，只用来检查你的修改是不是对没见过的查询也有效 (来源：[Agent Skills：优化技能描述](https://agentskills.io/skill-creation/optimizing-descriptions), 2026-11-03 查阅)

- 按名字能跑，自己却从不触发：YAML 解析失败时，Claude Code 依然会加载正文，只是元数据全空，Claude 没有描述可以匹配。用 `--debug` 启动 Claude Code，就能看到解析错误。
- 该触发时没触发：[Claude Code 的排错清单](https://code.claude.com/docs/en/skills)第一条就是查描述里有没有用户会说的词。把描述放宽到这一类请求，别照搬失败提示里的词。
- 触发太频繁：把描述收窄，或加上 `disable-model-invocation: true`。
- 碰上不相干的请求也触发：在描述里写明技能不管什么，比如写新迁移，再写清哪些请求该交给相邻的技能。

## 通过仓库、插件、Claude.ai 或 Mindket 分享

只在团队内部用，把文件夹提交进仓库就够了。

要分享到仓库以外，可以做成[插件](https://code.claude.com/docs/en/plugins/create)：技能放进 `my-plugin/skills/reviewing-sql-migrations/`，和它并列的是 `.claude-plugin/plugin.json`，必填字段只有 `name`。`claude --plugin-dir ./my-plugin` 能在一次会话里加载这个插件，这时技能的命令是 `/my-plugin:reviewing-sql-migrations`。

按 [Anthropic 帮助文章](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills)的要求，Claude.ai 收的是 zip 包：技能文件夹放在压缩包根目录，以技能名命名，不能把文件散着放。上传后到 Customize > Skills 里启用，代码执行也得开着。

Mindket 的[技能页](https://mindket.com/cn/skills)放的是粘贴进 AI 对话用的提示词技能，格式不一样。所以 SKILL.md 文件夹在 Mindket 上以套件的形式上架：在[出售页](https://mindket.com/cn/sell)填好介绍，用积分定价或设为免费。套件是一组文本文件，买家以 zip 包下载，里面的东西不会自己运行。像 `changed_migrations.sh` 这样的脚本会让条目先交给管理员审核，任何文件里出现服务商密钥或私钥，上传都会被拦下。

> 这里的每个事实都来自文中链接的页面和下方的来源列表，阅读日期为 2026 年 11 月 2 日和 3 日，Mindket 的做法取自它自己的页面。本文不是实测，示例技能是为本文写的。

## 常见问题

### 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 快速入门](https://agentskills.io/skill-creation/quickstart)说，同一个技能能用在任何兼容的智能体里，Claude Code 和 OpenAI Codex 都算，它的 VS Code 示例则从 `.agents/skills/` 读取技能。只是 `allowed-tools` 要小心：规范把它标为实验性字段，各家智能体支持程度不同。

## 资料来源

- [Agent Skills 规范](https://agentskills.io/specification) (2026-11-03 查阅)
- [Agent Skills：快速入门](https://agentskills.io/skill-creation/quickstart) (2026-11-02 查阅)
- [Agent Skills：优化技能描述](https://agentskills.io/skill-creation/optimizing-descriptions) (2026-11-03 查阅)
- [Claude Platform 文档：技能编写最佳实践](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) (2026-11-02 查阅)
- [Claude Code 文档：技能](https://code.claude.com/docs/en/skills) (2026-11-03 查阅)
- [Claude Code 文档：创建 Claude Code 插件](https://code.claude.com/docs/en/plugins/create) (2026-11-02 查阅)
- [Claude Code 文档：有效管理成本](https://code.claude.com/docs/en/costs) (2026-11-02 查阅)
- [Claude 帮助中心：如何创建自定义技能](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills) (2026-11-03 查阅)
- [Alex Albert 在 X 上：在 claude.ai、Claude Code 和 API 中推出技能](https://x.com/alexalbert__/status/1978877498411880550) (2026-11-03 查阅)

[开始出售](https://mindket.com/cn/sell)