Skills：怎样给智能体装上一项现成的能力

有一类请求您总在重复：看看改动，检查这几个文件，按这个格式整理，那边别碰。每次都要重新解释一遍这套流程，而且说法多少有点不一样。

结果也随着措辞变来变去。今天效果很好，明天您忘了一半条件，智能体也就老老实实照它听到的做了。

解决办法不是让智能体记性更好，而是给它一个装着说明的文件夹。Skill 就是写好一次的流程，Claude Code 既可以自动接入，也可以由您手动调用。下面看看这个文件夹放在哪里，怎么确认 skill 真的生效了，以及第一次运行前该检查什么。

什么是 skill

在拆解文件和字段之前，先找找感觉。

想象一位木匠。他把常用的工作顺序写下来一次，准备好备忘、模板和机床程序。现在只需一句话："把台面清空，磨好钻头，接下来是猫咪椅子 - 运行数控模板"。启动，然后就交给它了。

写下来的流程把整个工作串在一起：

• 按您的规矩收拾。 清理工作台，摆好工具 - 每次都一样，正是您习惯的那种。
• 守住写下的边界。 锯还在转 - 不碰。安全的部分立刻做，不用多问。
• 需要时才去查备忘。 该磨钻头了 - 打开磨钻头的说明。不会提前把它记在脑子里，用到时再取。
• 为不同的活儿备好模板。 从做桌子换成做椅子 - 直接取现成的准备方案。
• 一条命令启动复杂的部分。 重复切割的程序已经放在那儿了。只需说一句"找到猫咪椅子模板，送去数控机床" - 机器会守住间隙和操作顺序。

Skill 的道理一样。它不是智能体手里的又一件工具，而是打包好的流程。主说明保留顺序和边界，参考文件按需给出细节，模板留着可以直接用的底稿，脚本运行那些重复的机械操作。描述一次，之后直接调用就行。

Skill 这个格式本身不隔离任何东西。说明可以把工作范围限定在样式上，但 CSS 和逻辑之间没有技术上的墙。一个好的 skill 会明确说清楚工作范围；运行之后您要看改动了哪些文件，检查页面的行为。"能用"和"好看"是两个不同的层面，保证来自检查，不来自格式本身。

Skill 放在哪里

这里没有任何云端魔法。Skill 就是磁盘上的一个文件夹，就在您自己的项目里：

.claude/skills/web-design/SKILL.md

路径按段拆开来看：专用文件夹 .claude，里面是 skills，再里面是 skill 自己的文件夹（名字您自己定），里面才是文件 SKILL.md。就是个普通文本文件，用什么编辑器都能打开。

对于项目里或主目录下的 skill，只要文件本身没有另设名字（后面会讲到），目录名就成了斜杠命令的名字。所以起名字的时候，要想好它在聊天里显示出来是什么样子。

再纠正一个最常见的误解：skill 不是一个文件，而是一个文件夹。SKILL.md 旁边可以放任何东西。

.claude/
└── skills/
    └── web-design/
        ├── SKILL.md      # 主文件：描述和说明
        ├── palettes.md   # 参考文件，智能体需要时会打开
        └── scripts/
            └── check.py  # 可以运行的脚本

智能体自动选择的时候，手上有的是 skill 的名字和简短描述，不是整个正文。SKILL.md 在 skill 被调用时才加载，旁边的参考文件按需加载。所以再长的备忘也不会提前占用上下文。

日常本地工作里，有三个来源的 skill 值得关注：

~ 符号代表用户的主文件夹。命令里原样保留就好；如果要手动打开这个文件夹，就去自己的主目录。

前两个位置的区别很简单，值得一开始就弄清楚。

把文件夹放进项目 - skill 只在这个项目里起作用。打开另一个项目，那里就没有它。

主目录下的 skill 在所有项目里都能用。对通用流程来说很方便，但也可能在您没想到的地方启动。通用的放主目录，只跟某个项目有关的留在项目里。

如果 Claude Code 是用单独的学习专用配置 ~/.claude-codegym/ 启动的，个人 skill 就放在这个配置的 skills/ 文件夹里。项目路径 .claude/skills/ 不会随配置变化。

Description 决定 skill 何时触发

典型的情况是这样：文件夹放好了，文件也在，可智能体的表现和以前一模一样。什么都没坏 - 只是它没意识到这个 skill 适合当前的任务。

看看智能体在做选择的那一刻手上有什么。它还没读过 skill 本身的正文：加载的只有名字和描述的列表。也就是说，决定是靠描述做出的，别无其他依据。

