agent-skills：给AI编码代理装上可复用的技能包

1. 从“agent-skills”说起：为什么我们需要给AI编码代理装上技能包

第一次看到agent-skills这个项目名，我脑子里蹦出来的不是某个具体工具，而是一个很现实的问题：我们花在配置AI编码代理上的时间，是不是已经超过了它帮我们省下的时间？Claude Code、各类AI coding agents 现在确实能写代码、能跑终端命令、能改文件，但每次换项目、换语言、换团队规范，你都得重新告诉它一遍“我们这边测试怎么写”“提交信息什么格式”“哪些目录不能碰”。这种重复劳动，本质上不是模型能力问题，而是技能没有沉淀。

agent-skills要解决的就是这件事。它把“怎么让AI代理按你的规矩干活”这件事，从每次对话里的口头交代，变成一套可版本化、可复用、可组合的技能文件。你可以把它理解成给AI代理准备的“员工手册+操作SOP”，代理在执行任务时按需加载对应技能，而不是靠你每次现场教学。这个项目适合谁？如果你已经在用 Claude Code 或者类似的AI coding agents，并且开始觉得“每次都要重复交代同一件事很烦”，那它就是给你准备的。如果你还没入门，只是想看看AI编码代理到底怎么落地，那也可以把它当成一个理解“代理技能体系”的入口。

我最初接触这类方案时，最大的疑问是：为什么不直接把规范写进CLAUDE.md或者系统提示词里？后来踩过几次坑才明白，单一提示词文件会随着项目复杂度膨胀，最后变成几千行的“什么都说了等于什么都没说”。agent-skills的思路是把技能拆开，按场景触发，这跟我们在工程里做模块化是一个道理。下面我就按自己实际折腾的过程，把这个项目的设计思路、核心细节、实操流程和踩坑经验完整拆一遍。

2. 内容整体设计与思路拆解

2.1 核心问题：AI代理的“上下文污染”与“规范漂移”

在深入agent-skills之前，得先搞清楚它要对付的两个敌人。第一个是上下文污染。当你把测试规范、提交规范、代码风格、部署流程全部塞进一个系统提示词里，代理每次任务都要带着这一大坨上下文跑。结果是 token 消耗高不说，模型注意力还被稀释，真正跟当前任务相关的规范反而被淹没。我实测过一个中等规模项目，把全部规范塞进单一提示词后，代理在写单元测试时经常忘记“用 table-driven 风格”，因为那段说明被埋在了几百行之外。

第二个是规范漂移。团队规范是会变的，今天用 Jest，明天可能换 Vitest；今天提交信息用中文，明天要求英文。如果规范散落在各个对话历史里，你根本不知道代理当前遵循的是哪个版本。agent-skills把技能做成独立文件，每个技能有自己的触发条件和内容，变更时只改对应文件，代理加载的就是最新版。这个设计跟基础设施即代码的思路一致：规范也要可版本控制。

2.2 方案选型：为什么是“技能文件”而不是“插件”或“微调”

市面上让AI代理定制化的路子大概有三条：插件、微调、技能文件。插件能力强但开发成本高，适合平台级扩展；微调成本更高，而且规范一变就得重新训练，完全不现实。技能文件是折中方案：纯文本、易编辑、零构建、代理运行时按需读取。agent-skills选的就是这条路。

它的优势在于低门槛和高灵活性。你不需要写代码，只要会写 Markdown 就能定义技能。技能之间可以组合，比如“写测试”技能可以引用“项目结构”技能来定位测试目录。这种组合能力让技能体系能随项目成长而生长，而不是一开始就设计一个大而全的框架。我个人的判断是，对于大多数团队，技能文件是投入产出比最高的方案，除非你有非常特殊的运行时需求，否则没必要上插件。

2.3 技能的生命周期：定义、触发、执行、反馈

