# 28 · skill-creator 使用：用一个 skill 造你自己的 skill

> 📚 **系列导航**：上一篇 [27 Skills 使用实例] 教你怎么用好别人造的 skill——装进来、让它自动触发、用得顺手。这一篇反过来：教你造自己的。而且不靠手搓，靠官方那个专门用来造 skill 的 skill——`skill-creator`。

都说 `SKILL.md` 不就一个 markdown 文件嘛，自己手写就完了，犯得着再请个工具？

说句实话，这话只对了一半。**文件确实简单，但「造一个能被准确触发的 skill」这件事一点都不简单**——而手写翻车的，九成栽在同一个地方：`description` 写歪了，结果这 skill 永远叫不动。

我自己第一个手写的 skill 就是这么翻的。当时想做一个「生成符合团队规范的 commit message」的 skill，目录建好、正文写得明明白白，`description` 我随手填了句「Commit message helper」。结果呢？**每次让 Claude 提交，它压根不理我那个 skill，自己按通用习惯写一版**。我一口咬定是没装好，折腾半天 `/doctor`、重启、重装，全没用。后来才搞明白——**问题不在「装没装上」，在「描述里没有用户会说的那些词」**。这种坑，手写时你完全看不见，得有个东西逼你把它做对。

`skill-creator` 就是那个东西。

**看完这一篇，你会拿到：**

- 为什么手写 `SKILL.md` 看着省事、实际最容易踩坑，`skill-creator` 到底帮你做对了哪几件事
- `skill-creator` 的完整造 skill 流程：起脚手架 → 引导写 `name` / `description` / 正文 → 组织 `scripts` 和 `references` → 打包
- 全篇最值钱的一节：`description` 怎么写才能被准确触发（含触发场景关键词，还得「主动」一点）
- 个人 skill 和项目 skill 该落在哪个目录，谁能用到
- 一个能照着跑的动手实战：用 `skill-creator` 起一个最小 skill，并亲手验证它真的被触发了

---

## 01 反共识：手写 `SKILL.md` 不难，难的是「让它叫得动」

先把上一篇的底子接上。27 篇里你已经知道：一个 skill 就是一个目录，核心是里面那个 `SKILL.md`，顶上一段 YAML 写 `name` 和 `description`，下面是给 Claude 看的正文。官方文档原话：

> 每个 skill 都需要一个 `SKILL.md` 文件，包含两部分：YAML frontmatter（在 `---` 标记之间）告诉 Claude 何时使用该 skill，以及包含 Claude 在调用该 skill 时遵循的说明的 markdown 内容。

看着是不是特简单？建个文件夹、写个文件，齐活。所以新手第一反应都是：**手写就行了，要什么工具**。

这就是那个**反共识的点**：手写本身确实不难，**难的是手写出来的 skill「叫不动」——你以为它会在该出场的时候自动出场，结果它一直在角落里睡觉**。

**类比：填一张表单的「造工具向导」。** 你装新软件时见过那种向导吧——它不让你对着空白配置文件瞎填，而是一页一页问你「这工具叫什么」「什么情况下该用它」「输入长啥样、输出要什么格式」，你回答几个问题，它在背后把目录结构、脚手架、各字段的位置全给你摆对。`skill-creator` 就是 skill 界的这种向导：**你回答它几个问题，它把那些「手写时你根本想不到要管」的事替你做对**。

具体它替你兜住了哪几个手写最容易翻的坑？看这张对照表——**这是本节最该记住的**：

| 容易翻车的环节 | ❌ 纯手写常见结果 | ✅ `skill-creator` 帮你做对 |
|--------------|----------------|--------------------------|
| `description` | 写成「Commit helper」这种，缺触发词，永远不触发 | 引导你写清「干什么 + 什么时候用」，含用户会说的关键词 |
| 目录结构 | 把脚本、参考文档全塞进 `SKILL.md`，又长又乱 | 帮你分到 `scripts/` `references/`，正文保持精简 |
| 触发验证 | 写完不知道到底触不触发，全靠玄学 | 给你测试用例，跑一遍看它到底叫不叫得动 |
| 改进 | 没触发只能干瞪眼，不知道改哪 | 有专门的描述优化环节，对着触发率调 |

