1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会懵。它太泛了泛到像是随手敲的一个占位符。但结合热搜词里高频出现的 Claude Code、Codex、agents、plugin 这些词方向其实很明确——这里说的 skills指的是 AI 编程助手尤其是 Claude Code、Codex 这类 agent 工具里的技能扩展机制也就是让 agent 在基础能力之外按需加载特定领域知识、工具调用流程、操作规范的一套模块化方案。打个比方。基础的大模型 agent 就像一个刚入职的聪明应届生脑子好使但对你们公司的代码规范、部署流程、内部工具链一无所知。skills 就是给他的一本本岗位操作手册——遇到写数据库迁移的时候翻哪本遇到排查线上日志的时候翻哪本遇到前端组件规范的时候翻哪本。手册不是一次性全塞给他而是按需触发、按需加载这样既不撑爆上下文窗口又能保证在具体任务上足够专业。这套机制解决的核心痛点有三个。第一是上下文经济性一个 agent 的上下文窗口再大也是有限的把所有领域知识一股脑塞进 system prompt既浪费 token 又稀释注意力。skills 把知识拆成独立模块只在相关任务出现时才注入。第二是可复用性一个团队沉淀下来的最佳实践可以打包成 skill 在成员之间共享不用每个人重新踩坑。第三是可维护性某个流程变了只改对应的 skill 文件不用动整个 agent 配置。适合读这篇内容的人我大致分三类。一类是已经在用 Claude Code 或 Codex 做日常开发但还停留在对话式问答阶段没意识到可以给它装技能包的开发者。一类是想给团队搭建统一 AI 辅助工作流的 tech lead需要知道 skills 怎么组织、怎么分发。还有一类是纯粹好奇 agent 扩展机制原理的技术爱好者想搞清楚skills 和 plugin 到底啥区别。需要先说明一点skills 这个概念在不同工具里的实现细节不完全一样。Claude Code 有它自己的一套 skill 目录约定Codex 的扩展方式又有所不同社区里还有各种第三方封装的 skills 市场。下面我尽量讲通用的机制和思路具体到某个工具时会点明差异。所有涉及具体配置的部分都是基于常见实践的合理还原你实际用的时候以官方文档为准。2. skills 与 plugin、agent 的边界别把三个概念搅在一起热搜词里 skills、plugin、agents 三个词经常一起出现很多人第一次接触会以为是一回事。实际上它们处在不同的抽象层级搞清楚这个层级关系后面配置的时候才不会乱。2.1 三者的职责划分我用一个不太严谨但好记的类比agent 是员工plugin 是员工能用的外部工具skill 是员工脑子里的操作手册。agent 是执行主体它负责理解你的意图、规划步骤、决定调用什么。plugin 是能力扩展通常对应一个具体的外部接口或工具——比如读文件、跑命令、查数据库、调某个 API。skill 则是知识扩展它不直接提供新能力而是告诉 agent在什么场景下、按什么顺序、用哪些 plugin、注意哪些坑。举个具体例子。你要 agent 帮你做一次数据库 schema 变更。plugin 层面它需要执行 SQL和读文件这两个工具。skill 层面它需要知道先备份、再在事务里执行、变更前检查是否有长事务锁表、变更后验证索引是否生效。这些步骤不是 plugin 能提供的是知识是经验是 skill 该装的东西。维度agentpluginskill抽象层级执行主体能力接口知识模块解决什么理解意图、规划提供外部操作能力提供领域流程与规范典型形态一个配置好的助手实例一个工具函数/API 封装一个 Markdown 或结构化文件是否消耗上下文是对话历史按需工具描述按需触发时注入谁维护使用者/团队工具开发者领域专家/团队2.2 为什么 skill 要独立于 plugin 存在有人会问既然 skill 就是一堆操作步骤为什么不直接写进 plugin 的描述里或者干脆写进 agent 的 system prompt写进 plugin 描述的问题在于plugin 是通用的一个执行 SQL的工具不该内置我们公司的变更规范。工具要保持中立规范要独立可替换。写进 system prompt 的问题更明显system prompt 是常驻的每次对话都占上下文而你不可能同时需要前端规范、后端规范、运维规范、数据规范——大部分时候只需要其中一个。skill 的按需加载正好解决这个矛盾。这也是为什么 skills 机制在 Claude Code 这类工具里被设计成目录扫描 描述匹配的模式agent 启动时只读取每个 skill 的简短描述name description判断当前任务和哪个 skill 相关相关才把完整内容读进来。这个设计思路和 RAG 的检索增强很像只不过检索的是本地文件触发靠的是模型自己的判断而不是向量相似度。2.3 一个容易踩的认知坑我见过不少人把 skill 当成提示词模板来用写了一大段你是一个资深 XX 工程师请遵循以下规范……。这样写不是不行但浪费了 skill 机制最大的价值——触发条件。好的 skill 应该有一个清晰的什么时候用我的描述。比如当用户要求进行数据库 schema 变更、迁移脚本编写或索引调整时使用本技能而不是本技能包含数据库相关知识。前者让 agent 能准确判断该不该加载后者会让 agent 要么漏加载、要么乱加载。这个细节后面讲编写规范时还会展开。3. 一个 skill 文件里到底该写什么理解了定位接下来是实操。一个 skill 文件的结构直接决定了它好不好用、会不会被正确触发。我按重要性从高到低拆。3.1 元信息name 和 description 是命门几乎所有 skills 实现都要求每个 skill 有一个名字和一段描述。这两个字段是 agent 决定要不要加载这个 skill的唯一依据所以它们的重要性远超正文。name 要短、要具体、要能一眼看出领域。db-migration比database好react-component-style比frontend好。避免用utils、helpers、misc这种一看就不知道干嘛的名字。description 的写法有个实用套路当……时使用本技能它包含……。前半句写触发场景后半句写能力范围。举几个我实际用下来触发比较准的例子当需要编写或审查数据库迁移脚本时使用包含变更前检查清单、事务边界规范、回滚方案模板。当处理 React 组件的样式组织、命名和目录结构时使用包含团队约定的 CSS 方案选型与组件拆分原则。当排查线上服务超时、连接池耗尽或慢查询时使用包含分层排查顺序和常用诊断命令。注意这些描述都带了明确的动作词编写、审查、处理、排查因为 agent 判断相关性时任务里的动词是强信号。如果你的 description 全是名词堆砌触发率会明显下降。3.2 正文流程、检查清单、反例正文部分我建议按流程 检查清单 反例三段式来组织这是从实际使用中总结出来的比单纯罗列知识点有效得多。流程部分写第一步做什么、第二步做什么最好带上判断分支。比如数据库迁移的 skill流程可能是先确认变更类型加字段/改类型/加索引→ 不同类型走不同检查项 → 生成脚本 → 本地验证 → 提交。agent 拿到这个流程执行起来就有章法不会东一榔头西一棒子。检查清单部分写做完之后必须确认的事。这部分用无序列表最合适每条一个可验证的点。比如确认迁移脚本在空库和存量库上都能跑通确认回滚脚本已同步编写确认变更期间没有长事务。清单的价值在于它把隐性经验显性化了新人包括 AI照着勾就行。反例部分最容易被忽略但恰恰最有价值。写清楚不要这样做以及为什么。比如不要在业务高峰期执行大表 DDL因为会锁表导致请求堆积不要在迁移脚本里混入数据修复逻辑因为回滚时会出问题。反例能帮 agent 避开那些它凭常识想不到的坑。3.3 一个可参考的 skill 文件骨架下面这个骨架是我自己常用的你可以直接拿去改。注意这是通用结构具体到 Claude Code 或 Codex 时字段名可能略有差异。--- name: db-migration description: 当需要编写或审查数据库迁移脚本时使用包含变更前检查清单、事务边界规范、回滚方案模板。 --- ## 适用场景 - 新增/修改/删除表字段 - 新增/删除索引 - 数据回填脚本 ## 执行流程 1. 确认变更类型判断是否属于大表 DDL 2. 大表 DDL 走在线变更工具小表可直接执行 3. 编写正向脚本与回滚脚本 4. 在预发环境验证 5. 提交并附上变更说明 ## 检查清单 - [ ] 回滚脚本已编写并验证 - [ ] 变更期间无长事务 - [ ] 索引变更评估过对写入的影响 - [ ] 脚本幂等可重复执行 ## 反例 - 不要在迁移脚本里混入业务数据修复 - 不要省略回滚脚本哪怕这次肯定不回滚 - 不要在业务高峰期执行大表 DDL这个骨架的关键在于元信息精准、流程可执行、清单可验证、反例有理由。四样齐了一个 skill 基本就立住了。4. 让 skill 真正被触发几个反直觉的细节写完 skill 只是第一步能不能被 agent 在对的时候加载进来是另一回事。这块我踩过的坑最多单独拎出来讲。4.1 描述写太宽反而不会被触发直觉上description 写得越宽泛覆盖的场景越多触发率应该越高。实际恰恰相反。如果你写当处理任何编程相关任务时使用agent 会觉得这个 skill 太泛反而倾向于不加载——因为它判断不出这个 skill 相比它自己的通用能力有什么增量。正确的做法是收窄。宁可写五个精准的小 skill也不要写一个包罗万象的大 skill。精准的描述让 agent 的匹配判断更果断。我做过对比把一个大而全的后端开发规范拆成API 设计规范错误码规范日志规范三个独立 skill 之后每个的触发准确率都明显上升。4.2 触发词要贴近任务里的自然语言agent 判断相关性靠的是把当前任务描述和 skill description 做语义匹配。所以 description 里应该包含用户实际会说的词。比如你的 skill 是关于接口幂等性设计的如果 description 只写幂等性用户说这个下单接口重复提交怎么办的时候可能匹配不上。加上重复提交防重去重这些同义表达命中率就上来了。这不是让你堆关键词而是把领域里常见的说法覆盖到。4.3 多个 skill 冲突时怎么办当两个 skill 的适用范围有重叠agent 可能同时加载也可能只加载一个行为不太确定。我的处理原则是在 description 里显式划清边界。比如数据库迁移和数据库性能优化两个 skill前者 description 里加一句本技能不涉及查询性能调优那属于性能优化范畴后者加一句本技能不涉及 schema 变更那属于迁移范畴。这样 agent 遇到边界任务时能做出更清晰的选择。如果确实有共享内容抽出来做成第三个基础 skill让前两个引用它。不过要注意skill 之间的引用机制在不同工具里支持程度不一样有些工具不支持 skill 互相引用那就只能接受一定程度的重复或者把共享内容放进一个更基础的 skill 里靠触发顺序解决。4.4 验证触发是否正常写完 skill 别急着用先做几个测试。我通常准备三组测试用例一组是应该触发的明确属于该领域一组是不应该触发的相邻领域一组是边界模糊的可触发可不触发。然后观察 agent 的实际行为。如果该触发没触发多半是 description 的触发词不够贴近如果不该触发却触发了多半是 description 写太宽。这个测试过程有点像调 prompt需要迭代几轮。别嫌麻烦一个触发不准的 skill 比没有 skill 还糟——它会在错误的时机注入错误的知识把 agent 带偏。5. 团队场景下 skills 的组织与分发个人用 skills随便放放就行。团队用就得考虑组织结构和分发机制否则很快会乱成一锅粥。5.1 目录结构怎么设计我推荐按领域/子领域两级来分不要超过三级。比如skills/ backend/ api-design/ error-code/ logging/ frontend/ component-style/ state-management/ ops/ incident-response/ db-migration/每个叶子目录里放一个 skill 文件或一组相关文件。这样结构清晰agent 扫描时也容易按目录归类。避免把所有 skill 平铺在一个目录里几十个文件堆一起维护起来很痛苦。5.2 版本管理与变更流程skills 本质上是团队知识资产应该和代码一样纳入版本管理。我建议单独开一个仓库或者放在主仓库的一个独立目录下走正常的 PR 流程。变更流程上我见过两种做法。一种是宽松制谁都能改改完直接合并。另一种是评审制涉及核心流程的 skill 变更需要领域 owner 审核。我的经验是涉及安全、数据、线上操作的 skill 必须走评审其他可以宽松。因为这类 skill 一旦写错agent 照着执行可能造成实际损失。另外建议给每个 skill 加一个最后更新日期和维护人字段可以放在文件头部注释里。时间久了你能一眼看出哪些 skill 可能已经过时。5.3 分发方式的选择团队分发 skills 有几种常见方式各有取舍。方式优点缺点适用场景共享仓库 手动同步简单直接容易版本不一致小团队、skill 少打包成内部包分发版本可控需要额外打包流程中大型团队放在共享目录软链接实时同步依赖网络/挂载内网环境通过工具自带的 skill 市场安装方便受平台限制用官方生态我个人偏向共享仓库 定期同步。简单、透明、出问题好排查。软链接方式看着优雅但一旦挂载出问题agent 会静默地加载不到 skill排查起来很费劲。5.4 一个团队协作的实操心得团队用 skills 最容易出的问题不是技术问题是没人维护。一开始大家热情很高写了一批 skill半年后流程变了skill 还是老的agent 照着老流程执行反而添乱。我的应对办法是把 skill 维护和现有的流程文档维护绑定。也就是说任何流程变更改文档的同时必须改对应的 skill写进团队的 definition of done 里。这样 skill 不会变成孤儿资产。另外每隔一个季度做一次 skill 盘点把没人用的、过时的清理掉。宁可少而精不要多而烂。6. 常见故障与排查从加载不上到触发错乱用 skills 的过程中会遇到各种问题我把高频的几类整理出来附上排查思路。这些大多是我自己或身边人实际遇到过的。6.1 skill 完全没被加载现象是 agent 的行为和没装 skill 时一模一样。排查顺序确认文件位置对不对。不同工具对 skill 目录的位置要求不同有的要求放在项目根目录的特定子目录有的要求放在用户主目录。位置错了扫描不到。确认文件格式对不对。元信息字段名写错、YAML 头格式错误、编码问题都会导致解析失败。用一个最简单的 skill 做对照测试。确认工具版本支持。skills 机制是较新引入的老版本可能不支持。查一下版本。看日志。大多数工具在加载 skill 失败时会打日志只是默认级别可能看不到。把日志级别调高再试。6.2 skill 被加载了但没起作用现象是 agent 似乎知道有这个 skill但执行时没按 skill 里的流程走。可能原因skill 内容太长被截断。有些工具对单个 skill 的注入长度有限制超长部分会被丢弃。把 skill 拆小。skill 内容和 agent 的通用能力冲突。比如 skill 里写的流程和模型训练时学到的常识矛盾模型可能更信自己的常识。这种情况要在 skill 里显式说明即使与通用做法不同也请遵循本流程并给出理由。指令不够具体。skill 里写注意性能模型不知道具体注意什么。改成查询必须走索引禁止全表扫描这种可执行的指令。6.3 触发时机不对该触发的时候不触发或者不该触发的时候乱触发。前面 4.1 到 4.3 讲了一些这里补充一个排查工具把 agent 的思考过程打开如果工具支持。看它在判断相关性时是怎么想的往往能直接定位问题。如果看不到思考过程就用二分法把 skill 的 description 逐步简化看哪个版本开始触发正常反推是哪个词导致的误判。6.4 多个 skill 互相干扰现象是加载了 A 和 B 两个 skill 后agent 的行为变得混乱两边的要求都执行了一半。这通常是因为两个 skill 对同一件事给了不同指令。解决办法是在 skill 里明确优先级或者干脆合并。我倾向于合并——如果两个 skill 经常同时被触发且内容有冲突说明它们本来就不该分开。分开的唯一理由是它们各自有独立的触发场景如果场景总是重叠分开就是自找麻烦。提示排查 skill 问题时先用一个最小可复现的例子。把无关 skill 全部移走只留一个确认它单独工作正常再逐个加回来。这样能快速定位是哪个 skill 引入的问题。7. 我对 skills 这套机制的实际体会用了一段时间 skills 之后我最大的感受是它的价值不在于让 agent 更聪明而在于让 agent 更可控。基础模型的能力已经很强了很多时候它给出的方案大方向是对的。问题出在细节——不符合团队规范、忽略了某个边界条件、用了已经废弃的 API。skills 的作用就是把这些团队特有的、模型不可能知道的细节固化下来让 agent 的输出从大致能用变成直接能用。另一个体会是写 skill 的过程本身就是在梳理团队知识。很多流程平时大家凭肌肉记忆在做真要写下来才发现有歧义、有遗漏。写 skill 逼着团队把这些隐性知识显性化这个副产品可能比 skill 本身还有价值。至于投入产出我的判断是高频、易错、有明确规范的领域最值得写 skill。比如数据库变更、线上发布、安全相关的操作。低频的、一次性的任务写 skill 的性价比不高直接对话解决就行。别为了用 skills 而用 skills工具是拿来解决问题的不是拿来供着的。最后分享一个小技巧新写一个 skill 之后别只看它能不能用要看它在什么情况下会误用。故意用一些边界任务去试探它看 agent 会不会在不该加载的时候加载。一个 skill 的鲁棒性往往体现在它知道什么时候不该出现。这个测试习惯帮我避免了好几次线上事故——有次一个关于批量数据操作的 skill在测试时发现它会被删除单条记录这种任务误触发如果没测出来后果不堪设想。