10｜16 小时 Claude Code：Agent Skills，把重复工作变成可复用能力

26 · Agent Skills：给 Claude 装一身随叫随到的专项本事

「Skill 不就是个 slash 命令换了个名字吗？我打 /deploy 它就跑部署，跟以前 .claude/commands/deploy.md 有啥区别？」

「区别大了。slash 命令是你主动喊它才动；Skill 你可以不喊——Claude 一看你这活儿对得上，自己就把它调出来了。而且它平时只占你一句话的位置，用到才展开全文。」

「……自己调出来？那不就乱套了，我哪知道它什么时候会动？」

这是个很常见的误解，我自己刚上手那会儿就这么想的——把已有的 commit.md 命令塞进 .claude/skills/ 里，跑起来跟以前一模一样，我还纳闷「这不就换了个文件夹吗」。后来才反应过来，问题就卡在：把 Skill 当成 slash 命令的马甲。其实官方早就把自定义命令并进了 Skills 体系——你那些 .claude/commands/ 文件照样能用，但 Skill 多了三样东西：能带配套文件、能由 Claude 按需自动触发、平时几乎不占上下文。

官方原话：「自定义命令已合并到 skills 中。 .claude/commands/deploy.md 中的文件和 .claude/skills/deploy/SKILL.md 中的 skill 都会创建 /deploy 并以相同的方式工作。」

这一篇，我把 Skill 到底是什么、凭什么能「自己调出来」还不撑爆上下文、从哪来、怎么触发，一次给你讲透。

看完这一篇，你会拿到：

• Skill 到底是什么——一个 SKILL.md 加配套资源，怎么就成了 Claude 的一项本事
• 它如何「按需加载」（渐进式披露）：为什么平时只占一句话、用到才展开，省上下文的秘密全在这
• Skill、slash 命令、Subagent 三者定位差在哪，一张表分清（完整决策留到第 30 篇）
• Skill 从哪来（内置、插件带、自己写）、放在哪个目录决定谁能用
• 怎么触发（靠 description 自动匹配，不用背命令）、怎么查当前有哪些可用

01 先搞懂：Skill 到底是个什么东西

先给结论：一个 Skill，本质就是一个叫 SKILL.md 的说明文件，外加几个可选的配套文件，打包成一身「专项本事」交给 Claude。

类比：手机里的快捷指令。 你在 iPhone「快捷指令」里编一个「回家模式」——开灯、调空调、放音乐，编好之后你不用再一步步手动操作，喊一句「回家模式」，它就按你排好的顺序自动跑完。Skill 干的是同一件事：你把一套固定流程（比如「总结未提交的改动并标出风险」）写进 SKILL.md，之后这套流程就成了 Claude 随手能调的一个动作，你不用每次把步骤重新敲一遍。

SKILL.md 长什么样？就两部分，官方文档说得很清楚（这个例子存在 ~/.claude/skills/summarize-changes/SKILL.md，目录名 summarize-changes 就是你以后输入的命令名）：

---
description: 总结未提交的改动并标出风险。当用户问改了啥、想要提交信息、或让我审查 diff 时使用。
---

## 当前改动

!`git diff HEAD`

## 说明

把上面的改动用两三个要点概括，再列出你注意到的风险，比如缺失的错误处理、写死的值、需要更新的测试。如果 diff 是空的，就说没有未提交的改动。

上面那个 --- 框起来的部分叫 YAML frontmatter（前置元数据，写在文件开头两道 --- 之间的配置区），它告诉 Claude 这个 Skill 是干啥的、啥时候该用；下面的 markdown 正文，是 Claude 真正调用时要照着做的说明。

注意中间那行 !`git diff HEAD`——这是个挺妙的设计，叫动态上下文注入：Claude Code 会先把这条命令跑了，把它的输出替换到这一行，然后 Claude 才看到 Skill 内容。所以 Claude 拿到手的不是「去跑个 diff」，而是已经填好的、你此刻真实的改动。这是预处理，不是 Claude 自己执行的。

一个 Skill 不止 SKILL.md 一个文件，它是个目录。官方给的标准长相是这样：

my-skill/
├── SKILL.md           # 主说明（必需）
├── template.md        # 让 Claude 填的模板
├── examples/
│   └── sample.md      # 给它看的示例输出
└── scripts/
    └── validate.sh    # 它可以执行的脚本

只有 SKILL.md 是必需的，其余都可选。这就是 Skill 比老式 slash 命令强的地方：能带模板、带示例、带脚本——脚本可以是任何语言，Claude 负责编排，脚本干重活。

三个真实场景，你立刻能想到 Skill 能干嘛：

• 你每次让 Claude 提交代码，都要叮嘱「先跑测试、再写中文 commit、前缀用 feat」——把这套写进一个 commit Skill，以后一句话搞定。
• 团队约定了一套 API 写法（RESTful 命名、统一错误格式、必带校验）——写成一个 api-conventions Skill，谁写接口它自动按这套来。
• 你想生成一张代码库的可视化结构图——官方那个 codebase-visualizer Skill 捆了个 Python 脚本，跑完直接在浏览器里打开交互式树图。

