最近这一个月，我最大的感受是“skills”这个词在 AI 圈里的出镜率高得离谱。翻社区帖子，满屏都是“前端开发 skills”“论文写作 skills”“分镜 skills”，再往深挖一层，就是各种“agent skills 测试”“codex 好用的 skills”“Claude agent skills 第一性原理深度解析”。而且不只是讨论，是真有人拿它在干活：写论文的、审代码的、剪视频的、做安全测试的，全都在往这个筐里装东西。
我第一次真正意识到 skills 的价值，是在一次代码评审场景里。你平时让 agent 看一段前端代码，它给你回一段大而化之的通用建议，模板感极强。但装上一个专门为代码审查设计的 skill 之后，它竟然会按着流程先读入口文件、再摸依赖树、再对着可访问性规范逐条核，最后输出一份有边界情况、有性能隐患、有修改建议的完整报告。这玩意儿跟单纯把 prompt 写长完全不是一回事——它是一整套操作手册和工作流规范，而且 agent 是真的会照着一步步执行的。
所以这篇文章，我想把自己这段时间折腾 skills 的完整经验整理出来。从它解决了什么问题、内部结构长什么样，到怎么从市场装、怎么自己写、怎么排查坑，一次讲透。虽然会涉及 Claude、Codex 等不同生态，但核心逻辑是共通的，你只要抓住一个 skill 的本质，换平台也就是换层皮的事。
1. 为什么“skills”是当下 AI 圈最值得投入的事
1.1 从配置到能力模块：skills 到底解决了什么问题
要理解 skills 的价值，先得回顾一下没有它的时候我们是怎么跟 agent 相处的。以前你让一个 AI 助手干一件垂直的事，基本靠两招：写一段巨长的 system prompt，或者在一轮对话里反复“喂”背景材料和规则。这两招都有硬伤。system prompt 写太长，一次对话还没开始干活，光读规则就烧掉一大截上下文窗口；而且规则写在一起，互相干扰。对话里临时喂材料更是看运气，同一件事换个人问就有不同的结果，完全没有可复现性。
skills 的思路是完全反过来的。它是把某一种能力拆成一个独立的能力单元，和主对话剥离开，平时不占上下文，只有遇到相关任务时才被 agent 主动装载。我比较喜欢的一个类比是螺丝刀头：你手里是一把带快换接口的螺丝刀，工具包里可换的头就是一个个 skill，遇到十字螺丝换十字头，遇到内六角换内六角，而不是每拧一种螺丝就重新造一把整刀。
这种“按需装载”的设计带来两个直接好处：一是上下文更省，agent 的注意力不会被无关规则分散；二是能力可复用、可共享。同一个代码审查 skill，今天在你的项目里能用，明天拷给同事，在他的项目里表现基本一致，因为规则是固化的、可验证的。
1.2 当前生态全景：Claude、Codex 与社区三方夹击
现在一提到 skills，最容易混的是好几个不同的东西。Claude 官方推出的 Agent Skills 是一套定义明确的技能格式，核心是一个 SKILL.md 文件，配合可选的辅助脚本和资源，放进特定目录就能被 Claude 系 agent 自动发现。Anthropic 还专门建了 skills 仓库，官方收集了一批高质量的技能，涵盖代码、分析、内容处理等常见领域。
另一边，OpenAI 的 Codex 也在做类似的事。Codex 的能力体系里也引入了“skills”这个概念，结合 AGENTS.md 和自定义指令，让 agent 在不同仓库里能加载对应的工程技能。代码生成、批量任务处理、代码库维护，这些都是 Codex skills 的高频场景。
还有第三股力量是社区和第三方框架。比如有人做了“superpowers”这种技能集合框架，把一堆小技能组织成体系化的工作流，允许你用自然语言触发复杂操作；还有 reasonix 这类工具支持用户自定义扩展技能并一键安装。再加上 MCP 协议在工具层的配合，现在整个生态看起来就是“基础设施 + 协议 + 技能包”三层结构，skills 恰好是其中最贴近业务、最常被使用者感知的那层。
如果你是做前端开发的，大概率在 GitHub 上搜过“前端开发 skill”“skills 大全”；如果你是写论文或做视频的，可能在找“论文写作 skill”“分镜 skill”。这些需求现在都已经有了现成的东西，只是很多人不知道去哪找、怎么装、装了之后怎么验证它到底有没有生效。
2. 拆开一个 skill：里面到底是什么
2.1 SKILL.md 的骨架：元信息与控制指令的分离
一个 skill 的核心就是 SKILL.md 文件。这个文件遵循一套特定的结构——开头有一段 YAML 格式的元信息，后面是给 agent 看的指令正文。元信息的作用是让 agent 在“观测阶段”就能判断这个 skill 是否适用于当前任务，指令正文则决定 agent 进入技能之后具体怎么干活。
我拿一个典型的前端代码审查 skill 来举例。它的元信息长这样：
--- name: frontend-code-review description: 对前端项目进行代码审查，输出包含性能、可访问性、兼容性和代码规范的结构化审查报告。适合在用户要求 review、评审、检查前端代码时使用。 license: MIT ---这个description字段，是整个文件里最容易被低估的部分。它决定了 agent 在什么情况下会主动想起这个 skill。如果你写得太宽泛，比如“审查代码”，那么写后端代码时它也可能被唤醒，容易串台。写得太窄，可能真到需要它触发的时候 agent 根本没反应。经验是把这个字段当成“唤起条件”来写，里面埋好触发场景、触发目标、边界范围三个信息。
元信息下面是正文，这部分是真正的控制指令。我是说，这跟单纯 prompt 不同。一段 skill 正文通常包含：
- 任务目标：这个 skill 要达成的最终输出是什么。
- 执行步骤：按顺序列出的操作流程，尽量拆成可验证的小步骤。
- 决策规则：遇到不同情况时该如何选择分支。
- 输出格式：最终交付物的结构、模板、类型要求。
还是用前端代码审查的例子，正文开头可能会这样写：
# 前端代码审查流程 当用户要求进行代码审查时，按以下步骤执行： 1. 先列出项目中所有入口文件（package.json、vite.config、src/main.* 等），了解项目技术栈。 2. 读取 package.json 的 dependencies 和 devDependencies，逐项标记版本偏旧的依赖。 3. 按页面路由逐个审查组件代码，重点关注：状态管理是否合理、副作用是否被妥善清理、组件是否过度渲染。 4. 对所有交互组件检查键盘可访问性和 ARIA 标签。 5. 输出审查报告，模板见 ./templates/review-report.md。你看，这已经不是“给 AI 一段建议”，而是“给 agent 一套 SOP”。agent 会按照这个 SOP 去逐步执行，每一步都会真实地调用工具、读取文件、生成中间结果。
2.2 附属资源：让 skill 拥有真正的工作台
光有一个 SKILL.md 还不够，复杂的 skill 通常伴随资源文件，最简单也最重要的是子技能和参考文档。在前面例子里，review-report.md就是一个输出模板，它告诉 agent 报告长什么样、哪些章节必须出现、每章大概什么样的深度。这样做的好处是，agent 产出的结果格式高度统一，不会今天给你输出 Markdown 表格，明天就改成一段散文。
资源文件还可以放辅助脚本。比如说，一个前端性能分析 skill，它可能会有一个 Python 脚本去解析打包产物，把不同模块的体积和依赖关系抽出来，然后 agent 基于脚本输出分析。这种“让 agent 自己调用自己目录里的脚本”的能力，是 skill 从“高级提示词”升级为“真正工具”的分水岭。
目录结构通常会这样组织：
frontend-code-review/ ├── SKILL.md ├── assets/ │ └── review-report-template.md ├── scripts/ │ └── analyze_bundle.py └── examples/ └── before-after.mdexamples目录也很有用。给 agent 放一两组“坏样本 vs 好样本”的对比，它能更快学会你的输出偏好。这有点像带新人，光说“要写出高质量的审查报告”是没用的，给一份满分模板对照着写，效果立竿见影。
2.3 一个前端开发 skill 的完整目录样例
如果你正在做前端，可以参考这个常见的目录组织方式：
my-skills/ ├── frontend-audit/ │ ├── SKILL.md │ ├── assets/ │ │ ├── audit-checklist.md │ │ └── report-template.md │ └── scripts/ │ └── collect_metrics.mjs ├── component-generator/ │ ├── SKILL.md │ └── examples/ │ └── tabs-component.md └── dependency-upgrader/ ├── SKILL.md └── scripts/ └── changelog.py你注意，每一个子技能都尽量保持独立性。不建议把“审查代码”和“重构代码”塞进同一个 skill，因为触发场景不同，混在一起会互相污染。一个 skill 最好只承载一个动作，就像螺丝刀的每个替换头只承担一种头型。
3. Skills 获取与安装实操：官方市场与社区仓库
3.1 官方市场的结构与分类
如果你是 Claude 系的用户，最省事的途径是官方市场。Anthropic 官方仓库里按分类放了不少技能：分析、代码、数据科学、内容创作、软件开发等。官方技能的优点不是“写得特别好”，而是边界定义干净——它们不会乱触发，不会在不该生效的场景突然跳出来抢活。
如果你是 Codex 系，它的技能生态主要围绕工程任务展开。GitHub 官方也提供了一个 skills 仓库，里面偏工程效率向，比如代码审查、仓库分析、重构建议、批处理任务。需要注意的是，Codex 的 skills 和 Claude 的 skills 在安装路径和触发机制上略有区别，但核心的文件模型类似。
还有一个偏商业化的市场，就是各类第三方技能平台。有专门做技能分发下载的站点，也有直接把技能打包成 ZIP 让人下载安装的资源站。搜索时可以用“skills 下载平台”“skills 安装包下载”这类关键词。不过我建议你先从官方渠道入手——很多第三方的技能描述写得天花乱坠，装进去才发现就是一段很短的 prompt，质量参差不齐。
3.2 从 GitHub 检索与安装社区 skills
GitHub 是现在最大的 skills 集散地。常用的检索词有这么几个：awesome agent skills、claude skills、codex skills、superpowers skills。搜出来往往是一整个聚合仓库，里面目录结构大致是 skills/ 下按领域分类，每个子目录就是一个独立 skill。
安装流程其实不复杂，以 Claude 举例。先找全局技能目录，一般是在你的用户目录下建.claude/skills/文件夹；如果是项目级使用，就在项目根目录下建.claude/skills/。
# 新建技能目录 mkdir -p ~/.claude/skills # 克隆技能仓库（假设是社区 skills 聚合仓库） git clone https://github.com/xxx/awesome-skills.git cp -r awesome-skills/skills/frontend-audit ~/.claude/skills/装完怎么验证有没有被识别？最简单的方法是直接在对话里提一个跟该 skill 相关的任务，比如审查一段项目的代码，然后观察 agent 的输出里有没有出现该 skill 定义的步骤或者输出模板。如果你在日志工具里能看到“skill loaded”“using skill”之类的记录，那就是生效了。
Codex 的安装路径类似，主要是把技能文件夹放进 Codex 能识别的配置目录。如果你是 IDE 用户，也可以直接在 IDE 的配置面板里管理技能，很多工具已经支持可视化开关。
3.3 版本管理与更新注意
装 skill 只是开始，后续维护才是重头戏。社区技能更新频率很高，今天装的技能可能下周就升级了；但你手里的项目可能是用旧版本验证过的。我的习惯是给技能目录打标签，比如后面加个@v1.2，改动前先看 changelog。
还要注意一个特别容易踩的坑：license。GitHub 上很多 skill 仓库虽然代码是开源的，但许可证各不一样。拿去商用之前一定要看 license 字段。另外，一个技能可能依赖其他技能，比如 superpowers 框架下的小技能会引用框架的公共模块，缺了依赖单独装可能什么都跑不起来。这时候不要慌，回去看它的 README，通常有依赖关系说明。
4. 手写一个属于自己的 skill：从需求到测试闭环
4.1 选题与需求拆解
自己写 skill，第一件事不是打开编辑器，而是想清楚你要它反复解决什么问题。这个问题的特征应该是：高频、重复、有明确流程、当前 agent 回答质量不稳定。满足这四条，就值得做成 skill。
我经常被人问：“我要不要把我的日常 prompt 全转成 skill？”我的回答是没必要。写论文的时候，你可能有一堆步骤：先列大纲、再做文献检索、再逐段起草、然后统一引用格式。这个过程够复杂，但如果你每次都靠临时对话解决，结果经常前后不一致——这个就适合固化成 skill。反过来，你只是偶尔问一句“这句话怎么润色”，那直接对话就够了，做成 skill 反而是过度设计。
拆需求的时候，把整个流程写在纸上。比如“论文写作”，拆出来可能是：
- 明确论文主题、目标期刊或受众、篇幅。
- 检索相关背景资料，列出三到五个关键词方向。
- 生成论文框架，包括摘要、引言、方法、结果、讨论、结论。
- 逐节起草，每节给出核心论点、支持证据、段落衔接。
- 最后格式化引用，按指定参考文献格式输出。
这个清单没有歧义，每步都是 agent 能执行的动作。
4.2 编写 SKILL.md 的实操技巧
写正文的时候，最容易犯的错是把“目标”当步骤写。比如你写“识别代码中的问题”，这就是目标，agent 看完依然不知道怎么落地。正确的写法是给可操作的动作：“打开 package.json，把 dependencies 逐个与最新版本比对，标记差异超过一年的包。”这中间有对象（package.json）、有动作（比对、标记）、有标准（一年），agent 才能执行。
元信息里的name要取一个能在日志里一眼认出来的名字，建议是小写连字符风格。description我前面说了要给“唤起条件”，这里再补充一点：里面最好同时出现任务词汇和平台/领域词汇。比如前端代码审查的描述里，既有“审查、review、评审”这类任务词，又有“前端、HTML、CSS、React、Vue”这类领域词。这样不管用户从哪个词进入，agent 都能瞟到你。
指令正文里加一套“输出质量自检”是很有用的。你可以在 SKILL.md 末尾写一个 checklists 区，强制 agent 在交出结果之前逐条核对。短例子：
## 输出自检清单 - [ ] 已检查所有目标文件而非仅入口文件 - [ ] 每条建议都标注了严重级别（blocker / major / minor） - [ ] 报告引用了具体文件路径和行号这种自检手段，在 skill 使用的早期对质量提升极有帮助，原因很简单：不用自检的 agent 会默认输出“尽力而为”，而一旦你给了显式的检查清单，它就会像交卷前查卷子的学生一样，大概率顺手改掉错误。
4.3 用“测试跑一遍”来完成闭环
写完之后，最重要的一步是测试。很多人装了自己的 skill 就直接开始生产用，翻车之后又觉得是自己写的废话。我的经验是至少跑三轮。
第一轮叫最小触发测试：开一个新对话，直接说“用 xx skill 做一次 xx”，看 agent 能不能认出并加载它。如果完全没有反应，多半是 description 跟你的触发词对不上。
第二轮叫边界测试：换几种不同的表达方式触发，比如改变语序、换个同义词，看看描述里有没有覆盖全。还有一种边界是“不该触发的时候别触发”——比如你写的是前端审查 skill，在用户聊后端代码时，它不应该跳出来。两者同样重要，因为跳出来抢话的体验非常糟。
第三轮叫全流程跑测：拿一个真实案例从起点跑到终点，过程中记下 agent 卡在哪个步骤。常见的卡点在第二步，比如让它做一个复杂分析时，它干脆跳过了某个步骤直接给结论——这就是指令还不够细。回 SKILL.md 里补上“必须先……再……”这类顺序约束。
我自己测试时经常会用一个小脚本模拟一连串任务，把结果记到测试日志里。你也可以用项目里的测试框架去跑函数，效果一样。重点是有记录、有对比，不然改了一版技能后你根本不知道是变好了还是变差了。
4.4 一个论文写作 skills 的快速示例
如果你着急上手，我给你一个可以直接扩展的论文写作 skill 骨架：
--- name: academic-writing description: 辅助撰写学术论文与研究报告，包括选题拆解、文献梳理、大纲生成、逐节起草、参考文献格式化。适合在用户要求写论文、写文章、写研究报告、整理学术思路时使用。 --- # 学术论文写作助手 ## 流程 1. 与用户确认：主题、目标学科、目标读者层次、篇幅要求、引用格式（APA/MLA/GB/T 7714）。 2. 拆解主题：把主题拆成三个可直接检索的子问题，列出每个子问题的核心概念。 3. 规划章节：生成论文大纲，每个章节包含“本章目标、需要回应的论证点、预估字数”。 4. 逐章起草：每次输出一个章节，附带上下文衔接建议。 5. 自检：检查摘要是否覆盖背景-方法-结果-结论四要素；检查引言是否交代研究动机；检查每个论点是否有支撑材料。 6. 整理参考文献：按指定格式输出，标记待补全项。注意步骤 5 自检清单内部有强烈的结构化要求，这能防止 agent 天马行空。你后面还可以加一个./assets/reference-formats/目录，里面放不同引用格式的模板，让 agent 直接读取。
5. 常见问题与排查技巧实录
我在折腾 skills 的过程中踩过的坑至少能写满两页纸。这里挑最典型的几个，按“问题—排查思路—解决办法”的方式列出来，方便你遇到时直接查阅。
| 问题现象 | 排查方向 | 解决办法 |
|---|---|---|
| skill 完全没被加载，agent 按普通对话回应 | 路径不对 / 名字没对上 / 开启方式有误 | 检查技能目录是否符合官方约定的路径；确认描述里是否有触发词；试试直接在对话里点名“用某 skill” |
| skill 被触发，但执行流程跟 SKILL.md 不一致 | 指令写成了目标而非步骤；描述字段过度宽泛 | 把指令改成带检查步骤的可执行动作；指令里加入明确排序词和“必须/禁止”约束 |
| 同一 skill 在不同会话表现差异很大 | 依赖未固定 / 外部API / 数据获取不稳定 | 把脚本和参考模板一并放进目录；必要时锁定版本；对输出质量做自检校验 |
| 多个 skill 在相近任务上互相抢话 | 描述字段边界重叠 | 重写各 skill 的 description，强调各自的 exclusivity，用“只在……时触发”来限定 |
| 上下文很容易超长 | 技能正文太啰嗦 / 一次装载了太多附件 | 精简正文，把冗长规则移到 assets 里的参考文件；只放必要脚本和模板 |
| skill 里的脚本无法执行 | 权限 / 运行时缺失 / 路径问题 | 检查脚本解释器是否可用；执行权限是否放行；在脚本内使用相对路径读取资源 |
| 升级 skill 后行为反而退化 | 与相关组件有版本兼容问题 | 锁版本保留旧目录；看 changelog；必要时做 A/B 对比再切换 |
这张表里，最容易被忽略的是第一个问题。很多人装完 skill 就以为万事大吉，结果 agent 根本没加载。建议装完立刻做一次最小触发测试，别等生产环境里才暴露。
6. 我的几条经验与心得
折腾了这么久，我最后想掏心窝子讲几句个人体会——这些内容不太容易查资料查得到，因为基本是拿时间换来的教训。
第一，description 是技能的“命门”。我见过太多写得挺细的 SKILL.md，败在 description 只写半句话。你在描述上省下的十个字，可能会让 agent 在正确的场景里对你写得好的 skill 视而不见。把这个字段当成一篇短文的标题来打磨，反复试。
第二，少即是多，别想一次解决所有问题。一个 skill 聚焦一件事，做到闭环、做到可验证，比一个试图覆盖“代码审查+重构+性能测试+自动修 bug”的大杂烩靠谱得多。不是说后一种不能做，而是你的指令和自查清单很快就会失控。先从最小闭环开始，后面再加分支。
第三，把 skill 当作团队 SOP 来管理。如果你在一个小团队里用 agent 协作，技能文件就是一种把个人经验沉淀成团队标准的方式。我见过一个前端组把代码规范写进审查 skill，从此每次 PR 的 review 质量都稳定在高水位，因为技能统一了“什么是规范”的答案。
第四，构造测试用例、定期回归。这是我最想强调的。技能不是写出来就完了，它跟软件一样会腐化。项目技术栈变了、依赖升级了、个人标准变了，都需要回来改技能并回归测试。我自己的习惯是每个月花半天时间跑一遍所有自用技能的测试集。这半天不会白花，它保证我的“数字生产线”不出噪音。
我自己还有一个偏门小技巧：在技能目录里放一个CHANGELOG.md，每次改动都写一句话。这个文件对 agent 本身没作用，但对人非常有用——三个月后你回头看，能清楚知道自己当时为什么做那个决定。这个习惯救了我好多次，因为我给某个技能加了一段复杂分支之后，第二个月再看往往会惊觉“我当时是在想什么”。
Skills 这个方向还在野蛮生长，官方标准、第三方框架、社区实践每天都在变。但不管平台怎么变，一套好的技能方法论是通用的：想清楚边界、写可执行指令、挂好参考模板、带上自检清单、持之以恒地回归。你只要把这套心法打通，今天用 Claude 没压力，明天切到 Codex 也不会从零开始。这套经验，是我最想让你带走的东西。