我们从头到尾搭一个最简单的项目 skill。它叫 web-design - 文件夹就是这个名字，命令 /web-design 也是从这里来的。这里我们不在文件里另写名字，文件夹已经定好了：

.claude/skills/web-design/SKILL.md

里面写的就是这些，不需要更多：

---
description: 整理网页界面 - 现代化的 CSS、平滑过渡、统一的配色。
  当有人要求做得好看或有风格时使用。
---

# 网页设计

使用柔和的阴影、平滑的过渡和讲究的排版。
配色保持统一，动画用在悬停和元素出现时。

上面两行三短横线之间是元数据块，下面是普通的说明文字。没有必填字段，但 description 值得每次都写：没有它，智能体只能靠正文第一段猜 skill 是干什么的，那就是碰运气。

好的描述回答两个问题：skill 做什么，什么时候该用它。而且要用您写请求时真正会用到的那些词。

# 不会触发：不知道什么时候该用
description: 帮忙做样式

# 会触发：既说了做什么，也说了什么时候用
description: 整理界面 - CSS、排版、配色。
  当有人要求做得好看、有风格，或者要修一下布局时使用。

描述决定了 skill 什么时候会自己冒出来。但这不是唯一的入口：skill 有名字，您可以按名字手动调用它。输入 /web-design，描述就完全不起作用了，文件被直接读取并执行。

现成的 skill 里常见一个 name 字段。对项目和主目录下的 skill 来说，它决定了 / 菜单里显示的命令：文件夹 deploy-staging 里写了 name: deploy，就要用 /deploy 来调用。目录名同时也照样能用。在插件里，name 可以设定插件名之后那一段命令。

启动路径因此有两条，之后的部分是一样的。

左边这条是自动的：请求匹配了描述，智能体拿起了这个 skill。右边是手动的：输入了 /web-design，skill 就启动了，跟描述完全没关系。

Skill 会出现在和内置命令同一个 / 菜单里。文件 .claude/commands/deploy.md 和 skill .claude/skills/deploy/SKILL.md 会创建同一个命令 /deploy；两者都在的话，skill 胜出。

安装并检查

文件夹放好了。怎么确认智能体真的看到了它，而不只是磁盘上多了个文件？

/skills

这条命令打开 skill 列表，显示它们的来源。输入几个字母，列表就会过滤。如果找到了自己文件夹的名字，状态是 on - 说明 Claude Code 看到了这个 skill 并允许它运行。

名字、来源和 on 状态确认了 skill 可用

通常 Claude Code 会即时识别新增或修改过的 SKILL.md。如果列表里没有名字，就依次排查：

Skill 在列表里，但自己不触发？重新加载和这个没关系。检查 description，还有字段 disable-model-invocation: true - 它只留下手动调用这一条路。改一下请求的说法，或者按名字调用 skill。手动调用能用，说明安装没问题。

信任之前该检查什么

这里得把兴奋劲儿压一压。Skill 不是一个主题样式，也不是随时能装上、卸下的挂件。它是一组指令，您的智能体会在您的项目里真的执行它。

要检查的不只是主文件，而是整个文件夹。先看这四样：

• 描述 - 是否和您对这个 skill 的期待一致，会不会触发得太宽；
• 正文和里面的链接 - skill 要求做什么，要求打开哪些相邻文件；
• scripts/ 文件夹（如果有的话）- 里面运行什么命令，会碰到哪些文件和网络地址；
• allowed-tools 字段 - skill 提前批准了哪些工具，不用另外确认。

---
name: pre-commit-style
description: 在提交前把项目统一成一致的风格
allowed-tools: Read, Write, Edit, Glob
---

这里的 allowed-tools 既不是工作计划，也不限制智能体的完整能力范围。这个字段只是为调用 skill 的这一轮预先批准了列出的工具。名字很好懂：

• Read - 读文件；
• Write - 创建新文件，整体覆盖已有文件；
• Edit - 在已有文件内部做修改；
• Glob - 按模式查找文件，也就是在项目里走一遍，看看到底有什么。

第一个和最后一个只是查看。Write 和 Edit 能改动文件：如果指令导致这类操作，这一轮可能不会再单独确认。但有这个权限不代表智能体一定会用它。项目的通用访问规则照样生效。

这个字段本身不是坏事：它在您确实希望的地方省掉了多余的确认。但这份清单是 skill 的作者定的，所以第一次运行前值得看一看。

最后一点，没那么吓人，但更常见。Skill 引导智能体，不保证结果。运行之后，看看改动了哪些文件，检查一下结果：一个做样式的 skill 能把页面弄得更好看，但按钮还能不能用，没人替它确认。

去哪里找现成的