💡 一句话总结：Skill 就是「SKILL.md（说啥时候用 + 怎么做）+ 可选配套文件」打成一包的一身本事——写一次，之后 Claude 随手就能调，还能捆模板和脚本。

02 命门：渐进式披露，省上下文的秘密

这是整篇最该吃透的一节。Skill 凭什么能塞一大堆，却几乎不占你的上下文？ 答案就一个词：渐进式披露（progressive disclosure，意思是「按需逐步展开」，不相关时不加载全文）。

先说为什么这事关键。前面 19 上下文管理 讲过，Claude 的「工作台」就那么大，塞进去的每一个字都在花预算、都在挤占它思考的余地。如果每个 Skill 的全文一开会话就全堆进去，装十个 Skill 你的工作台就废了一半。

类比：餐厅的菜单和后厨。 你坐下来，服务员先递给你一张菜单——每道菜就一行菜名加一句简介，你扫一眼就知道有什么。你点了「宫保鸡丁」，后厨那张写满步骤的详细菜谱才被翻出来照着做。没点的菜，菜谱一直压在抽屉里，不占你桌上一寸地方。Skill 就这么运作：

• 平时：Claude 只看得到每个 Skill 的那一句 description（菜单上的菜名）。
• 相关时：你问的事对上了某个 description，那个 Skill 的完整正文才被加载进来（翻出对应菜谱）。

官方把这条规则讲得很直白：

在常规会话中，skill 描述被加载到上下文中，以便 Claude 知道什么可用，但完整 skill 内容仅在调用时加载。

所以你可以放心大胆地往 Skill 正文里写长篇参考资料、详细检查清单——用到之前，它几乎不花成本。这正是官方建议「把内容做成 Skill 而不是全塞进 CLAUDE.md」的原因：CLAUDE.md 是一开会话就全程驻留的，Skill 正文是用到才来。

这张图把「渐进式披露」两阶段画清楚了：左边是会话常态——三个 Skill 在上下文里各只占一句 description，工作台还很空；右边是某个 description 被你的提问命中后，只有那一个 Skill 的完整正文被加载进来，其余两个仍然只是一行。一眼看出「省」在哪。

不过有个配套的代价你得知道，否则会踩坑：一旦 Skill 被加载，它的正文会在整场会话里一直驻留——Claude 不会在后续每一轮重新读它。官方原话：

当你或 Claude 调用一个 skill 时，呈现的 SKILL.md 内容作为单个消息进入对话，并在会话的其余部分保持在那里。

这意味着两件事：第一，Skill 正文里每一行都是一次重复的 token 成本，别灌水，官方建议把 SKILL.md 控制在 500 行以内，长参考拆到单独文件按需加载；第二，写「常驻说明」而不是「一次性步骤」——因为它全程都在，要写成「整个任务都适用的指导」，而不是「第一步做 X」这种用完就过期的。

这里有个相关的小跟头我自己实打实栽过：写了个 Skill，前几轮还照着做，聊到后面死活感觉「它好像把这套说明忘了」，我第一反应是加载失败、还反复重启 Claude 想让它重新读一遍。翻了官方才明白——内容通常还在，是模型转头去选别的工具了。解法是把 description 和说明写更明确、让它继续偏向这个 Skill，而不是怀疑加载机制。

💡 一句话总结：渐进式披露 = 平时只露一句 description、用到才展开全文，所以装再多 Skill 也不撑上下文；但展开后会全程驻留，正文务必精简、写成常驻说明。

03 Skill、slash 命令、Subagent：到底差在哪

开头那场争论的核心，就是这一节。很多人把这三个搅在一起，其实定位完全不同。这里我先把最容易混的点掰开，完整的「该选哪个」决策表留到第 30 篇，这节只做到「分得清」。

先把三个名词对齐一下：

• slash 命令：你输入 /xxx 主动触发的一段操作。
• Skill：一身打包好的本事，你能主动喊、Claude 也能按需自动调。
• Subagent（子代理）：一个独立上下文的子助手，主对话把任务委派给它，它在自己的小世界里干完再把结果带回来（前面 23 子代理 详谈过）。

这里有个关键认知，专门破开头那个误解：slash 命令和 Skill 不是对立关系，slash 命令其实是 Skill 的一种调用方式。官方把自定义命令并进了 Skills——你建一个 commit Skill，它天然就能用 /commit 调。真正的区别不在「叫什么」，而在谁能发起、占不占上下文：

看懂这张表，开头的争论就化解了：那种「slash 命令」的理解是 Skill 的手动触发档；它没意识到同一个 Skill 还能让 Claude 自动触发。

那「自动触发」会不会乱套？不会，因为你能精确控制谁有权调用它。官方给了两个 frontmatter 开关：