看出来没？**手写翻的车，全是「你看不见所以没管」的事**。`skill-creator` 的价值不是帮你打字（打字它没快多少），而是**逼你把这几件隐形的事一件不落地做对**。

> 💡 一句话总结：手写 `SKILL.md` 不难，难在让它在该触发时真触发；**`skill-creator` 像个填表造工具的向导，把 `description`、目录、验证、改进这几件「手写时看不见」的事替你兜住**。

---

## 02 `skill-creator` 是什么、怎么请它出场

先给结论：**`skill-creator` 本身就是一个 skill，它的专长是「造别的 skill」**。听着像绕口令，但逻辑很顺——既然 skill 是用来扩展 Claude 能力的，那「造 skill」这件重复性工作，本身就值得做成一个 skill。

它不是 Claude Code 自带就有的（不像 `/code-review`、`/debug` 那几个捆绑 skill），需要单独安装——把 skill 目录放到 `~/.claude/skills/`（个人全局）或项目的 `.claude/skills/`（只对这个项目生效），第 27 篇已讲过这套机制。官方插件市场（`claude-plugins-official`）里对应「创建插件」的工具包叫 `plugin-dev`，`skill-creator` 是独立发布的 skill，安装方式是直接克隆或下载目录到 skills 路径：

```bash
# 把 skill-creator 目录放到个人 skills 目录
cp -r skill-creator ~/.claude/skills/
```

**预期**：放好后，`/skills` 列表里能看到 `skill-creator`，描述写着「Create new skills, modify and improve existing skills...」。

装好之后，请它出场有两种姿势，**跟 27 篇讲的「用 skill」一模一样**：

**姿势一：直接喊名字（明确指令）。**

```text
/skill-creator
```

**姿势二：用大白话说你要干啥（让它自动触发）。** 这也是更常用的一种——因为 `skill-creator` 的 `description` 写得很「全」，你说「我想做一个 skill 来干 XX」它就接住了：

```text
我想做一个 skill，每次帮我把 git 改动总结成一条规范的 commit message
```

不管哪种姿势，接下来它都不会闷头给你甩一个文件，而是**像向导一样开始问你问题**。官方那个 `skill-creator` 的说明里，第一步就叫「Capture Intent（捕捉意图）」，它会问你这么几件事：

> 1. 这个 skill 要让 Claude 能干什么？
> 2. 它应该在什么时候触发？（用户会用哪些说法 / 在什么场景）
> 3. 期望的输出格式是什么？
> 4. 要不要建测试用例来验证它能正常工作？

注意第 2 问——**「什么时候触发」它会专门问你一遍**。这就是它跟手写最大的不同：手写时这个问题没人逼你回答，你随手糊一个描述就过去了；`skill-creator` 把它当头等大事，因为它知道**这一问答不好，造出来的 skill 就是个废物**。

**类比：婚礼策划师接单先把你问个底朝天。** 靠谱的策划不会上来就甩方案，他先问「预算多少」「请多少人」「想要中式还是户外」「有没有忌讳」。把这些问透了，出的方案才贴你的需求，而不是套个模板了事。`skill-creator` 的「Capture Intent」就是这道「问需求」工序——**先把你要什么问明白，再动手攒 skill**。

> 💡 一句话总结：`skill-creator` 是个「造 skill 的 skill」，从官方插件市场装（需魔法上网）；喊 `/skill-creator` 或大白话说需求都能唤出它，**它出场第一件事是反过来问你问题，尤其会专门问「这 skill 什么时候该触发」**。

---

## 03 它替你走完的完整流程

`skill-creator` 不是只帮你生成一个文件就撒手，它会**陪你走完造 skill 的一整条流水线**。把它的流程拆开看，你就知道每一步它在帮你兜什么。

官方 `skill-creator` 把整个过程概括成一个循环，我给你翻成大白话：

1. **想清楚要干啥**：先跟你聊明白这 skill 做什么、大概怎么做（就是上一节的「Capture Intent」）。
2. **写初稿**：根据你的回答，填好 `name`、`description` 和正文，生成 `SKILL.md`。
3. **建测试用例**：写 2-3 个「真实用户会说的话」当测试 prompt，问你「这几个测试像不像样，要不要加」。
4. **跑一遍 + 评估**：拿这些 prompt 实际跑，让你看结果好不好——既看「输出对不对」，也看「该触发的有没有触发」。
5. **照反馈改**：根据你的评价和测试结果回头改 skill，**改完再跑一轮**，直到你满意。
6. **（可选）优化描述**：专门有个环节优化 `description`，把触发准确率往上调。
7. **打包**：最后把整个 skill 目录打成一个 `.skill` 文件，方便你分发或安装。

