1. 从skills这个热词说起它到底在解决什么问题最近一段时间不管是在开发者社区还是各种技术群里skills这个词出现的频率高得离谱。很多人第一次看到它会以为是某个新出的编程语言特性或者是某个框架里的功能模块。但如果你真的去翻一翻相关的讨论会发现大家嘴里的skills其实指向一个很具体的东西——给 AI 编程助手比如 Claude Code、Codex 这类工具扩展能力的插件化技能包。我最早接触这个概念的时候也走了弯路。当时我以为 skills 就是普通的插件装上去就能用。结果折腾了半天才发现它的设计思路和传统插件完全不是一回事。传统插件往往是往宿主程序里注入代码、挂载钩子而 skills 更像是一份给 AI 看的说明书——它用结构化的方式告诉 AI在什么场景下、该调用什么工具、按什么步骤执行、输出什么格式。这个区别非常关键直接决定了你写出来的 skill 到底能不能被正确触发。为什么这个东西会突然火起来我的判断是三个原因叠加。第一AI 编程助手已经过了能写代码就行的阶段大家开始要求它稳定、可控、可复用第二通用大模型在面对具体业务时总是差那么一口气而 skills 正好是补这口气的低成本手段第三社区里已经有人把好用的 skills 沉淀下来形成了事实上的技能市场后来者可以直接抄作业。这篇文章我想聊的不是某个具体 skill 怎么装而是把 skills 这套机制从底层逻辑到落地实操完整拆一遍。包括它和 plugin、agents 的关系怎么写一个能被稳定触发的 skill怎么在 Claude Code 和 Codex 里配置以及我在实际使用中踩过的那些坑。不管你是刚听说这个词的新手还是已经写过几个 skill 但总觉得触发不稳定的老手应该都能从里面找到点有用的东西。2. skills、plugin、agents 三者到底是什么关系很多人一上来就被这三个词绕晕了。我在群里见过不止一个人问skills 和 plugin 是不是一回事agents 又是什么要搞清楚这个得先理解它们各自在系统里扮演的角色。2.1 用公司来类比这三个概念我习惯用一个类比来解释把 AI 编程助手想象成一家公司。agents智能体是这家公司的员工。每个 agent 有自己的职责范围比如有的专门负责写前端组件有的专门负责排查后端 bug有的专门负责写测试。agent 是执行任务的主体它有自主决策的能力会根据当前情况选择下一步做什么。skills技能是员工脑子里的操作手册。一个 agent 可能掌握很多技能比如如何用 React 写一个表单如何用 pytest 组织测试用例如何做数据库迁移。skills 本身不主动执行它是被 agent 在需要的时候调用的知识包。plugin插件则是公司给员工配的工具和设备。比如给员工配一台更好的电脑、装一个专用的调试器、接一个外部的 API 服务。plugin 扩展的是 agent 的能力边界让它能接触到原本接触不到的东西。这个类比不一定百分百精确但能帮你快速建立直觉agent 是主体skill 是知识plugin 是工具。三者配合起来才能让 AI 助手在复杂任务里表现得像个靠谱的工程师而不是一个只会背代码的复读机。2.2 为什么 skills 是三者里最值得投入的从投入产出比来看我认为 skills 是普通开发者最应该花时间的地方。原因很简单写 plugin 门槛高。你得懂宿主程序的扩展机制要处理生命周期、依赖注入、版本兼容一不小心就把整个环境搞崩。调 agent 成本大。agent 的行为涉及提示词工程、工具编排、状态管理调不好就是看起来很智能实际上一团乱。写 skill 门槛低、收益直接。一个 skill 本质上就是一份结构化的 Markdown 加少量配置你只要把什么场景触发、按什么步骤做、注意什么写清楚就能显著提升 AI 在特定任务上的稳定性。我自己的经验是一个写得好的 skill能把某类任务的返工率从每次都要手动纠正降到基本一次过。这个提升是实打实的而且不需要你懂多少底层原理。2.3 三者的协作流程长什么样举个具体例子。假设你要让 AI 帮你把一个老项目的构建脚本从 Maven 迁移到 Gradle。agent 接到任务判断这属于构建系统迁移类别。agent 检索自己掌握的 skills发现有一个叫maven-to-gradle-migration的 skill 匹配当前场景。agent 加载这个 skill按照里面定义的步骤执行先分析现有 pom.xml 的依赖树再生成对应的 build.gradle然后处理插件差异最后跑一次构建验证。执行过程中如果需要读取远程仓库信息agent 调用对应的 plugin 去访问外部服务。整个过程结束后agent 根据 skill 里定义的输出格式给你一份迁移报告。你看skill 在这里起的是流程编排 知识注入的作用。它不直接干活但它决定了 agent 干活的方式和顺序。这就是为什么我说 skills 是最值得投入的一环——它直接决定了 AI 的输出质量。3. 一个 skill 的内部结构从触发条件到输出格式理解了定位接下来要拆的是 skill 本身长什么样。很多人写 skill 失败根本原因是没搞清楚一个 skill 到底由哪几部分组成导致写出来的东西要么触发不了要么触发了但执行得乱七八糟。3.1 skill 的四个核心组成部分根据我的实践一个能稳定工作的 skill 通常包含四个部分第一部分是元信息metadata。这部分定义了 skill 的名字、描述、适用场景、触发关键词。名字要短且有辨识度描述要能让 agent 快速判断这个 skill 是不是当前任务需要的。我见过很多人把描述写得特别笼统比如帮助处理代码相关任务这种描述等于没写agent 根本没法判断该不该用。第二部分是触发条件trigger。这部分明确告诉 agent当用户输入包含哪些特征时应该加载这个 skill。触发条件可以基于关键词、文件类型、任务类型甚至是上下文状态。写得越具体触发越精准。第三部分是执行步骤procedure。这是 skill 的主体用自然语言加结构化格式描述第一步做什么、第二步做什么。步骤要足够细细到 agent 不需要自己发挥就能照着做。但也不能太死板要留出应对异常情况的空间。第四部分是输出规范output spec。这部分定义 skill 执行完后应该产出什么。是生成一个文件还是输出一段报告格式是什么有没有必须包含的字段这部分经常被忽略但它直接决定了结果能不能被后续流程消费。3.2 触发条件为什么是最容易翻车的地方我踩过最大的坑就在触发条件上。早期我写了一个专门处理数据库索引优化的 skill描述写得很详细步骤也很完整。但实际用的时候发现十次里有七八次它根本不触发agent 直接用自己的通用知识去回答了。排查了很久才找到原因我的触发条件写得太学术了。我用的词是索引选择性分析查询计划优化这类术语但用户实际提问时说的是这个查询怎么这么慢数据库卡死了怎么办。触发词和实际输入对不上skill 自然就哑火了。后来我调整了策略在触发条件里同时包含三类词专业术语索引、执行计划、慢查询口语表达卡、慢、跑不动、等半天场景描述数据量大了之后、上线之后变慢调整完之后触发率明显上来了。这个经验告诉我触发条件要覆盖用户可能怎么说而不是你希望他怎么说。3.3 执行步骤的粒度怎么把握另一个常见问题是步骤粒度。写太粗agent 会自由发挥结果不可控写太细又变成了死板的脚本遇到一点变化就卡住。我的经验是采用目标 约束 示例的三层结构每一大步给出明确目标比如分析现有依赖冲突。给出约束条件比如优先保留直接依赖间接依赖可以升级。给一个具体示例比如如果 A 依赖 B 的 1.xC 依赖 B 的 2.x优先尝试统一到 2.x。这样 agent 既知道要干什么又知道边界在哪还能参考示例处理类似情况。比单纯列步骤要灵活得多。3.4 输出规范决定了 skill 能不能被复用输出规范这块我想多说两句。很多人写 skill 只关注能不能完成任务不关注输出能不能被下一步用。结果就是每次执行完还得人工整理一遍结果效率提升有限。一个好的输出规范应该包含要素说明示例格式输出是 Markdown、JSON 还是纯文本JSON必填字段哪些信息必须出现问题描述、根因、修复建议可选字段有则更好没有也不影响参考链接、相似案例长度限制避免输出过长或过短每个字段不超过 200 字把这张表填清楚你的 skill 输出就能直接被下游流程消费比如自动生成工单、自动发通知、自动归档。这才是 skill 真正的价值所在。4. 在 Claude Code 和 Codex 里落地 skills 的实操路径理论讲完了接下来是动手环节。这部分我会分别讲 Claude Code 和 Codex 两个环境下的配置方式以及一些通用的调试技巧。需要说明的是这两个工具都在快速迭代具体命令可能会变但核心思路是相通的。4.1 Claude Code 环境下的 skill 安装与配置Claude Code 对 skills 的支持相对成熟安装方式主要有两种。第一种是通过官方市场安装。如果你能访问官方市场直接搜索 skill 名字安装就行这是最省事的方式。安装完之后skill 会被放到用户配置目录下的 skills 文件夹里Claude Code 启动时会自动加载。第二种是手动放置。当你从社区拿到一个 skill 包或者自己写了一个可以手动放到对应目录。目录结构通常是这样的~/.claude/skills/ ├── my-skill/ │ ├── SKILL.md │ ├── config.json │ └── examples/ └── another-skill/ └── SKILL.md其中SKILL.md是核心文件里面就是前面说的元信息、触发条件、执行步骤、输出规范。config.json是可选的用来定义一些参数。examples/目录放示例输入输出帮助 agent 理解预期效果。放好之后重启 Claude Code用/skills之类的命令具体命令看版本查看已加载的 skill 列表确认你的 skill 出现在里面。注意手动放置 skill 时目录名和 SKILL.md 里定义的名字最好保持一致否则某些版本会出现加载了但识别不到的情况。我因为这个排查了半小时。4.2 Codex 环境下的 skill 接入Codex 这边的机制略有不同。它更强调 skill 和 agent 的绑定关系也就是说你需要先定义 agent再给 agent 挂载 skill。基本流程是这样的在 Codex 的配置目录下创建 agent 定义文件声明这个 agent 的职责范围。在 agent 定义里引用需要的 skill可以引用多个。启动 Codex 时指定使用哪个 agent对应的 skills 就会被加载。Codex 的一个好处是它对 skill 的版本管理比较友好你可以在配置里指定 skill 的版本号避免因为 skill 更新导致行为突变。这在团队协作场景下特别有用。另一个需要注意的是Codex 对 skill 的描述字段解析比较严格格式不对会直接报unrecognized configuration setting之类的错误。遇到这种报错先检查你的配置文件缩进和字段名八成是格式问题。4.3 本地模型接入时的 skill 适配有些朋友会用本地模型来跑 Claude Code 或 Codex这时候 skills 的适配会有点不一样。本地模型的上下文窗口通常比云端模型小所以 skill 里的步骤描述要更精简避免一次性塞太多内容导致截断。我的做法是把 skill 拆成核心步骤和扩展参考两部分核心步骤常驻上下文扩展参考按需加载。另外本地模型对结构化格式的遵循能力可能弱一些所以输出规范要写得更明确最好给出完整的输出示例让模型照着套。4.4 调试 skill 的通用方法不管你用哪个环境调试 skill 的思路是相通的。我总结了一个三步排查法第一步确认 skill 被加载了。查看 skill 列表确认你的 skill 在里面。如果不在检查目录位置和文件格式。第二步确认 skill 被触发了。在对话里输入一个明显应该触发该 skill 的问题观察 agent 的响应里有没有引用 skill 的迹象。如果没有问题出在触发条件上回去调整触发词。第三步确认 skill 执行正确。如果触发了但结果不对逐段检查执行步骤看是哪一步 agent 理解偏了。常见原因是步骤描述有歧义或者缺少异常处理分支。这三步走下来大部分问题都能定位。我见过有人一上来就怀疑是工具 bug折腾半天重装环境结果发现是 skill 里一个标点符号写错了导致解析失败。先做基础排查能省很多时间。5. 写一个高质量 skill 的实战心得前面讲的都是是什么和怎么配这一节我想聊聊怎么写好。这部分内容在官方文档里基本找不到都是我在实际写了几十个 skill 之后攒下来的经验。5.1 从我平时怎么做倒推 skill 结构写 skill 最好的起点不是打开编辑器而是回忆你自己做这件事的流程。比如你要写一个代码审查的 skill先别急着写拿一张纸把你平时审查代码时的步骤列出来先看改动范围大不大再看有没有明显的逻辑错误然后看命名和注释是否清晰接着看有没有遗漏的边界情况最后看测试覆盖够不够这个列表就是你 skill 执行步骤的雏形。因为这是你真实的工作流程所以它天然是合理的、可执行的。比凭空设计一套理想流程要靠谱得多。5.2 给 skill 加上止损点这是我踩坑之后学到的最重要的一课。早期我写的 skill 都是一路向前的假设所有条件都满足。结果遇到异常情况时agent 会硬着头皮往下走产出完全不可用的结果。后来我在每个关键步骤后面都加了止损点也就是明确告诉 agent如果出现某种情况就停下来报告问题不要继续。比如在依赖升级的 skill 里我会写如果升级后出现编译错误且错误涉及核心模块停止后续步骤输出错误详情和受影响的模块列表等待人工确认。这个止损点看起来简单但它把agent 自作主张搞出一堆问题变成了agent 发现问题及时上报。对于生产环境来说这个区别是致命的。5.3 用真实案例喂养 skillskill 里的示例部分一定要用真实案例不要编。我见过有人为了省事示例里写的是假设有一个函数 foo它做了 bar 操作这种占位内容。这种示例对 agent 几乎没有帮助因为它不包含真实世界的复杂性。我的做法是每写一个 skill就从自己过去的项目里找一个真实场景作为示例。包括真实的输入、真实的中间过程、真实的输出。这样 agent 在学习这个 skill 时接触到的是真实世界长什么样而不是教科书里长什么样。5.4 版本管理和迭代节奏skill 不是写完就完事的它需要持续迭代。我的建议是每个 skill 都带版本号放在元信息里。每次修改都记录变更原因哪怕只是一句话。定期回顾触发率如果某个 skill 长期不触发要么是触发条件有问题要么是这个 skill 根本不需要。我自己的 skills 目录里有一半以上的 skill 都经历过至少三次修改。第一次写出来能用第二次调整触发条件第三次补充异常处理。迭代是常态别指望一次写完美。6. 那些年我在 skills 上踩过的坑这一节专门讲踩坑因为我觉得这些经验比正面教程更有价值。下面这些坑有的是我自己踩的有的是帮别人排查时遇到的都是真实案例。6.1 触发词写得太聪明导致不触发前面提过一次这里再展开说。有个朋友写了一个API 文档生成的 skill触发词写的是OpenAPI 规范解析Swagger 注解提取这类专业词。结果用户实际提问是帮我把这些接口整理成文档完全不匹配skill 从来不触发。这个坑的本质是写 skill 的人和使用 skill 的人语言习惯往往不一样。写的人偏专业用的人偏口语。解决办法就是在触发词里同时覆盖两种表达甚至三种专业、口语、场景。6.2 步骤之间缺少状态传递这个坑比较隐蔽。我写过一个多步骤的 skill第一步分析问题第二步生成方案第三步验证方案。单独看每一步都没问题但连起来跑就出乱子——因为第二步不知道第一步分析出了什么第三步不知道第二步生成了什么。后来我在 skill 里显式定义了中间产物的概念要求每一步把结果写到指定的临时位置下一步从那里读取。这样步骤之间就有了明确的状态传递不会再各干各的。6.3 输出格式和下游不兼容有一次我写了一个日志分析的 skill输出是自然语言描述。结果下游的告警系统需要结构化数据根本没法消费。只能返工把输出改成 JSON。这个坑的教训是写 skill 之前先想清楚输出给谁用。如果只是给人看自然语言没问题如果要给系统消费就必须结构化。别等到写完了才发现格式不对。6.4 忽略权限和边界有些 skill 会涉及文件读写、命令执行这类操作。如果不明确声明权限边界agent 可能会做出超出预期的操作。我见过一个 skill 因为没限制写入范围结果把用户的项目文件覆盖了。所以涉及副作用的 skill一定要在配置里明确声明能读哪些目录、能写哪些目录、能执行哪些命令。宁可限制得严一点也不要留隐患。6.5 在错误的层级解决问题最后一个坑比较抽象但很重要。有些人遇到 AI 输出不稳定第一反应是去调 agent 的提示词或者换模型。但实际上很多问题的根源在 skill 层面——是 skill 的步骤描述有歧义或者触发条件不清晰。我的经验是先检查 skill再检查 agent最后才考虑换模型。因为 skill 是最容易改、改动成本最低的一层。把这一层做扎实了很多问题自然就消失了。7. 关于 skills 的一些延伸思考写到这里核心内容基本讲完了。最后我想聊几个延伸话题算是给这个领域再补一点视角。7.1 skills 会不会成为新的技术债我有个担忧随着 skills 越来越多会不会出现skill 泛滥的问题就像当年 npm 包一样一开始大家觉得方便后来发现依赖树深不见底维护成本高得吓人。我的建议是对 skills 也要有断舍离的意识。定期清理不再使用的 skill合并功能重叠的 skill保持 skill 库的精简。一个只有二十个高质量 skill 的库比一个有两百个半成品 skill 的库要有价值得多。7.2 团队协作下的 skill 管理如果是团队使用skills 的管理就更重要了。我的做法是建立一个共享的 skill 仓库所有人从这里取用。每个 skill 有明确的负责人负责维护和更新。定期做 skill 评审淘汰低质量的推广高质量的。建立 skill 使用反馈机制用的人可以提改进建议。这样 skills 就从个人收藏变成了团队资产价值会放大很多。7.3 从 skills 看 AI 工具的未来形态我个人的判断是未来的 AI 编程工具会越来越像操作系统而 skills 就是上面的应用程序。操作系统提供基础能力应用程序解决具体问题。谁掌握了高质量的 skills谁就能让 AI 工具发挥出更大的价值。这个趋势对普通开发者来说其实是好事。因为写 skill 不需要你懂多深的底层原理只需要你对自己的工作流程足够熟悉。把熟悉的事情结构化地表达出来这就是 skill 的核心。门槛不高但天花板很高。我在实际使用中最大的体会是skills 的价值不在于它多智能而在于它多稳定。一个能稳定触发、稳定执行、稳定输出的 skill比一个偶尔惊艳但经常翻车的 skill 要有用得多。追求稳定而不是追求炫技这是我写了几十个 skill 之后最想分享的一句话。如果你刚开始接触 skills我的建议是从一个小场景入手写一个最简单的 skill跑通整个流程然后再逐步扩展。别一上来就想着写一个万能 skill那基本不可能成功。从一个具体问题开始解决它然后再解决下一个。这个过程本身就是最好的学习。