• disable-model-invocation: true：只有你能调。用于有副作用、你想亲手掐时机的活儿——比如 /deploy、/commit、发 Slack 消息。你肯定不希望 Claude「看你代码像是写好了」就自作主张部署了。
• user-invocable: false：只有 Claude 能调。用于那种「背景知识」型的 Skill——比如一个解释老系统怎么跑的 legacy-system-context，Claude 该用时知道就行，但 /legacy-system-context 对你来说不是个有意义的命令。

所以「乱套」是可控的：怕它乱动手的，加 disable-model-invocation: true 锁成纯手动；这正是上面那个误解里该用的招。

💡 一句话总结：slash 命令是 Skill 的手动触发档、Subagent 是独立上下文的子助手——三者定位不同；怕 Skill 自动乱动，就用 disable-model-invocation: true 锁成只能你喊。

04 Skill 从哪来：内置、插件带、自己写

知道是什么了，那 Skill 从哪儿冒出来的？三个来源，由近到远。

来源一：内置（捆绑）Skill——开箱就有，每次会话都在。 Claude Code 自带一批捆绑 Skill，不用你装。官方列的有 /code-review（审代码）、/debug（调试）、/batch（批处理）、/loop（循环跑）、/claude-api（Claude API 参考）等。还有三个配套干「跑起来验证」的：/run（启动并驱动你的应用看改动有没有效）、/verify（构建并运行确认改动按预期工作）、/run-skill-generator（教前两个怎么构建启动你的项目）。这些你打个 / 就能在菜单里看到。

注意：捆绑 Skill 和 /help、/compact 那种内置命令不是一回事。内置命令直接执行固定逻辑；捆绑 Skill 是基于提示的——给 Claude 一份详细说明，让它用自己的工具去编排完成。调用方式一样，都是打 / 加名字。

来源二：插件附带——装个插件，Skill 跟着一起来。 前面 24 插件 讲过，插件能打包一堆扩展。Skill 就是插件能带的东西之一：插件里建个 skills/ 目录，启用插件的地方这些 Skill 就可用了。插件 Skill 用 插件名:skill名 的命名空间（比如 /my-plugin:review），所以它永远不会跟你自己的 Skill 撞名。

来源三：自己写——这才是 Skill 的主场。 你把反复粘贴的那套说明、检查清单、多步流程写成一个 SKILL.md，它就成了你专属的本事。官方给的判断标准很实用：

当你不断将相同的说明、检查清单或多步骤程序粘贴到聊天中时，或者当 CLAUDE.md 的一部分已经演变成程序而不是事实时，创建一个 skill。

这句话点破了 Skill 和 CLAUDE.md 的分工，跟上一篇正好接上：CLAUDE.md 装「事实」（这项目用什么技术栈、有什么约定），Skill 装「程序」（这件事分几步怎么做）。你发现自己在 CLAUDE.md 里写起了「第一步……第二步……」，那部分就该挪进 Skill。

下面这张表帮你对号入座：

💡 一句话总结：Skill 三个来源——内置捆绑（开箱即用）、插件附带（装啥带啥）、自己写（主场）；判断要不要自己写就一条：你是不是在反复粘同一套步骤。

05 放哪决定谁能用 + 怎么触发、怎么查

最后这节落到最实操的三件事：自己写的 Skill 放哪、它怎么被触发、怎么看现在手上有哪些。

放在哪个目录，决定谁能用它

这是官方的位置表，放错地方 = 该用的人用不上，照抄就行：

逻辑很直观：只有你自己用、跨项目通用的（比如你个人的 commit 习惯），放个人级 ~/.claude/skills/；这个项目专属、想让团队都用的（比如本项目的部署流程），放项目级 .claude/skills/ 并提交到版本库。

同名时谁赢？官方规定的优先级是 企业 > 个人 > 项目（插件因为带命名空间，不参与抢名）。还有一条安全提示值得划重点：项目级 Skill 提交进仓库后，别人拉下来要先过「工作区信任」对话框——因为 Skill 里的 allowed-tools 能给自己授权一批工具，信任仓库前先看看项目里的 Skill 写了啥，别被一个来路不明的 Skill 偷偷开了权限。

怎么触发：靠 description 自动匹配，不用背命令

这是 Skill 最舒服的一点：你不用记 /什么什么，正常说人话就行。Claude 会拿你说的话去比对每个 Skill 的 description，对上了就自动把那个 Skill 调出来。

拿第 01 节那个 summarize-changes Skill 举例，它 description 里写了「当用户问改了啥……时使用」，所以两种方式都能触发它：

我改了什么？

/summarize-changes

第一种是让 Claude 自动调（你压根没提 Skill 名，它自己匹配上了）；第二种是直接喊名字。日常更推荐第一种——说需求就行，触发交给它。这也反过来告诉你写 Skill 时 description 有多重要：description 里得包含「用户会自然说出口的关键词」，它才匹配得准。官方排查「Skill 没触发」的第一条就是查这个：

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