一个技能从被定义到被代理使用，走的是这样一条链路：你先在技能目录里写一个技能文件，声明它的名称、描述和触发条件；代理在接到任务时，根据任务描述匹配技能；匹配成功后加载技能内容到当前上下文；代理按技能里的步骤执行；执行结果如果不符合预期，你再回来改技能文件。这个闭环里最关键的是触发条件的设计，写得太宽会导致技能被滥用，写得太窄又会在需要时匹配不上。我后面会专门讲怎么调这个。

3. 核心细节解析与实操要点

3.1 技能文件的结构：名称、描述、触发词、正文

一个典型的技能文件长这样：顶部是元信息，包括技能名称、一句话描述、触发关键词列表；下面是正文，用自然语言写清楚“什么时候用这个技能”“具体步骤是什么”“有哪些注意事项”。这里有个容易踩的坑：很多人把触发词写得特别泛，比如只写“测试”，结果代理在任何跟测试沾边的任务里都加载这个技能，包括“解释这段测试代码”这种根本不需要执行测试规范的任务。我的经验是触发词要尽量具体，最好带上动作，比如“写单元测试”“新增测试用例”“修复失败测试”。

正文部分我建议按“目标—步骤—检查点”来组织。目标说清楚这个技能要达成什么；步骤是可执行的指令，最好带具体命令或文件路径；检查点是代理执行完后的自检项，比如“确认测试文件放在__tests__目录下”。检查点这个设计很关键，它让代理在完成任务后有个自我验证的环节，减少“看起来做完了其实没做对”的情况。

3.2 触发机制：代理怎么知道该用哪个技能

agent-skills的触发机制通常是基于任务描述的关键词匹配，有些实现还会结合语义相似度。这里有个实操要点：触发词要覆盖同义表达。比如你的团队既说“单测”也说“单元测试”，那触发词里两个都要有。我见过一个案例，技能只写了“unit test”，结果中文任务描述“给这个函数补个单测”完全匹配不上，代理就没加载技能，写出来的测试风格跟团队规范不一致。

另一个要点是技能优先级。当多个技能同时匹配时，得有优先级规则。常见做法是更具体的技能优先，比如“React 组件测试”优先于“通用测试”。这个优先级可以在技能元信息里声明，也可以靠触发词的精确度自然区分。我倾向于显式声明，因为隐式规则在技能多了之后很难维护。

3.3 技能的组合与引用：避免重复定义

技能之间可以互相引用，这是减少重复的关键。比如“写测试”技能里需要知道测试文件放哪，这个信息可以放在“项目结构”技能里，然后“写测试”技能引用它。引用方式一般是在正文里写明“参见项目结构技能”，代理加载时会一并处理。但要注意引用深度，我建议最多两层，再深就容易出现循环引用或者加载顺序问题。实测下来，两层引用能覆盖绝大多数场景，三层以上就该考虑合并技能了。

3.4 与 Claude Code 等代理的集成方式

agent-skills本身是技能定义，要真正用起来得跟具体的AI coding agent 集成。以 Claude Code 为例，通常是在项目根目录放一个技能目录，然后在代理配置里指向这个目录。代理启动时会扫描技能目录，建立索引。任务来了之后，代理先做技能匹配，再加载匹配到的技能内容。这里有个细节：技能目录的位置要跟项目绑定，不要放在全局配置里，否则不同项目的技能会互相干扰。我一般放在项目根目录的.agent-skills/下，跟.git平级，这样技能文件也能跟着项目一起版本控制。

4. 实操过程与核心环节实现

4.1 环境准备：从零搭起技能目录

假设你已经在用 Claude Code，第一步是在项目根目录建技能目录。我习惯用.agent-skills/，因为点开头目录在大多数编辑器里默认折叠，不会干扰日常浏览。目录建好后，里面每个技能一个 Markdown 文件，文件名用技能名，比如write-unit-test.md。这里有个小技巧：文件名用英文短横线连接，正文里可以用中文，这样既保证兼容性又方便阅读。

接下来要在代理配置里声明技能目录。不同代理配置方式不一样，Claude Code 一般是在项目配置里加一行指向技能目录的路径。配置完重启代理，让它扫描一遍。你可以用一个简单任务测试，比如“帮我写个函数”，看代理有没有加载相关技能。如果没加载，先检查路径对不对，再检查技能文件的触发词是否匹配任务描述。