看出这条流水线的门道没？**手写时你只做了第 2 步（写个文件），后面 3-7 全跳过了**——所以你的 skill 触不触发全凭运气，触不动也不知道怎么改。`skill-creator` 的价值就在于它**把 2 之后那几步当成必修课**，尤其是「跑测试看触发」和「照反馈改」这个循环。

这里穿插一个**它帮你做对的目录结构**。官方文档「添加支持文件」一节给的目录示例是这样的：

```text
my-skill/
├── SKILL.md           # 主要说明（必需）
├── reference.md       # 详细参考文档，按需加载
├── examples.md        # 示例输出，按需加载
└── scripts/
    └── helper.py      # Claude 可以执行的脚本
```

关键认知：**`SKILL.md` 要短，重的东西往外放**。官方原话点得很透：

> 将 `SKILL.md` 保持在 500 行以下。将详细的参考资料移到单独的文件中。

为啥要这么分？因为 skill 一旦触发，`SKILL.md` 的内容会**整段进上下文、并在整个会话里赖着不走**——每一行都是重复的 token 成本。而 `scripts/` 里的脚本是「执行但不加载」、`references/` 里的文档是「需要时才读」。**手写最容易犯的错，就是把一份三百行的 API 文档直接糊进 `SKILL.md`**，又占上下文又乱。`skill-creator` 会引导你把这些分门别类放对地方——正文只留「干什么、去哪找」，重资料挪进 `references/`，可执行的活儿挪进 `scripts/`。

**类比：写一本书的目录页和附录。** 你不会把所有内容都堆在目录页上，目录页只写「第几章讲什么、在哪一页」，详细内容在正文和附录里。`SKILL.md` 就是那张目录页——**它告诉 Claude「有哪些料、什么时候去翻哪一份」，料本身放在 `references/` 和 `scripts/` 里**。

> 💡 一句话总结：`skill-creator` 陪你走的是「想清楚 → 写初稿 → 跑测试看触发 → 照反馈改 → 优化描述 → 打包」一整条流水线；**手写往往只做了第二步，它把后面那几步补全了**，还会引导你把重资料分到 `references/` 和 `scripts/`、让 `SKILL.md` 保持精简。

---

## 04 全篇最值钱的一节：`description` 怎么写才叫得动

如果这篇你只记一件事，记这件：**`description` 是决定一个 skill 触不触发的「总开关」**。

为什么是它？因为 Claude 在每次对话里，看到的不是你 skill 的全文——**它先看到的只是一串「skill 名字 + description」的清单**，然后根据这个 description 判断「这次该不该把这个 skill 调出来」。description 写得对不对，直接决定它会不会被想起来。官方在「Skill 未触发」的排查里，第一条就是冲着它去的：

> 检查描述是否包含用户会自然说的关键字。

开头我那个翻车的 commit skill，病根就在这。写的是「Commit message helper」——**这句话里一个「用户会说的词」都没有**。我平时嘴里蹦出来的明明是「帮我提交」「写个 commit」「生成提交信息」，可描述里这些词一个没有，Claude 自然对不上号。后来我让 `skill-creator` 把描述改成下面这样，再喊一句「帮我提交」，它立马就接住了。

对照一下这两种写法，差距一目了然：

| ❌ 手写常见的废描述 | ✅ `skill-creator` 引导出的好描述 |
|------------------|------------------------------|
| `Commit message helper` | `把暂存的改动总结成一条符合团队规范的 commit message。当用户说「帮我提交」「写个 commit」「生成提交信息」或让你 review 改动准备提交时使用。` |
| 只说了「是什么」 | **既说「干什么」，又说「什么时候用、用户会怎么说」** |
| 缺触发词，永远不触发 | 含真实触发词，该出场时准时出场 |