怎么查：当前到底有哪些 Skill 可用

装了一堆、内置一堆，怎么知道现在手上有啥？最直接一句话问它：

现在有哪些 Skill 可用？

它会把当前所有可用的 Skill 列给你。这也是官方排查 Skill 问题的标准动作之一——先确认它到底在不在列表里，再谈触发。另外打 / 调出命令菜单也能看到能手动调的那些，/doctor 则能帮你查「Skill 描述是不是因为装太多被截断了」（装的 Skill 多到一定程度，描述会被压缩以省字符预算，可能把匹配用的关键词削掉）。

💡 一句话总结：个人级放 ~/.claude/skills/、项目级放 .claude/skills/，同名时优先级：企业 > 个人 > 项目；触发靠 description 自动匹配、不用背命令；一句 What skills are available? 就能查当前有哪些。

06 动手：5 分钟看清「自动触发」和「渐进式披露」

光看不练记不住。下面这套最小操作，不写任何复杂脚本，就让你亲眼看到两件事：Skill 怎么被一句话自动触发、它平时怎么只占一行。全程在一个空目录就能跑。

第一步：建个人级 Skill 目录（Mac / Linux）

mkdir -p ~/.claude/skills/explain-self

Windows 用户：在 C:\Users\你的用户名\.claude\skills\ 下新建 explain-self 文件夹即可。

预期：~/.claude/skills/ 下多了个 explain-self 空目录。

第二步：写一个最简单的 SKILL.md

用你顺手的编辑器，把下面内容存到 ~/.claude/skills/explain-self/SKILL.md：

---
description: 用大白话解释一段代码或一个报错。当用户说「这段代码啥意思」「这个报错咋回事」「帮我读读这个」时使用。
---

## 说明

把用户给的代码或报错，用初学者能懂的大白话讲清楚：
1. 这东西整体在干啥（一句话）
2. 逐行 / 逐段拆开说
3. 如果是报错，指出最可能的原因和怎么改

不要堆术语，能用生活类比就用。

注意它的 description 特意写了「这段代码啥意思」「这个报错咋回事」这些你真会说出口的话——这就是自动触发的钩子。

预期：explain-self 目录里有了一个 SKILL.md。

第三步：启动 Claude 并确认它认得这个 Skill

claude

进去后敲：

现在有哪些 Skill 可用？

预期：返回的可用 Skill 列表里，能看到 explain-self，旁边是你写的那句 description。看到它在列表里 = Skill 已被正确加载。（这一步还顺带印证了渐进式披露：此刻上下文里只有它这一句 description，正文那几行说明还没被加载进来。）

第四步：不喊名字，用「人话」触发它

故意不打 /explain-self，而是说一句对得上 description 的话：

这段代码啥意思：print(sum([1,2,3]) / len([1,2,3]))

预期：Claude 会自动调用 explain-self 这个 Skill（你能在它的回应里看到 Skill 被触发的提示），然后按你写的三步——先一句话说整体（算这三个数的平均值）、再逐段拆、术语少——来解释。它没等你喊命令就调出了对应本事，这就是自动触发。

第五步：对比直接喊名字

再试一次手动档，直接打：

/explain-self 这个报错咋回事：ZeroDivisionError: division by zero

预期：同样触发这个 Skill，效果和第四步一致——区别只在于这次是你主动喊的。两条路通向同一身本事，正好印证第 03 节那张表里「你 + Claude 都能发起」。

跑通这五步，你就把 Skill 最核心的两件事——「描述匹配自动触发」和「平时只占一句 description」——亲手验证了一遍。

💡 一句话总结：建 ~/.claude/skills/explain-self/SKILL.md、用 What skills are available? 确认加载、再用「人话」和 /名字 各触发一次——亲眼看到自动触发和手动触发通向同一身本事，比记十条文档都实在。

07 小结

这一篇把 Agent Skills 从「是什么」到「怎么用」捋了一遍——它让 Claude 不再是张白纸，而是带着一身能按需调出的专项本事上岗。

核心要点串起来回顾：

你现在应该能： 说清楚一个 Skill 由什么组成、它凭「渐进式披露」省上下文的原理；分得清 Skill、slash 命令、Subagent 各自的定位；知道 Skill 的三个来源、放在哪个目录决定谁能用；并且明白触发它靠的是 description 自动匹配、不用背命令。这套「按需调出专项能力」的本事，是你把 Claude 从「通用助手」调教成「懂你这套活儿的专家」的关键一步。

下一篇 27「Skills 使用实例」——这一篇全是概念和机制，下一篇真刀真枪：带你从零装一个真正有用的 Skill，亲手触发它、看着它把活儿干完。想想看，你日常哪件事是反复跟 Claude 叮嘱同一套流程的？下一篇我们就拿这类活儿开刀，把它封成一个一句话就能调的本事。

27 · Skills 使用实例：装一个、喊一声、看它干活