4.2 编写第一个技能：以“测试驱动开发”为例

测试驱动开发（TDD）是个很好的入门技能，因为它流程明确、检查点清晰。我写这个技能时，正文大致是这样的：目标是“按 TDD 流程实现新功能”；步骤是“先写失败测试—运行确认失败—写最小实现—运行确认通过—重构”；检查点是“测试文件命名符合规范”“测试覆盖了边界条件”“重构后所有测试仍通过”。触发词我设了“TDD”“测试驱动”“先写测试”“红绿重构”这几个。

写完后我拿一个真实任务试了一下，让代理“用 TDD 方式实现一个字符串截断函数”。代理确实先写了测试，但测试里只覆盖了正常情况，没覆盖空字符串和超长字符串。我回去在技能的检查点里加了一条“必须覆盖空值、边界值和异常输入”，再试就对了。这个迭代过程说明技能不是一次写好的，得在实际任务里磨。

4.3 技能加载的验证：怎么确认代理真的用了技能

验证技能是否生效，最直接的方法是看代理的输出里有没有体现技能里的规范。比如技能里要求测试文件放在__tests__目录，那代理创建的文件就应该在那个目录下。如果没体现，可能是技能没加载，也可能是加载了但代理没遵守。区分这两种情况的办法是看代理的思考过程（如果代理暴露的话），或者临时在技能里加一句显眼的指令，比如“在回复开头写‘已加载测试技能’”，看代理有没有照做。

我一般还会做一个负面测试：故意给一个不该触发技能的任务，比如“解释这段测试代码的作用”，看代理会不会错误加载写测试的技能。如果加载了，说明触发词太宽，得收紧。这个正反测试做完，基本能确认技能触发机制是可靠的。

4.4 多技能协同：一个完整功能的实现流程

真实任务往往需要多个技能协同。比如“给用户模块加一个邮箱验证功能”，可能涉及“写测试”技能、“项目结构”技能、“提交规范”技能。代理会先匹配到“写测试”和“项目结构”，执行完测试和实现后，提交时再匹配“提交规范”。这里要注意技能加载顺序，一般按任务阶段自然排序，测试技能在前，提交技能在后。如果顺序乱了，比如先加载提交规范再写代码，代理可能会在代码还没写完时就想着提交，导致流程混乱。

我实测下来，多技能协同的关键是每个技能只负责一个阶段，不要在一个技能里既写测试又管提交。技能粒度细了，组合才灵活。当然也不能太细，细到每个函数一个技能就过度了。我的经验是技能粒度对齐“任务阶段”，一个阶段一个技能，这样最平衡。

5. 常见问题与排查技巧实录

5.1 技能不触发：从触发词到加载路径的排查清单

技能不触发是最常见的问题，排查顺序我一般是这样：先看任务描述里有没有触发词，没有就加上或者换种说法；再看技能文件路径对不对，代理配置里指向的目录是否包含这个文件；然后看技能文件格式有没有问题，比如元信息缺了必填字段；最后看代理版本是否支持技能加载。这个顺序能覆盖九成以上的不触发问题。

有个隐蔽的坑是编码问题。如果技能文件用了非 UTF-8 编码，代理读取时可能乱码，导致触发词匹配失败。我遇到过一回，技能文件在 Windows 上编辑后保存成了 GBK，代理死活不加载，换成 UTF-8 就好了。所以技能文件统一用 UTF-8，这个要写进团队规范。

5.2 技能冲突：多个技能同时匹配怎么办

多个技能同时匹配时，如果它们对同一件事有不同要求，就会冲突。比如“写测试”技能要求测试文件放__tests__，“项目结构”技能要求放test/，代理就懵了。解决办法是建立单一事实来源：测试目录这种信息只在一个技能里定义，其他技能引用它。如果确实需要覆盖，就在更具体的技能里显式声明“本技能优先于通用技能”，并说明覆盖原因。

我建议定期做一次技能审计，把所有技能过一遍，看有没有重复定义或矛盾的地方。技能多了之后，这种审计很有必要，我一般一个月做一次，每次都能发现几处需要合并或删除的技能。