提炼成一句口诀：**好的 description = 干什么 + 什么时候用（含用户会说的那些原话词）**。「干什么」让 Claude 知道这工具是干嘛的，「什么时候用」才是真正的触发钩子——而且这部分要尽量写成**用户嘴里会蹦出来的大白话**，不是你脑子里的术语。

还有一个反直觉的点，是从 `skill-creator` 那儿能学到的：**描述要「主动」一点，甚至略微「催」一点**。因为目前 Claude 有个倾向，叫「undertrigger（该用没用）」——它经常在 skill 明明能帮上忙时，懒得调出来。`skill-creator` 的内部说明里专门叮嘱要对抗这个：

> 目前 Claude 有不愿触发 skill 的倾向——在 skill 本可派上用场时不去用它。为对抗这一点，请把 skill 描述写得稍微「主动」一些。

什么叫「主动」？举个它给的例子的味道：与其干巴巴写「构建一个展示内部数据的仪表盘」，不如写成「……**只要用户提到仪表盘、数据可视化、内部指标，或者想展示任何公司数据，哪怕没明说要『仪表盘』，都该用这个 skill**」。**把「即使用户没明说，也该出场」的场景显式写进去**——这一手能显著提高它被叫动的概率。

**类比：给店门口的招牌写文案。** 招牌只写「张记」，路人不知道你卖啥，不会进来；写成「张记牛肉面 · 加面免费 · 辣的不辣的都有」，把客人可能搜的词都铺上，进店的人立马多了。**`description` 就是你这个 skill 的招牌——招牌上要有顾客嘴里会念叨的词，还得主动招呼**。

> 💡 一句话总结：`description` 是触发总开关，公式是「**干什么 + 什么时候用（含用户会说的原话关键词）**」，而且要写得略微主动、把「没明说也该出场」的场景铺进去——**这一句写好了，skill 才叫得动；写歪了，正文再漂亮也白搭**。

---

## 05 落在哪个目录：个人 skill vs 项目 skill

skill 造好了，存哪儿？**存的位置直接决定谁能用到它**。这点 `skill-creator` 会问你，但你得自己心里有数。

官方给的位置表，挑出小白最常用的两档：

| 位置 | 路径 | 谁能用 |
|------|------|--------|
| **个人** | `~/.claude/skills/<skill-name>/SKILL.md` | 你电脑上的**所有项目** |
| **项目** | `.claude/skills/<skill-name>/SKILL.md` | **仅当前这个项目** |

怎么选？就一个判断标准：**这 skill 是「你的私人习惯」还是「这个项目的规矩」？**

- **你个人到哪都想用的**——比如「按我喜欢的风格写 commit」「把选中文字翻成中文」——放**个人目录**（`~/.claude/skills/`），一处安家，所有项目通用。
- **跟具体项目绑死的**——比如「按本仓库的 API 规范生成接口」「跑这个项目特有的部署流程」——放**项目目录**（`.claude/skills/`），而且**提交进 Git**，这样团队每个人 clone 下来都自动有这个 skill。

**类比：随身工具包 vs 工地工具房。** 你那把惯用的瑞士军刀，揣兜里走到哪带到哪（个人 skill）；但某个工地专用的大型设备，就锁在那个工地的工具房里，换个工地用不上、也带不走（项目 skill）。**判断依据就是「这工具是跟着人走，还是跟着场子走」**。

一个简单好记的分法：**通用习惯类全进 `~/.claude/skills/`，项目专属类进各自的 `.claude/skills/` 并提交 Git**。像翻译 skill、commit skill 这类，常年待在个人目录，跟着你跑遍所有项目；而每个团队项目里那些「本项目专用」的 skill，一律提交进仓库——**这样新人 clone 完，连 skill 都一起到位了，不用再口头交代「记得装那几个 skill」**。

> 还有个好处官方点过：项目 skill 会从你的起始目录一路往父目录找，所以你在子目录里启动 Claude，根目录定义的项目 skill 照样能被拾到。monorepo 里各个子包还能有自己的 skill，互不打架。

> 💡 一句话总结：个人 skill 放 `~/.claude/skills/`、跟着你跑遍所有项目；项目 skill 放 `.claude/skills/` 并提交 Git、只在本项目生效且团队共享；**判断就一句话——这工具是跟着人走，还是跟着项目走**。

---