比如要赶一份代码库结构图，给老板汇报用。换平时，咱们得先在脑子里理节点、画 Mermaid 草图、调配色、导出 PNG，一套下来稳稳半天。这时候只要对着 Claude Code 敲一句「帮我画一张这个项目的架构图」——Claude 就自己搞定了。

它不问你任何参数，自己加载一个叫 baoyu-diagram 的 skill，按里面写死的暗色设计系统排好版、生成 SVG、转成 @2x PNG，前后不到五分钟，图就躺在 docs/assets/ 里了。

这一刻你才真正理解 skill 的价值：它不是「让 Claude 更聪明」，而是「让 Claude 把某件事，每次都按同一套靠谱流程做出来」。半天压成五分钟，差的就是这套写好的流程。

上一篇你已经知道 skill 是什么了。这一篇只干一件事：带你把这个「半天变五分钟」的体验，亲手跑一遍。

看完这一篇，你会拿到：

• 一句话查出当前会话里到底有哪些 skill 可用，不再瞎猜
• 看懂一个真实 SKILL.md 长什么样，知道 description 那行凭啥决定它触不触发
• 用「自然语言触发」和「/ 直呼其名」两种方式跑完一个 skill 的完整流程，每步都有预期输出
• skill 喊不动时的三步排查表（说法太含糊 / description 不匹配 / 压根没启用）
• 把一个 skill 提交进项目、让全队照同一套流程干活的具体做法

01 先别急着用：看看手里到底有哪些 skill

动手第一步不是「用 skill」，是搞清楚你现在有哪些 skill 能用。

新手最容易犯的错，是凭印象瞎喊——「我记得有个画图的 skill 吧？」然后对着 Claude 喊半天没反应，以为是 skill 坏了，其实压根没装。先查清家底，比啥都强。

类比：照菜谱做菜前，先翻翻你这本菜谱里到底收了哪几道菜。 你不会对着厨房空想「今天做个红烧肉吧」，得先确认菜谱里有「红烧肉」这一页、食材步骤都齐。skill 就是 Claude 的菜谱，每个 SKILL.md 是一道写好的菜——先翻目录，确认这道菜在册，再开火。

查看的办法特别简单，在 Claude Code 会话里用大白话问它就行：

有哪些可用的 skill？

官方文档里用的是英文问法 What skills are available?，中文一样认。预期：Claude 会列出当前会话能用的 skill，每个带名字和一句话简介。在这个教程项目里跑，列表里就有那个画图的：

baoyu-diagram — 生成专业的暗色主题 SVG 图（架构图 / 流程图 / 时序图 / 思维导图……）

💡 一句话总结：用 skill 之前，先在会话里问一句「有哪些可用的 skill？」确认你要的那道菜在册，再开火，别对着不存在的 skill 瞎喊。

还有两个查家底的小动作，顺手记一下：

/skills 菜单——在输入框敲 /skills 回车，会弹出一个可视化菜单，把所有 skill 列出来，还能在这里切换每个 skill 的启用状态（高亮后按 Space 循环切换，Enter 保存）。比纯文字列表更直观。

/doctor 体检——这条偏进阶：如果你装了一大堆 skill，Claude 可能因为「描述预算」装不下、把一部分 skill 的描述截断了，导致它「看不全」。/doctor 能告诉你预算有没有溢出、哪些 skill 受影响。新手一般用不到，但哪天发现某个 skill 莫名其妙不触发了，先跑 /doctor 看一眼。

02 拆开一个真 skill：SKILL.md 长什么样

光知道「有这个 skill」还不够，得看懂它内部长什么样，你才明白它凭啥被触发、能干啥。

正好，这个教程项目里就躺着一个真 skill。咱们不看官方文档里的玩具示例，直接扒这个真实在用、天天靠它出图的 baoyu-diagram。

它在项目里的位置是：

.claude/skills/baoyu-diagram/
├── SKILL.md              # 主说明（必需）
├── references/           # 各类图的详细排版规范（按需加载）
│   ├── architecture.md
│   ├── flowchart.md
│   └── sequence.md
└── scripts/
    └── main.ts           # SVG 转 PNG 的脚本（被执行，不进上下文）

看出门道没？一个 skill 就是一个文件夹，SKILL.md 是入口，旁边可以挂参考文档和脚本。SKILL.md 必需，其余都是可选的「料」——参考文档让主说明保持精简（用到哪类图才加载哪个），脚本是给 Claude 跑的工具。

打开它的 SKILL.md，最上面那块 --- 围起来的就是命门，叫 frontmatter（前置元数据，写在文件最顶端的配置）：

---
name: baoyu-diagram
description: Create professional, dark-themed SVG diagrams of any type — architecture diagrams, flowcharts, sequence diagrams... Also trigger when the user says "画个图" "画一个架构图" "diagram" "flowchart"...
version: 1.117.3
---

--- 下面那一大段 markdown，才是 Claude 真正要照着干的「菜谱正文」（设计系统、配色、排版规则、转 PNG 的命令）。