5.3 技能膨胀：什么时候该拆分，什么时候该合并

技能写多了会膨胀，写少了又不够用。判断标准是技能是否还在单一职责内。如果一个技能里出现了“如果 A 情况这样做，如果 B 情况那样做”的大段分支，就该拆了。反过来，如果两个技能总是一起被触发，而且内容高度相关，就该合并。我自己的经验值是单个技能正文控制在 200 行以内，超过就考虑拆。这个数字不是硬性的，但超过之后维护成本明显上升。

5.4 与代理版本升级的兼容性

AI coding agents 更新很快，技能格式和加载机制可能变。我踩过的坑是代理升级后技能目录的默认路径变了，导致所有技能都不加载。解决办法是把技能目录路径写进项目配置并提交到版本控制，这样升级后配置还在，不容易丢。另外升级后要跑一遍技能验证，确认触发和加载都正常。我一般会在升级后拿一个标准任务测一下，比如“写个带测试的函数”，看输出是否符合技能规范。

5.5 独家避坑：技能文件也要做 Code Review

这一点很多团队会忽略：技能文件是给代理看的规范，规范错了代理就跟着错。所以技能文件变更也应该走 Code Review，至少让团队里另一个人看一眼。我见过一个案例，有人在技能里把测试命令写错了，结果代理每次跑测试都失败，排查了半天才发现是技能文件的问题。把技能文件当代码对待，这个习惯能省很多事。

6. 技能体系的扩展与团队落地

6.1 从个人技能到团队技能库

个人用技能和团队用技能是两回事。个人用可以随意，团队用就得考虑一致性。我的做法是建一个团队技能库仓库，每个人贡献的技能先提 PR，Review 通过后合并。技能库里按领域分目录，比如testing/、deployment/、code-style/。项目里通过引用团队技能库来复用，而不是每个项目复制一份。这样规范更新时只改一处，所有项目都能受益。

6.2 技能与项目规范的同步机制

项目规范文档和技能文件容易脱节，文档更新了技能没更新，代理就按旧规范干活。解决办法是把技能文件作为规范的唯一来源，文档从技能文件生成，或者至少文档里链接到技能文件。我现在的做法是规范文档只写“为什么”，技能文件写“怎么做”，两者通过链接关联。改规范时先改技能文件，再同步文档，顺序不能反。

6.3 技能效果的度量：怎么知道技能有没有用

技能有没有用，不能靠感觉，得有度量。我一般看两个指标：代理输出符合规范的比例和人工返工的比例。前者可以通过抽查代理产出来估算，后者看代码 Review 里因为规范问题被打回的次数。如果技能上线后返工比例下降，说明技能有效。如果没变化，可能是技能没触发，或者技能内容太模糊代理执行不了。这个度量不用很精确，有个大致趋势就能指导优化。

6.4 后续扩展方向：技能市场与技能继承

技能体系成熟后，可以考虑两个扩展方向。一是技能市场，团队之间共享技能，比如前端团队和后端团队各自维护自己的技能集，需要时互相引用。二是技能继承，基础技能定义通用规范，项目技能继承并覆盖特定部分。这两个方向都能进一步提升复用率，但也会增加复杂度，建议在技能体系稳定后再考虑。我目前还在技能库阶段，市场化和继承机制还在观察，等团队规模再大一些可能会上。

7. 我个人的实操体会

折腾agent-skills这段时间，最大的体会是：技能体系的价值不在于技能数量，而在于触发准确率和内容可执行性。我一开始贪多，写了二十多个技能，结果触发混乱，代理经常加载不相关的技能。后来砍到八个，每个都反复打磨触发词和步骤，效果反而好很多。另一个体会是技能文件要当代码管，版本控制、Review、测试一个都不能少。最后分享一个小技巧：给每个技能加一个“最后验证日期”，定期回顾，过期的技能及时更新或删除，避免技能库变成垃圾场。这个习惯让我在三个月里把技能库的准确率从六成提到了九成以上。