## 06 动手：用 `skill-creator` 起一个最小 skill 并验证触发

光看不练假把式。下面带你用 `skill-creator` 真造一个最小 skill，**最关键的是亲手验证它确实被触发了**——这一步正是手写党最容易跳过、也最容易翻车的地方。全程不依赖任何复杂项目。

我们造的目标 skill 很小：**让 Claude 把当前 git 仓库里未提交的改动，总结成几条要点**。

**第一步：确认 `skill-creator` 已就位**

启动 Claude Code 后，敲：

```text
/skills
```

**预期**：列表里能看到 `skill-creator`。看不到的话，回第 02 节把 `skill-creator` 目录拷进 skills 路径装一下（记得开魔法上网）。

**第二步：用大白话让它开造**

在输入框里说清你要什么（顺手把「什么时候触发」也讲了，省得它再追问）：

```text
用 skill-creator 帮我做一个 skill。
功能：把当前 git 仓库里未提交的改动总结成 2-3 条要点。
触发场景：当我问「我改了啥」「总结一下我的改动」「我这次动了哪些东西」的时候。
名字就叫 summarize-changes。
```

**预期**：`skill-creator` 被唤起，开始跟你确认意图——可能反问你输出格式、要不要建测试用例。顺着它问的答就行，**重点盯它生成的 `description` 里有没有把「我改了啥」「总结改动」这些触发词写进去**（这是第 04 节的命根子）。

**第三步：让它把文件落到个人目录**

确认它要把 skill 写到 `~/.claude/skills/summarize-changes/`（个人目录，所有项目可用）。它生成的 `SKILL.md` 大概长这样——你重点核对 frontmatter：

```yaml
---
name: summarize-changes
description: 把当前 git 仓库里未提交的改动总结成几条要点。当用户问「我改了啥」「总结一下我的改动」「我这次动了哪些东西」，或想快速了解工作树现状时使用。
---

## 当前改动

!`git diff HEAD`

## 你的任务

把上面的改动用 2-3 条要点总结清楚。如果 diff 为空，就说一句「当前没有未提交的改动」。
```

> 那行 `` !`git diff HEAD` `` 是官方的「动态上下文注入」写法：Claude Code 会**先把这条命令跑掉**，把这行替换成真实的 diff，再让 Claude 看到 skill 内容。所以它拿到的是你工作树的实际改动，不是凭空猜的。这个语法 27 篇提过，这里正好用上。

**第四步：制造一点改动，好让 skill 有东西可总结**

找任意一个 git 项目（没有就 `git init` 一个空的），随便改个文件。比如：

```bash
cd ~/some-git-project
echo "// test change" >> README.md
```

**预期**：`git status` 能看到 `README.md` 被改了、处于未提交状态。

**第五步（最关键）：验证它真的被「触发」**

这一步分两种验证，**官方文档明确给了这两条路**：

**验证 A——自动触发**：在 Claude Code 里用大白话问（注意，**别提 skill 名字**，就用自然说法，看它会不会自己想起来）：

```text
我改了啥？
```

**预期**：如果 `description` 写对了，Claude 会**自动调起 `summarize-changes`**，吐出几条改动要点（比如「README.md 末尾新增了一行注释」）。**它能自己接住 = 触发成功，你的 `description` 关过了**。

**验证 B——直接调用**：万一自动没触发，再用名字硬点一次：

```text
/summarize-changes
```

**预期**：这次一定会跑，同样吐出改动要点。

**怎么判断成败**：

| 现象 | 说明 | 该咋办 |
|------|------|--------|
| 验证 A、B 都出要点 | 触发完美 | 收工 |
| A 不触发、B 能跑 | **`description` 关键词不够**，正文没毛病 | 让 `skill-creator` 优化描述，补触发词 |
| A、B 都不出要点 | 文件没建对 / 正文有问题 | 核对路径和 `SKILL.md` 正文 |

**重点体会中间那行**——A 不触发但 B 能跑，恰恰证明了本篇的核心论点：**skill 本身没问题，问题在「叫不叫得动」，而叫不动几乎总是 `description` 的锅**。这正是手写党踩了无数次、却始终没意识到的那个坑。这时让 `skill-creator` 走一遍「描述优化」就能救回来。