这里有个上一篇讲过、但你现在该亲眼对上号的关键点：那行 description，是 Claude 判断「这次该不该用这个 skill」的核心依据（frontmatter 里还有个可选的 when_to_use 字段可以补充触发条件，两者合计截断为 1536 字符）。

你注意到没——这个 description 里明晃晃塞了一堆中文触发词：「画个图」「画一个架构图」，还有英文的 diagram、flowchart。这不是随便写的，是作者故意把用户可能说的话都铺进去，好让 Claude 一听到这些词就反应过来「该我上了」。

类比：菜谱页眉那行「适合：家宴、待客、下饭」。 你翻菜谱找「待客菜」时，一眼扫到页眉这行字，就知道这道菜对路。description 就是 skill 的页眉标签——Claude 拿你的话去比对每个 skill 的 description，谁的标签最对得上，就翻开谁那一页。

所以记住这条因果链，后面排查全靠它：

你说的话 → Claude 拿去比对各个 skill 的 description → 匹配上了 → 加载那个 SKILL.md 的正文 → 照里面的步骤干活。

description 写得越贴近你的真实说法，触发越准。这也是为什么下一节排查「喊不动」，第一个要查的就是它。

这张图把「一句话怎么变成 skill 干活」拆成四步：你说话 → Claude 拿去和每个 skill 的 description 比对 → 命中后加载对应 SKILL.md 正文 → 照里面写死的步骤产出结果。看懂这条链，你就知道排查该从哪一环下手。

💡 一句话总结：一个 skill 就是一个带 SKILL.md 的文件夹，最顶上的 description 是触发命门——Claude 拿你的话去比对它，对上了才翻开这页菜谱。

03 跑通第一个：自然语言喊一声，看它出活

家底清了、结构懂了，开整。这一节用 baoyu-diagram 走一遍最常见的用法：用大白话喊，让 Claude 自己判断该不该上。

这是 skill 最爽的地方——你不用记任何命令，该用哪个 skill 是 Claude 自己挑的。

第一步，在教程项目根目录把 Claude Code 起起来：

claude

预期：进入会话，底部出现输入框。

第二步，直接用大白话提需求——注意，这里一个字都没提 baoyu-diagram 这个名字：

帮我画一张图，说明 Claude 的「想→做→看」代理循环

预期：Claude 一听「画一张图」，就去比对各 skill 的 description，命中 baoyu-diagram 那行的 diagram/「画个图」，于是自动加载它，然后照菜谱正文干活：读对应的参考文档（流程图就读 references/flowchart.md）、按暗色设计系统排版、生成一个 .svg、再跑脚本转成 @2x.png。

干完它会告诉你产出在哪，大致长这样：

已生成图表：
  docs/claude-code/assets/27-agent-loop.svg
  docs/claude-code/assets/27-agent-loop@2x.png

看到这两个文件 = skill 触发成功、活也干完了。 整个过程你没碰任何参数，全靠一句大白话。

这就是 skill 和「普通对话」最大的区别。摆一张对比，差距一目了然：

说白了，skill 把「每次都要交代一遍的繁琐流程」一次性写死了。你只管说要什么，「怎么做得专业」是菜谱的事。

不想等它猜？直接点名

有时候你很确定就要用某个 skill，懒得让它猜，直接 / 点名最快：

/baoyu-diagram 画一张用户登录的时序图

预期：跳过「匹配 description」这一步，直接加载 baoyu-diagram 并执行，/ 后面那串话作为参数传进去（这里就是告诉它画什么图）。

两种方式啥时候用哪个？一般来说：

• 探索、不确定该用啥 → 用大白话，让 Claude 自己挑（说不定它挑的比你想的还准）。
• 明确知道要哪个、要它立刻执行 → / 点名，尤其是那种「有副作用、不能乱触发」的 skill（比如部署、提交），官方就建议这类干脆只让你手动 / 调，别让 Claude 自作主张。

💡 一句话总结：跑 skill 两条路——大白话让 Claude 自己挑、/名字 直接点名；前者适合探索，后者适合「我就要它、立刻干」。

04 喊了没反应？三步排查，对号入座

真上手你迟早会遇到：喊了一句，Claude 没用 skill，自己吭哧吭哧用普通方式干了。先别慌，也别觉得 skill 坏了——九成是下面三种情况之一。官方的故障排查就这几条，下面按「最常见」排了序。

类比：照菜谱做菜，菜没成，无非三种原因——你说的菜名跟菜谱页眉对不上、菜谱根本没收进这本书、或者你话说得太含糊厨师没听懂。 一条条排，总能揪出是哪环。

第一步：先怀疑「你说得太含糊」（最常见）。

很多时候不是 skill 的错，是你那句话离 description 太远。比如 baoyu-diagram 的 description 里写的是「画图 / diagram / 架构图」，你要是说「给我整个可视化的东西」，Claude 可能就没把它跟「画图」对上。

解法：把话往 description 上靠，换个更直白的说法重说一遍：