为了试一试而从零开始写 SKILL.md，完全没必要。现成的 skill 大多能在公开仓库里找到，或者随插件一起拿到。

最快的办法是让智能体帮忙找一个合适的，但不要盲目安装。说法可以是这样：

帮我找一个用来整理界面的 skill。给我看来源、SKILL.md 和脚本，
说明它会用到哪些文件和工具。在我确认之前，
什么都不要安装。

看过来源和内容之后，再让它把文件夹放进项目的 .claude/skills/，通过 /skills 检查结果。

自己搜索的话，用 Claude skills marketplace 这个查询就行。目录能帮您找到选项，但上了目录不等于安全：内容还是要在安装前读一遍。

SKILL.md 遵循开放的 Agent Skills 标准，所以基本结构能在不同智能体之间通用。但 Claude Code 加了自己的字段和调用方式。把 skill 搬到别的工具里，要先检查它那边实际支持哪些功能。

自己的 skill 可以和智能体一起搭

该动手做自己的 skill 了，这个时机不需要理论就能看出来：同一套流程您第三次解释了。不是任务本身，而是操作顺序 - 看看这个、检查那个、这样整理、那边别碰。反复出现，就说明时机到了。

好消息在这里。不必从空白页开始写 SKILL.md。智能体可以搭出一份草稿，您只需要说清楚这是什么流程，希望它做到什么。看起来就是一次普通的对话：

帮我做一个准备提交的 skill。它应该看看改了什么，
检查有没有多余的文件混进提交，还要按我们的模板写提交信息。
我会自己手动运行，想用的时候再用。
如果要求不够清楚，先提问。

注意，您一个字段都没提，也没去碰文件的结构。要求是用大白话说的，把它们变成字段是智能体的活儿。

如果信息不够，智能体会提问。如果不这样要求，它可能直接自己做假设，所以例子里已经加上了这句。拿到草稿后，检查文件，通过 /skills 找到这个 skill，试着运行一下。

如果这套流程能手动走一遍，那就先跟智能体一起做一遍再打包。一次按步骤完成的提交，能看出哪里需要纠正，说明里少了什么。靠一次真实的运行搭出来的 skill，比靠回忆搭出来的更准。

SKILL.md 长大了怎么办

第一个 skill 几乎总是一个文件搞定，这很正常。挤是后来的事：流程添了细节，一张对照表搬了进来，接着是一份规则清单，三个长例子，某天您打开文件，发现足足有四屏。

都堆在一个地方不好，原因前面提过：只要 skill 一开工，正文就整个加载。四屏的参考资料，哪怕只需要其中一行，也会跟着一起进场。

所以细节挪到旁边的文件里，SKILL.md 里只留一个指引：遇到某种情况，打开某个文件。您已经见过那个带 palettes.md 和 scripts/ 的文件夹了，内部长这样：

## 参考文件

- 配色和搭配方案 - 见 [palettes.md](palettes.md)
- 现成的排版示例 - 见 [examples.md](examples.md)
- 检查对比度：运行 scripts/check.py

参考文件是智能体需要时才打开的。脚本可以直接运行，不用把全部源码拉进对话，所以文件大小几乎不占用上下文。但别人写的脚本，第一次运行前还是要读一遍：它是可执行代码，输出会进入智能体的工作过程。

按用途拆分比较顺手：

• SKILL.md - 流程本身：做什么，按什么顺序，不做什么。调用之前智能体只看到它的描述，调用时才加载正文；
• 参考文件 - 表格、规则、长例子，不是每次运行都需要的东西；
• scripts/ - 用运行代替用文字描述更省事的部分。在别人的 skill 里，这些文件会在运行前被检查；
• 模板 - skill 拿来当起点、再按任务调整的文件。

由此还能得出一个反过来的结论，关于别人的 skill。短短一个 SKILL.md 不代表"简单的 skill"。看看它旁边的文件夹里放了什么。

这对您的工作意味着什么

把这些收拢成几行：

• 反复出现的请求会变成一个文件夹。把工作顺序描述一次，之后每次都照样执行，无论哪个会话、哪一天；
• 自己的 skill 不必从空白页开始写。用自己的话讲清流程，请它补上缺的部分，再检查搭出来的草稿；
• 自动启动时 skill 靠 description 挑选，手动启动靠带斜杠的名字。如果它一直不响应，先弄清楚它在列表里是否可见，自动启动是否被允许；
• /skills 回答的是"它到底装上了没有"这个问题。半分钟的检查省下半小时的猜测；
• 别人的 skill 在安装和运行之前要先读一遍，连同它关联的文件和脚本一起；
• skill 改变的是智能体做事的方式，它不隔离改动的范围，也不能代替对结果的检查。