最近一段时间，GitHub 上被一个词刷屏了，就是skills。点进去一看，有叫superpower skills的，有叫baoyu skills的，还有各种claude code skills、codex skills、opencode skills。如果你跟我一样，第一反应是“这不就是提示词模板合集吗”，那这篇文章可能会改变你的看法。Skills 确实长得很像提示词，但它解决的问题、工作的方式，以及踩坑的点，都跟传统提示词完全不是一个量级。
我花了两周时间，把几个主流编程 Agent（Claude Code、Codex、Cursor、OpenCode）的 Skills 机制都跑了一遍，自己写了 4 个可以复用的 Skill，也踩了不少坑。这篇文章不聊概念，就聊实操：Skill 到底是什么、怎么装、怎么写、怎么跟 MCP 配合、出了问题怎么排查。文章里所有目录结构和代码，都是我在本地跑通过的真实方案，你可以直接照着抄。
1. Skills 不是技能清单，是 Agent 的“岗位说明书”
先说结论：Skills 是一套给 AI Agent 用的、结构化的“岗位说明书”。它告诉 Agent 在什么场景下、按什么步骤、用什么工具，把一类任务稳定地做完。
1.1 为什么提示词不够用了，才轮到 Skills 上场
早期我们用提示词，本质上是在“一次性交代任务”。比如你写一句“帮我分析一下这个项目的代码结构”，模型会基于它的常识和当前上下文里的文件内容，临时组织一套流程。问题是，这套流程每次都不一样。同一个项目，今天让它分析，它先看 README；明天再问，它可能直接去翻 package.json。结果就是你得反复纠正，效率很低。
Skills 做的事情，是把“稳定的流程”从“随机的模型行为”里剥离出来。你把一套最佳实践写成文档，放在固定的目录里，Agent 在遇到匹配场景时自动加载这个文档，按里面写的步骤一步步执行。相当于你给 Agent 发了本《工作手册》，它照着做就行。我试过之后最直观的感受是：输出质量从“看运气”变成了“可预期”。
还有一个很实际的原因：上下文窗口是有限的。一次会话里塞 10 个提示词模板，真正执行时模型反而不知道该听谁的。Skills 是按需加载的，Agent 看到任务，先判断匹配哪个 Skill，再把对应内容读进来。平时不占空间，用到时才加载，这才是它适合复杂任务的根本原因。
1.2 它和 MCP、插件、Prompt Template 到底什么关系
这块是新手最容易绕晕的地方。我一开始也把 Skills 和 MCP 混在一起，后来用多了才理清楚边界。打个比方：MCP 是 Agent 的“手脚”，负责执行外部操作，比如查数据库、调 API、读写文件；Skills 是 Agent 的“大脑皮层”，负责决定遇到什么情况用什么手脚、按什么顺序用。
具体区别可以用一个表说清楚：
| 概念 | 核心作用 | 载体 | 典型例子 |
|---|---|---|---|
| Prompt Template | 一次性对话模板 | 一段文字 | “你是一个资深前端，请审查以下代码” |
| Skill | 可复用的任务流程 | Markdown 文件 + 脚本 + 资源目录 | “按设计稿还原前端页面，并输出结构图” |
| MCP | 外部工具连接器 | 服务端程序 | 文件系统、数据库、浏览器自动化 |
| Plugin / Extension | 工具集成框架 | 插件包 | IDE 插件、命令行扩展 |
这里有个容易误解的地方：Skills 内部可以引用 MCP。准确说，是 Skill 文档里会写明“执行到某一步时，调用哪个 MCP 工具”。最终调用的动作还是 MCP 完成的，但“什么时候调、为什么调”是 Skill 说了算。所以两者的关系是配合，不是替代。
2. 让 Agent 会调 Skill：目录结构与 SKILL.md
任何工具类技术，第一步永远是搞清文件放哪、格式长什么样。Skills 的约定不复杂，但细节很碎，目录错了、文件名不对、格式不对，都可能让 Agent 完全忽略你的 Skill。
2.1 目录约定：不同 Agent 的加载路径
我实测下来，目前主流工具遵循两类目录约定。第一类是以 Claude Code 为代表的.claude/skills/，第二类是以 Codex 和 OpenCode 为代表的.agent/skills/。好消息是，大多数工具为了兼容，两个目录都会读取。我自己现在的标准做法是建一个.agent/skills/目录，同时在项目根目录放一个.claude/skills/作为软链，这样切工具时不用重复维护。
目录内部的结构一般是这样的：
.agent/skills/ └── frontend-design-recovery/ ├── SKILL.md # 核心文件，Agent 首先读取它 ├── reference/ │ └── style-guide.md └── scripts/ └── extract-design-tokens.py每个 Skill 一个独立文件夹，文件夹名就是 Skill 的名字。核心文件必须是SKILL.md，这是所有工具的统一约定。辅助文件可以随便放，但建议按功能分子目录，reference/放参考资料，scripts/放可执行脚本。目录里的文件都会被 Agent 感知，但它不会一次性全读，只会按需打开，这个机制对控制上下文消耗很重要。
2.2 SKILL.md 的 Frontmatter 怎么写才不白写
SKILL.md是一个带 YAML Frontmatter 的 Markdown 文件。Frontmatter 里最关键的两个字段是name和description。name没太多讲究，跟文件夹名一致就行；description是灵魂，因为 Agent 判断“这个任务跟这个 Skill 匹不匹配”，全靠读 description。
我写 description 的经验是：要把“触发场景”和“任务目标”写清楚，但不要写具体执行步骤。比如你写“用于把人脸照片转成素描”，这个描述太粗，Agent 可能在处理风景照时也强行加载它。更好的写法是“当用户上传包含人脸的图片，并希望生成素描风格图像时使用”。反过来，也千万别把步骤写进 description，比如“先裁剪图片，再转灰度，再增强边缘……”，这样会限制 Agent 在遇到特殊情况时做调整的灵活性。
Frontmatter 的基本格式长这样：
--- name: frontend-design-recovery description: 当用户提供设计稿图片（PNG/JPG/Figma 导出图）并要求还原为前端代码时使用。包括提取设计规范、生成页面结构、输出可用组件代码。适用于电商活动页、后台管理界面、移动端 H5 页面等场景。 ---正文部分就是你希望 Agent 执行的具体流程。这里我建议写得“像一个老员工带新人的操作手册”，而不是“给机器人的指令序列”。什么意思呢？把步骤、原则、质量标准都写清楚，但给 Agent 留出做具体实现的自由。它可以按你写的流程走，同时允许它调用合适的工具来自行完成实现。比如某一步我写“按 W3C 规范检查无障碍属性”，至于具体检查哪些，Agent 自己会补充细节。
2.3 触发的两种方式：自动匹配与手动点名
调用 Skill 有两种方式。第一种是自动触发：Agent 根据用户当前请求，在已安装的 Skills 里搜索 description 匹配度最高的，自动加载执行。第二种是手动触发：你直接在对话里输入#skill-name或/skill-name，指定它必须使用某个 Skill。具体语法取决于工具，不过大方向一致。
这里有个很实用的技巧：当你想强制测试一个 Skill 时，手动触发是最好的方式。我在开发初期调试 Skill 的时候，永远手动点名，确认它能跑通之后，再调整 description 让自动匹配生效。这样能避免一个常见困境：你改了 description，但 Agent 还是经常优先加载另一个长得比较像的 Skill，最后分不清是哪个在起作用。
3. 手写一个 Skill：把“图片转前端设计稿”变成可复用工作流
光说理论没有感觉，我直接拿一个我实际开发的 Skill 当案例，拆给你看。这个 Skill 解决的是“设计稿还原前端页面”的问题，这个是前端开发里最高频、最繁琐、也最值得自动化的场景之一。
3.1 先把工作流拆成 Agent 能理解的步骤
在写 Skill 之前，我先把人工还原设计稿的流程拆了一遍，总结成 5 步：
- 分析设计稿，提取色值、字体、间距、圆角、阴影等设计变量；
- 识别页面布局结构，确定是 Flex 还是 Grid，几个区块，嵌套关系；
- 编写 HTML/CSS 骨架，先保证结构和视觉一致；
- 处理响应式，按断点调整样式；
- 做无障碍检查和代码格式化，输出可提交的成品。
这个流程本身并不新奇，但把它稳定地跑下来，效果就很可观了。因为模型每次自己发挥时，总会漏掉其中一步。有时候漏了响应式，有时候忘了提取设计变量，直接硬编码色值。写成 Skill 之后，Agent 会老老实实按步骤走，质量明显稳定。
3.2 SKILL.md 完整示例：主干的写法
下面是我这个 Skill 的主干内容精编版。你不需要照抄，重点关注它的结构和语气。
--- name: frontend-design-recovery description: 当用户提供设计稿图片（PNG/JPG/Figma 导出图）并要求还原为前端代码时使用。包括提取设计规范、生成页面结构、输出可用组件代码。适用于电商活动页、后台管理界面、移动端 H5 页面等场景。 --- # 前端设计稿还原 ## 任务目标 将用户提供的设计稿图片转化为语义化、响应式、可维护的前端代码。 ## 执行流程 ### 第一步：提取设计规范 1. 打开设计稿图片，列出所有出现的颜色值，建立色板。 2. 识别字体族、字号、字重、行高，整理成 typography 规范。 3. 测量主要区块的间距、圆角、阴影值。 4. 将以上结果统一输出到一个 DESIGN_TOKENS.md 文件中。 ### 第二步：确定布局结构 1. 判断整体布局方向（横向导航 / 纵向导航 / 混合）。 2. 识别内容分区，为每个区块命名并标注嵌套关系。 3. 根据区块特征选择实现方式（Flex 用于一维排列，Grid 用于二维布局）。 ### 第三步：实现组件与页面 1. 先写 HTML 结构，确保语义化标签使用正确（header、nav、main、section、footer）。 2. 再写 CSS，优先使用设计变量，避免 hardcode 值。 3. 如果用户要求使用 Tailwind，将设计变量映射为 Tailwind 的配置项；如果要求普通 CSS，则使用自定义属性。 ### 第四步：响应式适配 1. 设置合理的断点（根据内容而不是固定设备宽度）。 2. 优先采用移动优先策略，再逐步增强桌面样式。 ### 第五步：质量校验 1. 检查图片是否全部处理了 alt 属性。 2. 检查颜色对比度是否符合 WCAG AA 级别。 3. 检查是否有未使用的 CSS 类名或重复样式。 4. 格式化代码，提交最终结果。 ## 避坑提示 - 不要为了追求像素级还原而忽略响应式，优先保证结构清晰。 - 设计稿中使用模糊效果时，建议用标准 CSS filter 实现，不要用静态图片模拟。写完之后我测试了几轮，发现一个现象：只要我把“先输出设计变量”这步放在最前面，最终代码的规范性就会有一个明显提升。原因也好理解，模型先看到了整理好的变量清单，后面写代码时会不自觉地引用这些变量，而不是随手硬编码。这就是 Skill 带来的“流程约束力”。
3.3 给 Skill 加执行脚本，复杂任务才能落地
有些 Skill 只靠 Markdown 文档就能完成，比如代码审查、文档编写。但一旦涉及文件批量处理、数据清洗、图片操作，就必须依赖脚本。以我的设计还原 Skill 为例，我用一个 Python 脚本从设计稿里提取主要色值，输出成 JSON，再交给 Agent 去写 CSS 变量。
定义一个能传给 Agent 的脚本，通常是在 SKILL.md 的正文里用代码块写清楚调用方式。我这里给出一个简化版的示例，核心是用 Python 的 Pillow 库识别图片中的主色，供参考。
# scripts/extract_dominant_colors.py from PIL import Image import sys def extract_colors(image_path, num_colors=10): image = Image.open(image_path).convert('RGB') image.thumbnail((200, 200)) # 这里使用量化方法提取主色，避免直接聚类带来的性能问题 reduced = image.quantize(colors=num_colors, method=Image.MEDIANCUT) palette = reduced.getpalette() color_counts = sorted(reduced.getcolors(), reverse=True) colors = [] for count, index in color_counts: offset = index * 3 rgb = tuple(palette[offset:offset + 3]) colors.append({ "rgb": f"rgb{rgb}", "hex": "#{:02x}{:02x}{:02x}".format(*rgb), "count": count }) return colors if __name__ == "__main__": colors = extract_colors(sys.argv[1]) for color in colors: print(f"{color['hex']} {color['rgb']} occurrence={color['count']}")在 SKILL.md 里，我会在“第一步：提取设计规范”下面加一行说明，告诉 Agent 可以运行这个脚本辅助识别色值。实践下来，让 Agent 先跑脚本再写样式，比让它自己“看”图片更可靠。因为模型对颜色的感知并不总是准确，特别是相近色、阴影里的暗色，脚本给的是精确值，一步到位。
4. Skill 和 MCP 工具怎么配合才顺手
围绕 Skills 的搜索热词里，出现频率最高的一个问题是“Skills 如何调用 MCP 工具”。我一开始也被这个问题困住过，后来发现关键不在于代码层面怎么打通，而是文档结构上怎么安排。Agent 自己会读取 Skill 文档，当流程里标注“需要查资料时调用某某 MCP 工具”，它自然就会去调用。
4.1 在 Skill 文档里写明工具调用时机
以我写的一个“前端技术调研”Skill 为例，它的一个典型场景是：用户希望我分析某个新框架是否适合项目，我需要先上网查最新版本、社区评价、更新记录，再结合当前项目情况给出建议。这时候，Skill 文档里就有这么一段：
### 执行步骤 1. 首先，使用 web_search 这个 MCP 工具搜索该框架的官方文档和最新版本信息。 2. 如果官方文档页面无法直接读取，使用 web_fetch 工具获取页面正文。 3. 顺着文档把安装方式、核心 API、迁移路径整理出来。 4. 结合项目现状（README、package.json）给出可行性与风险分析。注意，我在这里并没有写复杂的代码去调用 MCP，只是把“调用什么工具、在哪个环节用”写清楚。Agent 看到这些说明后，会根据当前环境可用的 MCP 服务名称去发起调用。所以实际工作时，往往是“Skill 提供流程大纲，MCP 提供实际操作工具”，两者搭配起来效率才会高。你需要确保的是，文档里写的工具名称和你实际配置的 MCP 服务名完全一致，比如web_search、web_fetch，别用别名，否则 Agent 可能找不到。
4.2 实测：让 Skill 在联网检索场景下干活
我测试过一个“行业竞品分析”的 Skill，它在流程里有一步是“搜索这些竞品最近三个月的版本更新和用户反馈”。在配好相应 MCP 工具后，Agent 确实会自动完成搜索、汇总并输出对比表格，整个流程非常顺畅。如果不配 MCP，Agent 会用自己的内部知识硬写，内容很容易过时。
不过这里面有个需要当心的地方：MCP 工具返回的内容可能很冗长，动辄上万字的网页正文，会直接冲击上下文窗口。我的解决办法是在 Skill 的流程说明中主动要求“先抓取页面正文，提取前 500 字的核心要点；如果有版本号或关键数据，单独列出；不要粘贴完整正文”。这个约束看起来很简单，但能帮你省掉大量上下文占用，Agent 的执行效率也会高很多。
4.3 共享给团队时的注意事项
如果你打算把 Skill 提交到团队仓库共享，除了文件本身，还要附一个说明，说清楚这个 Skill 依赖哪些 MCP 服务、哪些脚本、哪些外部命令。我见过不止一次，同事拿到了一个很好的 Skill，但本地没装对应的 MCP 服务，结果 Skill 跑起来直接报错，最后大家误以为是 Skill 本身有问题。所以在你写 SKILL.md 时，最好在 Frontmatter 下面加一个“依赖环境”的章节，把需要预装的东西列清楚，这是团队协作里最容易被忽略、却最重要的细节。
5. 常见问题排查：为什么我的 Skill 不生效
Skills 机制本身不复杂，但真正用起来，各种奇怪的问题一点也不少。我自己整理了一份排查表，这些问题你大概率也会遇到。
5.1 速查表：Skill 不生效的 6 个常见原因
下面这张表是我个人踩坑的记录汇总，按出现频率排序。如果你发现 Skill 没有被加载，先从第一行开始查，大概率能快速定位。
| 现象 | 可能原因 | 排查与解决办法 |
|---|---|---|
| Agent 完全忽略 Skill | 目录结构不对或文件名不是 SKILL.md | 确认骨架是.agent/skills/技能名/SKILL.md，文件夹名字不能有空格，文件必须叫 SKILL.md |
| 有多个 Skill，Agent 总是选错 | description 写得太宽泛，或关键词不精准 | 重新打磨 description，写清触发场景，比如“当用户提供截图并要求还原为代码时使用”而不是“处理图片” |
| 手动点名也不生效 | 工具版本太低，或字符写错 | 检查工具版本是否支持 Skills，确认是#skill-name还是/skill-name，参照官方文档 |
| Skill 执行一半突然停止 | 脚本报错或依赖缺失 | 手动运行脚本排查错误，检查依赖环境，尤其注意相对路径问题 |
| 同一个任务两次结果差异巨大 | SKILL.md 中流程描述不够具体 | 把步骤写得更细，比如指定输出文件的格式、命名规则、必须包含的检查项 |
| 上下文被 Skill 相关内容占满 | Skill 文档太长，或子文件被一次性加载 | 精简 SKILL.md 正文，把长内容移到 reference 子目录；在文档里明确“按需读取子文件” |
5.2 一个真实的排查案例记录
前两天我帮朋友排查一个 Skill，现象是：他把一个“测试用例生成”的 Skill 放进目录后，Agent 完全无感，每次还是按默认方式生成测试。我远程看了一眼他的目录，问题立刻找到了。他把文件夹建成了test-cases-skill/SKILL.md，文件夹名字没问题，但 SKILL.md 的 Frontmatter 里name写的是unit-test-generator，两边名字对不上。有些工具靠文件夹名识别，有些靠name字段识别，一旦不一致，就会出现加载混乱。改成一致后，问题马上解决。
还有一次是路径问题。我的 SKILL.md 里引用了./scripts/extract.py，但脚本实际放在scripts/tools/extract.py，相对路径错了。这里提醒大家：SKILL.md 里引用脚本时，路径要相对于 SKILL.md 文件本身来写，不要相对于工作目录。因为 Agent 执行脚本时，它的当前工作目录可能是项目根目录，而不是 Skill 所在目录。
5.3 调试 Skill 的好用方法：写一个“自检版”
如果你想系统调试一个 Skill，而不是每次靠猜，可以给 Skill 加一个“自检模式”。做法是，在 SKILL.md 的末尾加一个章节，写上：
## 自检清单 在完成上述任务后，请逐项确认以下内容，并把结果写入 OUTPUT.md： - [ ] 是否提取了设计变量 - [ ] 是否包含响应式断点 - [ ] 是否检查了无障碍属性 - [ ] 是否有未使用的 CSS 类名 - [ ] 引用的脚本是否成功运行这样做有一个额外好处：Agent 在收尾时自己会当一回“质检员”，根据清单复查一遍结果。这个技巧看起来简单，但对输出质量的改善非常明显。相当于你给流程加了一层强制校验，模型在做完活之后还要自证“我做完了、做对了”。
6. 社区公认的高质量 Skills，以及怎么挑
现在的 Skills 生态有点像早期的 App Store，什么牛鬼蛇神都有。GitHub 上标星最高的几个，比如superpower skills和baoyu skills，质量确实不错，但也不是所有内容都适合你的工作流。我的建议是：不要全部照搬，把别人好的思路拆出来，改造进自己的 Skill 里，比直接下载一堆“通用包”有用得多。
6.1 我推荐优先收藏的三类 Skill
第一类是“研究类”，比如学术文献检索、技术调研、竞品分析。这类 Skill 特别适合和 MCP 联网工具配合，能把过去 1 小时的调研压缩到 10 分钟。第二类是“代码项目审查类”，它会指导 Agent 按层次分析一个仓库，从依赖、架构、代码风格、测试覆盖等几个维度分别输出报告，非常适合接手旧项目时快速摸清底细。第三类是“文档与内容生成类”，比如把会议录音转成结构化的周报、把零散需求整理成 PRD，它们的核心价值在于格式规范，能让输出直接投入使用。
还有一类比较特殊，是“数学建模”方向的 Skills，在高校和竞赛圈子里讨论度很高。这类 Skill 通常会把建模流程拆成“问题分析、模型假设、数学建模、算法设计、结果检验”几个步骤，配合 Python 脚本做数据预处理和可视化。如果是竞赛用途，建议自己在本地跑一遍，把脚本路径和依赖调通，别直接指望 Agent 全自动完成。
6.2 如何判断一个开源 Skill 能不能直接用
判断标准就三条：看文档是否写清了适用场景；看是否列出了依赖环境；看是否有明确的输出产物定义。如果一个 Skill 的 README 只写了一句“牛逼的 Skills 集合”，连每个 Skill 的触发场景都没说明白，那哪怕它有一千颗星也不适合生产使用——因为你根本不知道它会在什么场景下被触发、会产生什么行为。相反，如果文档里清楚地写着“当用户要求生成接口测试用例时使用，依赖 HTTP 抓包 MCP 服务”，那基本可以判断作者是认真打磨过的。
我在挑选的时候还有一个习惯，就是先看它的 SKILL.md 正文是不是用了“检查清单”和“避坑提示”这种结构。有这些内容的，说明作者实际用过、被坑过，写出来的东西可信度更高。纯讲流程没有实战细节的，多半是凑出来的。
6.3 直接用的两个注意点
把社区 Skill 直接放进本地目录前，务必看一遍它的脚本内容。Skills 里的脚本是有执行权限的，Agent 在流程要求时会运行它。如果你不确定脚本做了什么，就先在隔离环境里跑一遍，确认没有危险操作再放进正式目录。这个习惯在团队环境里尤其重要，安全怎么强调都不为过。
另外，社区 Skill 默认的 description 往往写得比较宽泛，直接装进来可能跟你的现有 Skill 冲突，导致 Agent 选错。我的做法是，安装后立刻改写 description，让它的触发范围更精准，并删掉我项目里用不到的子模块。这样既能用上社区经验，又不会污染本地的工作流。
7. 从单个 Skill 到一套工作流：我的个人实践建议
最后聊点更贴近日常经验的东西。Skills 这个模式真正厉害的地方，不是“一个 Skill 搞定一个任务”，而是你可以基于它搭建一套完整的工作流。拿我自己的技术写作流程举例：我把“素材收集、初稿撰写、代码示例验证、SEO 检查、排版格式化”各自拆成一个 Skill，再在主 Skill 里按顺序引用它们。这样当我输入一个主题时，Agent 会像流水线工人一样，一步步产出有稳定质量的成品，而不是在一条上下文里从零硬写。
在生产环境里，我会保证“项目私有 Skill”优先于“用户全局 Skill”，这样不同项目可以维持各自的技术栈规范。比如项目 A 用 Vue 写组件，项目 B 用 React，它们的组件生成 Skill 内容完全不同，放在各自项目的.agent/skills/下就不会串。
写过几个 Skill 之后，我的体会是：写它的过程，实际上就是在倒逼你自己把平时的工作流想清楚。我以前带人的时候说“按最佳实践来”，但其实我自己也没有逐字写下来过。写 Skill 逼着我把它白纸黑字整理出来，这个过程本身的价值，可能比最后生成的那几个文件还要大。如果你正在学 Agent 相关的开发，建议第一条先别想着搞那些花哨的功能，就从记录你自己的日常操作开始。