帮我画一张架构图

带上「画」「图」这种明确动词，命中率立刻上去。这是最快的一招，先试它。

第二步：确认「这个 skill 到底在不在册」。

回到第 01 节那招，问一句：

有哪些可用的 skill？

预期：如果列表里根本没有你要的那个 skill，那问题就清楚了——它压根没装，或者没被加载（比如项目级 skill 还没通过信任、或你启动目录不对）。这种就别在「怎么触发」上耗了，先把它装上 / 加载上（第 05 节讲项目级怎么让它生效）。

第三步：确认了在册、还是不触发——直接 / 点名兜底。

如果第二步确认了它在列表里、第一步换了说法也还是不灵，别跟它较劲，直接 /名字 手动调起来：

/baoyu-diagram 画一张架构图

只要它在册，/ 点名一定能调起来（/ 是「我点名要你」，绕过了「Claude 自己判断」那一环）。这一步既是兜底，也能帮你定位问题：/ 调得起来 = skill 本身没毛病，纯粹是自动触发没匹配上，那回头优化 description 就行。

把这三步整理成一张排查表，喊不动时照着走：

⚠️ 反过来也有「触发太勤」的烦恼——某个 skill 动不动就自己蹦出来。官方的解法是：把它的 description 写得更具体（别用太宽的词），或者给它加 disable-model-invocation: true，直接禁止 Claude 自动触发、只许你手动 / 调。这个改法属于「造 / 改 skill」，下一篇会展开。

💡 一句话总结：喊不动按三步排——先怀疑说法太含糊（换直白说法）、再查在不在册、最后 / 点名兜底；这三招覆盖你会遇到的几乎所有「不触发」。

05 让全队都能用：把 skill 提交进项目

到这儿你已经会用 skill 了。但有个问题：上面装在 ~/.claude/skills/ 里的 skill，只有你自己电脑上有，同事拉下代码是没有的。

想让整个团队都照同一套流程干活，得换个地方放——项目级 skill。

类比：这道菜的菜谱，别只贴在你自家厨房，印进随项目一起发的「公司菜谱册」里。 谁拿到这本册子（clone 了仓库），翻开就能照着做同一道菜。个人 skill 是你私房菜谱，项目级 skill 是跟代码一起发出去、人手一份的公共菜谱。

差别就一个：放哪、要不要提交进 Git。看这张对照：

具体怎么落地，就三步：

第一步：把 skill 放进项目的 .claude/skills/（而不是主目录）：

你的项目/
└── .claude/
    └── skills/
        └── team-commit/
            └── SKILL.md

第二步：提交进版本控制。 像提交普通代码一样：

git add .claude/skills/
git commit -m "feat: 加一个团队统一的 commit skill"

第三步：同事拉下来就能用——这是项目级最香的地方：别人 clone 仓库、git pull 之后，这个 skill 自动就在他们的会话里了，不用各自手动装。整个团队从此「画图都是同一套风格」「提交都走同一套检查」。

这里有个官方明确的安全细节，务必记住：别人项目里检入的 skill，首次打开该项目时会弹一个「工作区信任」对话框让你确认。为啥要这一道？因为 skill 可以给自己授予工具权限（比如自动跑命令），信任一个仓库前，先扫一眼它的 skill 里写了啥，别闭眼点同意。官方原话：

在信任存储库之前查看项目 skills，因为 skill 可以授予自己广泛的工具访问权限。

拉外部项目时就该按这条做。比如 clone 一个开源仓库，信任前翻一眼它 .claude/skills/ 下的 SKILL.md，有可能发现里面某个 skill 在 allowed-tools 里放开了一堆 Bash 权限——倒不一定是恶意，但宁可看清楚再点信任。这一眼，值得花。

💡 一句话总结：想让全队用同一个 skill，放进项目的 .claude/skills/ 并提交进 Git，别人 clone 就自动有；但信任别人的项目 skill 前，先扫一眼它都申请了啥权限。

06 动手：从零装一个个人 skill，亲手喊起来

前面用的都是现成的 baoyu-diagram。这一节带你从零造一个最简单的 skill 并触发它——不为造多复杂，就为亲眼看到「写文件 → 它出现在列表 → 一句话喊起来」这条完整链路。全程不依赖任何复杂环境。

我们做一个超简单的：让 Claude 用「咖啡馆聊天风」帮你解释一段代码。

第一步：建 skill 目录（个人级，放主目录，你所有项目都能用）。Mac / Linux：

mkdir -p ~/.claude/skills/explain-casual

Windows（PowerShell）：

mkdir $HOME\.claude\skills\explain-casual

预期：~/.claude/skills/ 下多了个 explain-casual 文件夹。

第二步：写 SKILL.md。 用你顺手的编辑器，在 ~/.claude/skills/explain-casual/SKILL.md 里贴入：

---
description: 用轻松的咖啡馆聊天风格解释一段代码。当用户说「用大白话讲讲这段代码」「这段代码在干嘛」「讲讲这个函数」时使用。
---