跑通这五步，你就把「起脚手架 → 写对 description → 落到正确目录 → 制造改动 → 验证自动触发 / 直接调用」这条完整链路亲手验了一遍。**以后造任何 skill，本质都是在这套流程上换内容。**

> 💡 一句话总结：动手就盯两件事——**生成的 `description` 里有没有真实触发词、用大白话问它会不会自动出场**；自动不触发但 `/名字` 能跑，就是 `description` 的锅，让 `skill-creator` 优化描述补关键词。

---

## 07 一个加分项：打包成 `.skill` 分发给别人

skill 造好、验过触发，如果你想发给同事或团队，`skill-creator` 还能帮你**打包成一个 `.skill` 文件**——对方拿到一个文件就能装，不用你手把手教他建目录。

它背后跑的是一个打包脚本，你不用记命令，**直接让 `skill-creator` 帮你打包就行**：

```text
帮我把这个 skill 打包成 .skill 文件
```

**预期**：它会运行打包脚本，把整个 `summarize-changes/` 目录（含 `SKILL.md` 和所有 `scripts/`、`references/`）压成一个 `summarize-changes.skill` 文件，并告诉你文件路径。

这一步的意义在于**分发**：上一篇 27 教你「装别人的 skill」，这一篇你造出来的 skill，打包后**正好就是别人那边要装的东西**——一前一后闭环了。团队内部传 skill 通常就是这么干的：谁造了个好用的，打包丢群里，别人下下来一装就有，比口头讲「你照着我这个目录建一下」靠谱多了。

> 💡 一句话总结：造好的 skill 让 `skill-creator` 打包成 `.skill` 文件，**一个文件即可分发**；这恰好接上了 27 篇「装别人的 skill」——你造的，就是别人装的。

---

## 08 小结

这一篇我们从「为什么别纯手写」一路走到「亲手造一个能触发的 skill」——**核心就一句话：造 skill 的难点不在写文件，在让它叫得动，而 `skill-creator` 专治这个**。

把要点串起来回顾：

| 你要做的事 | 用什么 | 关键点 |
|-----------|--------|--------|
| 装造 skill 的工具 | 克隆 / 拷贝目录到 skills 路径 | `cp -r skill-creator ~/.claude/skills/`（独立发布的 skill，非市场内置） |
| 唤起它开造 | `/skill-creator` 或大白话说需求 | 它会反问你「干什么、何时触发」 |
| 让 skill 叫得动 | 写好 `description` | 干什么 + 何时用（含用户原话词），略微主动 |
| 选存放位置 | 个人 vs 项目目录 | 跟着人走放 `~/.claude/`，跟着项目走放 `.claude/` 并提交 Git |
| 确认成败 | 自动触发 + `/名字` 直接调 | 自动不触发=description 的锅 |
| 分发给别人 | 打包成 `.skill` | 一个文件即可安装，接上 27 篇 |

**你现在应该能：** 看懂为什么手写 `SKILL.md` 容易翻在触发上、用 `skill-creator` 走完「起脚手架 → 写对 description → 测触发 → 打包」整条流程，亲手写出一句「叫得动」的 `description`，把 skill 放进对的目录，并验证它真的被触发了。**这套「造得对、叫得动」的能力，是你从『用别人的 skill』升级到『打造自己的工具链』的分水岭。**

开头那个翻车的 commit skill，后来用 `skill-creator` 重造一遍，**前后就改了一句 `description`，从此再没掉过链子**。这就是这工具最值钱的地方——它不让你多打字，它让你少踩那个看不见的坑。

> 💡 一句话总结：造 skill 难在触发，`skill-creator` 把「写对 description、跑测试、照反馈改」这几件手写时容易跳过的事补全了——**会造 skill 的关键，是学会把触发条件说清楚，而不只是把功能写明白**。

---

下一篇 **29「Agent teams 智能体团队」**（实验性，可能变化）——到这儿为止，你的 Claude Code 一直是「单兵作战」：一个会话、一个助手，你跟它一对一。但有些活儿一个人扛太慢——能不能像组个项目组那样，让**多个智能体分工协作、一个管架构一个写代码一个跑测试**？下一篇就带你从「单兵」迈进「团队作战」。想想看：如果手头能同时有三个 Claude 给你干活，你最先想让它们分头干哪三件事？
