1. 从"skills"这个模糊词说起：它到底指什么
第一次看到"skills"这个标题，很多人会懵。它太宽泛了，宽泛到像是随手敲的一个词。但结合热搜词里高频出现的 Claude Code、Codex、plugin、agents 这些词，方向其实很明确——这里说的 skills，指的是 AI 编程助手生态里的技能包机制，也就是给 AI Agent 挂载可复用能力模块的那套东西。
我接触这套机制是从 Claude Code 开始的。当时最大的困惑不是"怎么装"，而是"装了到底改变了什么"。用了一段时间才想明白：skills 本质上是把一段固化的、经过验证的工作流，封装成 AI 可以按需调用的能力单元。它和 plugin 不是一回事，和 agent 也不是一回事，但三者经常被混着说。plugin 更偏向工具层面的扩展，agent 偏向自主决策的执行体，而 skills 更像是"给 agent 准备的一套标准操作手册"——遇到某类任务，直接按手册走，不用每次从零推理。
这个区别很关键。因为如果你把 skills 当成 plugin 来理解，就会期待它提供某个具体功能按钮；如果你把它当成 agent，就会期待它自己规划任务。实际上 skills 的价值在于降低重复推理成本、统一输出质量。举个我自己的例子：我经常需要把一段零散的会议记录整理成结构化的周报。以前每次都要重新描述格式要求，AI 每次输出的结构还不太一样。后来我把这套流程做成一个 skill，之后只要触发它，输出格式就固定了，省掉了大量来回沟通。
所以这篇内容适合谁看？三类人：一是刚接触 Claude Code 或 Codex、搞不清 skills 定位的新手；二是已经会用但想自己写 skill 的进阶用户；三是团队里想把 AI 工作流标准化的负责人。我会从概念拆解讲到实际编写，再到踩过的坑，尽量把每个"为什么"都讲透。
2. skills、plugin、agents 三者的边界到底在哪
2.1 用一个类比把三者摆清楚
我习惯用一家餐厅来类比。agents 是厨师，负责根据订单决定做什么菜、怎么做；plugin 是厨房里的设备，比如烤箱、搅拌机，提供具体的能力；skills 是菜谱，告诉厨师这道菜的标准做法是什么。厨师可以没有菜谱凭经验做，但有了菜谱，出品就稳定，新人也能快速上手。
这个类比能解释很多实际现象。比如为什么 skills 通常不直接"执行"操作——它不执行，它是指挥 agent 怎么执行的。为什么同一个 skill 在不同 agent 上表现可能不同——因为厨师水平不一样。为什么 plugin 装错了会直接报错，而 skill 写错了往往只是输出质量下降——因为设备坏了没法用，菜谱写错了还能凑合做。
2.2 为什么这个边界容易搞混
热搜词里同时出现 "claude agent skills" 和 "codex skills"，说明大家在不同平台上都遇到了这套机制，但各平台的叫法和实现细节不一样。Claude Code 里的 skills 更强调通过文件系统组织，Codex 里的 skills 则和它的任务执行模型结合得更紧。这种差异导致很多人以为它们是同一个东西的不同叫法，实际上底层设计思路有区别。
我踩过的一个坑就是：把 Claude Code 里写好的 skill 直接搬到 Codex 上用，结果触发逻辑完全不对。后来才明白，Claude Code 的 skill 更依赖描述文本的语义匹配，而 Codex 更依赖显式的调用声明。这个差异不搞清楚，跨平台复用就是白费功夫。
2.3 一张表看清核心差异
| 维度 | skills | plugin | agents |
|---|---|---|---|
| 本质 | 标准化工作流 | 能力扩展模块 | 自主执行体 |
| 触发方式 | 语义匹配或显式调用 | 安装后自动生效 | 接收任务后自主规划 |
| 出错表现 | 输出质量下降 | 功能不可用或报错 | 任务跑偏或卡死 |
| 复用性 | 跨任务复用 | 跨项目复用 | 跨场景复用 |
| 编写门槛 | 中，需要理解任务拆解 | 高，需要编程 | 高，需要设计决策逻辑 |
这张表是我自己整理出来贴在显示器旁边的，每次搞混的时候就看一眼。尤其是"出错表现"这一行，帮我省了很多排查时间——输出不对先怀疑 skill，功能没有先怀疑 plugin，任务乱跑先怀疑 agent 的规划逻辑。
3. 一个 skill 从想法到落地的完整过程
3.1 先想清楚：什么任务值得做成 skill
不是所有任务都值得封装。我一开始热情很高，想把所有常用操作都做成 skill，结果做了一堆没人用的东西。后来总结出一个判断标准：高频、格式固定、容易出错这三个条件同时满足，才值得做。
高频意味着省时间；格式固定意味着有标准可循；容易出错意味着人工做的时候经常翻车。比如"把技术文档翻译成中文并保持术语一致"就符合这三条——我每周都要做，格式要求明确，术语翻译经常不统一。而"帮我查一下这个 API 怎么用"就不值得做，因为每次情况都不一样，封装了也没法复用。
3.2 拆解任务：把隐性知识显性化
这是最难的一步。你以为自己知道怎么做，但真要写下来，会发现很多步骤是"凭感觉"的。我的做法是：先手动做三遍同样的任务，每遍都记录下自己实际做了什么决策、依据是什么。三遍之后，重复出现的决策点就是 skill 需要固化的部分。
举个例子，我做"代码审查"这个 skill 的时候，第一遍记录发现我会先看命名规范，第二遍发现我会先看逻辑分支，第三遍才意识到我其实是先扫一遍整体结构再深入细节。这个"先整体后细节"的顺序就是隐性知识，不写下来 AI 根本不知道。
3.3 写描述文本：让 AI 知道什么时候该用它
skill 的描述文本决定了它能不能被正确触发。我见过太多人把描述写得像功能说明书，结果 AI 根本不知道什么场景该调用。好的描述应该包含三部分：触发场景、输入要求、输出预期。
比如我写的一个"周报生成"skill，描述是这样的：当用户提供零散的每日工作记录、要求整理成周报时使用；输入应为按日期排列的工作条目；输出为包含本周完成、下周计划、风险项三部分的结构化文本。这样写，AI 在遇到类似场景时就能准确匹配。
3.4 迭代：第一版一定是烂的
我做的第一个 skill 现在回头看简直没法用。但没关系，关键是先跑起来，然后在实际使用中发现问题。我的迭代节奏是：用一周，记录所有不满意的输出，周末集中改一次。通常改三轮之后，输出质量就稳定了。
这里有个经验：不要追求一次写完美。skill 的价值在于持续迭代，而不是一次成型。我见过有人花两周打磨一个 skill，结果实际用的时候发现场景根本不对，白费功夫。先做个能用的，再慢慢优化，这才是正确姿势。
4. 实测中那些让人抓狂的坑
4.1 触发不稳定：为什么有时候不生效
这是最高频的问题。同一个 skill，有时候触发得很准，有时候完全没反应。我排查了很久，发现原因主要有三个：描述文本太模糊、和已有 skill 的描述重叠、当前上下文和触发条件不匹配。
最隐蔽的是第二种。我有两个 skill，一个叫"整理会议记录"，一个叫"生成会议纪要"，描述写得太像，结果 AI 经常搞混。后来我把前者改成"把口语化的会议录音转写整理成要点"，后者改成"基于会议要点生成正式纪要文档"，区分度一下就上来了。
4.2 输出格式漂移：说好的结构呢
即使触发了，输出格式也可能和预期不一样。我遇到过最离谱的一次：要求输出 Markdown 表格，结果 AI 给我输出了一段散文。后来发现是描述里只说了"结构化输出"，没明确说"表格"。AI 对"结构化"的理解和我不一样。
解决办法是把格式要求写得极其具体。不要写"结构化输出"，要写"输出为三列表格，第一列是项目名，第二列是状态，第三列是负责人"。越具体，漂移越小。
4.3 跨平台失效：换了个环境就不认了
前面提过，Claude Code 和 Codex 的 skill 机制不一样。我一开始没注意，把 Claude Code 的 skill 直接放到 Codex 里，结果完全不触发。后来查了文档才知道，Codex 需要在 skill 里显式声明调用入口，而 Claude Code 更依赖语义匹配。
这个坑的教训是：跨平台复用前，先确认触发机制是否一致。如果不一致，要么改写，要么放弃复用。我现在的做法是，核心逻辑抽出来单独维护，各平台的适配层分开写，这样改一处逻辑不用改多个平台。
4.4 排查链路：我是怎么定位问题的
遇到 skill 不生效，我的排查顺序是这样的：
- 先确认 skill 文件是否被正确加载——有时候是路径问题，文件根本没被读到
- 再检查描述文本是否有歧义——把描述单独拿出来读一遍，看能不能明确判断触发场景
- 然后测试单独调用——绕过语义匹配，直接显式调用，看 skill 本身有没有问题
- 最后检查上下文冲突——看当前对话里有没有其他 skill 或指令在干扰
这个顺序帮我省了很多时间。以前我上来就改描述，改了半天发现是文件没加载，纯属白费功夫。
5. 让 skill 真正好用的几个关键设计
5.1 输入输出要像函数签名一样明确
我现在写 skill，第一件事就是定义输入和输出。输入是什么格式、包含哪些字段、哪些是必填哪些是可选；输出是什么结构、每个部分放什么内容、长度大概多少。定义清楚了，AI 执行起来就稳。
比如我写的一个"API 文档生成"skill，输入定义是：函数签名、参数说明、返回值说明、至少一个调用示例；输出定义是：包含功能描述、参数表格、返回值说明、示例代码四个部分的 Markdown 文档。这样定义之后，输出质量稳定了很多。
5.2 给示例比给规则更有效
我发现一个规律：与其写一堆规则，不如给一两个示例。AI 从示例里学到的模式，比从规则里推理出来的更准确。所以我现在每个 skill 里都会放至少一个输入输出示例。
这个发现是从一次失败中得来的。我写了一个"代码注释生成"skill，规则写了十几条，结果 AI 还是经常跑偏。后来我加了一个示例，展示什么样的代码对应什么样的注释，效果立刻好了很多。
5.3 边界情况要提前说明
什么情况下不该用这个 skill，什么情况下需要特殊处理，这些边界情况一定要写清楚。我吃过亏：一个 skill 在处理正常输入时表现很好，遇到空输入或者格式错误的输入就直接崩了。后来我在每个 skill 里都加了边界处理说明，稳定性提升明显。
5.4 版本管理不能省
skill 是要迭代的，迭代就需要版本管理。我的做法是每个 skill 文件里都带一个版本号和修改记录，改了什么、为什么改，都记下来。这样出问题的时候能快速回滚，也能看出哪些改动是有效的。
这个习惯是从一次事故里养成的。我改了一个 skill 的描述，结果触发率暴跌，但想不起来改之前是什么样，只能凭记忆恢复，折腾了很久。从那以后，每次改动都记录，再也没出现过这种问题。
6. 团队协作场景下的 skill 管理
6.1 共享 skill 库的目录结构
一个人用 skill 和团队用 skill 是两回事。团队用的时候，目录结构、命名规范、版本管理都要统一。我们团队现在的结构是这样的：按功能域分目录，每个 skill 一个文件夹，里面放主文件、示例、修改记录。命名统一用"功能域-具体任务"的格式，比如"doc-meeting-notes"。
这个结构不是一开始就定好的，是踩了很多坑之后慢慢收敛出来的。最开始大家各写各的，命名五花八门，找起来特别费劲。统一之后，新人上手快了很多。
6.2 评审机制：怎么保证 skill 质量
我们团队有个简单的评审机制：新 skill 或者重大修改，需要至少一个人 review。review 的重点不是代码风格，而是三件事：触发场景是否明确、输入输出是否清晰、边界情况是否覆盖。这三条过了，基本就能用。
评审机制刚推行的时候有人觉得麻烦，但后来大家都认可了。因为一个写得烂的 skill 被多人使用，浪费的是所有人的时间。评审花十分钟，省的是后面无数次的排查。
6.3 废弃机制：不用的 skill 要及时清理
skill 库会越来越大，不清理就会变成垃圾场。我们现在的做法是：每个 skill 记录最后使用时间，超过三个月没人用的，标记为待废弃，再过一个月还没人用就删掉。删之前会通知所有人，有人需要就保留。
这个机制帮我们保持 skill 库的精简。现在库里只有二十多个 skill，但每个都是真正常用的。比起之前上百个但大部分没人用的状态，效率高多了。
7. 我个人的一些实操心得
写了这么多，最后分享几个我自己的体会。第一个是不要贪多。我一开始想做一个万能 skill，什么任务都能处理，结果什么都不精。后来拆成多个专用 skill，每个只做一件事，反而好用得多。
第二个是描述文本要反复打磨。skill 能不能被正确触发，八成取决于描述文本。我现在的习惯是，写完描述之后放两天，再回来看，往往能发现表述不清的地方。
第三个是多记录失败案例。每次 skill 输出不符合预期，我都会记下来，分析是描述问题、示例问题还是边界问题。这些失败案例积累起来，就是改进 skill 的最好素材。
第四个是别怕重写。有些 skill 用了一段时间发现设计思路就不对，这时候不要修修补补，直接重写。我重写过好几个 skill，每次重写之后质量都有明显提升。修补只会让问题越积越多。
这套东西没有什么高深的理论，就是不断用、不断改、不断总结。用得多了，自然就有感觉了。