## 任务

用最口语、最轻松的方式解释用户给的代码，像跟朋友在咖啡馆闲聊，不要学术腔。要求：

1. 先一句话说清这段代码整体在干嘛。
2. 再挑出关键的几行，逐个用大白话讲。
3. 最后提一句：有没有看着别扭、可能埋坑的地方。

划重点：那行 description 里故意塞满了用户可能说的话——「用大白话讲讲这段代码」「这段代码在干嘛」「讲讲这个函数」。这就是第 02 节说的「页眉标签」，塞得越贴近真实说法，触发越准。

第三步：确认它进了列表。 这里有个官方细节要注意：会话启动时不存在的「顶级 skill 目录」需要重启才能被监视到。咱们刚新建了 explain-casual 这个目录，所以保险起见新开一个会话：

claude

进去后问：

有哪些可用的 skill？

预期：列表里出现了 explain-casual，带着你写的那句中文描述。看到它 = skill 装好且被加载了。

第四步：用大白话喊它（别提名字）。 在会话里贴一段代码让它讲，比如：

用大白话讲讲这段代码：
def average(numbers):
    return sum(numbers) / len(numbers)

预期：Claude 把你这句「用大白话讲讲这段代码」跟 explain-casual 的 description 对上，自动加载这个 skill，然后照里面三步走：先一句话说它算平均值；再讲 sum(numbers) / len(numbers) 这行；最后提醒你传空列表会除以 0 崩掉（这正是第 1 步任务里「埋坑的地方」那条在起作用）。整个口吻是轻松的咖啡馆风，不是干巴巴的文档腔。

第五步：对比一下「点名调用」。 再试 / 直呼：

/explain-casual def average(numbers): return sum(numbers) / len(numbers)

预期：同样的效果，但这次是你点名触发的——跳过了「Claude 自己判断」那一环，/ 后面的代码作为参数传进去。

跑通这五步，你就把 skill 的完整生命周期亲手摸了一遍：写 SKILL.md → 它出现在可用列表 → 大白话能喊起来 → / 也能点名。以后用任何别人的 skill，本质都是这套机制，无非菜谱内容更复杂。

⚠️ 如果第三步列表里没看到 explain-casual：十有八九是没重启会话（新建顶级目录得重启才被监视到），退出 claude 重进一次。要是重进还没有，检查文件路径和文件名是不是一字不差地叫 SKILL.md（全大写）。

💡 一句话总结：亲手造个最简单的 skill 跑一遍——建目录、写 SKILL.md（description 塞满真实说法）、重启确认进列表、大白话喊起来；这条链路走通，别人的 skill 你也就全会用了。

07 小结

这一篇全程在动手，把「会用别人的 skill」从概念落成了肌肉记忆。把核心动作串起来回顾：

你现在应该能： 在任何会话里查清手里有哪些 skill、看懂一个真实 SKILL.md 的结构和它凭啥触发、用两种方式把一个 skill 跑起来、喊不动时三步定位问题，还能把一个 skill 提交进项目让团队共享。这套「会用别人的 skill」的能力，是你之后白嫖整个 skill 生态的入场券——社区里大量现成 skill，装上、喊一声，就是别人写好的专业流程为你所用。

开头那张「半天变五分钟」的架构图，就是这么来的。你现在也有了同一把钥匙。

下一篇 28「skill-creator：造你自己的 skill」——会用别人的菜谱了，下一步自然是自己写菜谱。你有没有哪段流程，是每次都要给 Claude 重复交代一长串？（这种流程往往不止一个。）下一篇就教你用官方的 skill-creator，把这种「反复粘贴的繁琐流程」一次性固化成你专属的 skill，从「用菜谱的人」变成「写菜谱的人」。

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

都说 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 的价值不是帮你打字（打字它没快多少），而是逼你把这几件隐形的事一件不落地做对。

💡 一句话总结：手写 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 路径：

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

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

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

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

/skill-creator

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

我想做一个 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 之后那几步当成必修课，尤其是「跑测试看触发」和「照反馈改」这个循环。

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

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 把描述改成下面这样，再喊一句「帮我提交」，它立马就接住了。

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

提炼成一句口诀：好的 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 会问你，但你得自己心里有数。

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

怎么选？就一个判断标准：这 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 后，敲：

/skills

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

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

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

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

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

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

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

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

## 当前改动

!`git diff HEAD`

## 你的任务

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

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

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

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

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

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

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

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

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

我改了啥？

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

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

/summarize-changes

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

怎么判断成败：

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

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

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

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

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

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

帮我把这个 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.md 容易翻在触发上、用 skill-creator 走完「起脚手架 → 写对 description → 测触发 → 打包」整条流程，亲手写出一句「叫得动」的 description，把 skill 放进对的目录，并验证它真的被触发了。这套「造得对、叫得动」的能力，是你从『用别人的 skill』升级到『打造自己的工具链』的分水岭。

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

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

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