agent-skills 工程化实践：让 AI 编码代理稳定复用技能

1. 从agent-skills说起一个被低估的工程化命题第一次看到agent-skills这个词很多人会下意识地把它归类成又一个提示词合集。我一开始也是这么想的直到真正把它放进日常的 AI coding agents 工作流里跑了几轮才发现它解决的其实是一个更底层的问题如何让 AI 编码代理在不同任务之间稳定地复用同一套能力而不是每次都要重新教它一遍。简单说agent-skills是一套面向 AI coding agents 的技能组织方式通常以目录 描述文件的形式存在配合 skills CLI 进行加载、检索和调用。它要解决的核心痛点是当你用 Claude Code 这类工具做真实项目时会发现模型本身很聪明但聪明不等于可靠。同一个重构任务今天它能按你的规范改明天可能就换了一套命名风格同一个测试流程这次跑通了下次它可能跳过边界用例。agent-skills的价值就在于把这些隐性规范沉淀成显性技能让代理每次执行时都有据可依。这套东西适合谁我的判断是三类人一是已经在用 Claude Code、Cursor 这类工具做实际开发但被输出不稳定折磨过的工程师二是想给团队建立统一 AI 编码规范的 tech lead三是刚接触 AI coding agents、想少走弯路的新手。它不要求你会写复杂的插件但要求你愿意把怎么做才对这件事想清楚、写下来。我踩过的第一个坑就是以为技能写得越详细越好。结果一个技能文件写了八百字代理加载后反而抓不住重点执行时该忽略的细节全忽略了。后来才明白agent-skills的精髓不是写全而是写准——把判断标准和关键约束讲清楚剩下的交给模型自己发挥。2. 核心设计思路为什么是技能而不是提示词2.1 提示词与技能的本质区别很多人会把agent-skills和系统提示词混为一谈觉得无非是把 prompt 拆成文件而已。这个理解偏差会导致后面所有设计都走偏。我用一个类比说明区别提示词像是给新员工的入职须知技能像是岗位操作手册。入职须知告诉你我们公司做什么、你负责哪块是一次性的、全局的。而操作手册是遇到 A 情况按这个流程、遇到 B 情况检查这几个点是可复用、可组合、按需调用的。当你让 AI coding agent 做测试驱动开发时你不需要它每次都重新理解什么是 TDD你需要的是它知道这个项目里测试文件放哪、用什么断言库、覆盖率门槛是多少、先写测试还是先写实现。这就是agent-skills的设计出发点把任务相关的上下文和约束从全局提示词里剥离出来做成可独立加载的单元。好处有三个第一上下文窗口更省只加载当前任务需要的技能第二技能可以跨项目复用一个Python 测试规范技能能用在十个仓库里第三技能可以版本化管理改规范就是改文件可追溯、可回滚。2.2 技能目录的典型结构基于我实际用下来的经验一个可维护的agent-skills目录通常长这样agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ └── examples/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── checklist.md │ └── refactor/ │ └── SKILL.md ├── skills.json └── README.md这里有几个设计决策值得展开。为什么每个技能是独立目录而不是单文件因为真实技能往往需要附带示例、检查清单、参考代码。把SKILL.md作为入口其他文件作为支撑材料代理可以先读入口判断这个技能适不适用需要细节时再深入读附件。这比把所有内容塞进一个文件要高效得多。为什么要有skills.json这是给 skills CLI 用的索引。它记录了每个技能的名称、描述、触发条件、依赖关系。代理在接到任务时先查索引匹配技能而不是把所有技能全读一遍。这个先检索后加载的机制是控制上下文成本的关键。2.3 触发条件的设计比内容本身更重要我见过太多人把精力全花在技能正文上却忽略了触发条件。结果就是技能写得很好但代理根本不知道该在什么时候用它。触发条件本质上是这个技能解决什么问题的一句话描述要写得让模型能判断匹配度。举个例子一个测试驱动开发技能的触发条件我建议这样写当任务涉及新增功能、修复缺陷、重构逻辑且项目要求测试先行时使用。不适用于纯文档修改、配置调整、样式微调。注意后半句不适用于同样重要。明确边界能防止技能被滥用。我早期写的触发条件只有正面描述结果代理在改一个 CSS 颜色时也去加载 TDD 技能白白浪费上下文还拖慢响应。3. 核心细节解析一个 TDD 技能是怎么落地的3.1 技能正文的黄金结构SKILL.md的写法直接决定技能好不好用。我试过好几种结构最后稳定下来的模板是四段式目标、约束、流程、验收标准。目标段回答这个技能要达成什么一到两句话。约束段列出硬性规则比如测试文件必须与被测文件同目录禁止在测试中使用真实网络请求。流程段是分步骤的操作指引。验收标准段告诉代理怎么算做完了这是最容易被忽略但最有价值的部分。为什么验收标准这么关键因为 AI coding agent 最大的问题不是不会做而是不知道什么时候该停。没有明确验收标准它可能反复修改、过度优化或者提前收工。把测试全部通过且覆盖率不低于 80%写进技能代理就有了明确的终止条件。3.2 约束要写成可判定的规则约束段最容易犯的错是写成模糊的价值观。比如代码要优雅测试要充分这种话对代理毫无指导意义因为它无法判定自己是否满足。好的约束必须是可判定的。对比一下模糊约束可判定约束测试要充分每个公开函数至少一个正常用例和一个异常用例命名要规范测试函数名格式为 test_被测函数_场景_预期结果不要重复代码相同逻辑出现三次以上必须抽取为独立函数注意性能单次测试执行时间不超过 5 秒右边这列代理执行完能自己检查是否达标。这就是可判定的价值。我在实际项目里把约束全部改成可判定形式后代理的返工率明显下降。3.3 流程步骤的粒度控制流程段写多细是个技术活。写太粗代理自由发挥空间太大结果不可控写太细代理变成机械执行遇到边界情况不会变通。我的经验是关键决策点写细机械操作写粗。以 TDD 为例先写测试这个顺序是必须写死的因为这是 TDD 的核心。但用什么命令跑测试可以写粗让代理根据项目实际情况判断。再比如测试失败后如何定位这个决策点要写细给出排查顺序而如何提交代码可以写粗因为不同项目规范不同。提示流程步骤里凡是涉及顺序不能变的环节一定要用明确的顺序词标注比如第一步必须先...确认通过后再进行第二步。代理对顺序的敏感度不如人类需要显式强调。3.4 示例文件的作用被严重低估examples/目录里的示例作用不是给代理抄而是给代理校准。模型通过对比示例能更准确地理解技能描述的抽象规则。我建议每个技能至少配一个正例和一个反例。正例展示这样做是对的反例展示这样做是错的错在哪。反例尤其重要因为模型对不要做什么的理解往往比对要做什么更模糊。一个具体的反例能让它快速建立边界感。4. 实操过程从零搭建一套可用的 agent-skills4.1 环境准备与 skills CLI 接入先说环境。无论你是在 macOS、Ubuntu 还是 Windows 上核心依赖都是 Node.js 环境和一个支持 skills 机制的 AI coding agent。以 Claude Code 为例安装完成后skills CLI 通常作为配套工具提供。接入的基本流程是先确认 agent 版本支持 skills 机制然后在项目根目录创建agent-skills目录结构最后通过 CLI 命令注册技能索引。这里有个细节技能目录的位置会影响加载优先级。项目级技能优先于用户级技能这意味着你可以在具体项目里覆盖全局规范。我实测下来把通用技能放在用户级目录比如~/.agent-skills/把项目特定技能放在项目根目录是最合理的分层方式。这样换项目时通用技能自动可用项目技能随仓库走团队协作时不会丢。4.2 编写第一个技能以测试驱动开发为例假设我们要写一个 TDD 技能。第一步是确定触发条件前面说过要写清适用和不适用场景。第二步是写正文按四段式结构来。目标段我这样写确保新增和修改的代码都有对应的测试覆盖测试先于实现编写实现以通过测试为唯一目标。约束段列出硬性规则测试文件命名遵循项目既有约定无约定时使用test_模块名格式每个测试用例只验证一个行为测试必须能在无网络环境下运行禁止修改测试来迁就实现只能修改实现来通过测试流程段分步骤阅读任务描述列出需要覆盖的行为点为每个行为点编写测试用例此时测试应当失败运行测试确认失败原因是功能未实现而非测试写错编写最小实现使测试通过重构实现保持测试通过检查覆盖率补充遗漏的边界用例验收标准段所有测试通过新增代码覆盖率不低于项目既定门槛无跳过或注释掉的测试。这套结构写下来大概三百到五百字足够代理理解并执行。关键是每一步都可判定代理不会卡在我这样做对不对的犹豫里。4.3 技能组合与依赖管理真实任务往往需要多个技能协同。比如一个重构 测试的任务需要同时加载重构技能和 TDD 技能。这时候依赖管理就很重要。我的做法是在skills.json里声明技能间的依赖关系。比如重构技能声明依赖 TDD 技能那么加载重构技能时CLI 会自动把 TDD 技能也加载进来。这样代理执行重构时天然就知道要保证测试通过。但依赖不能滥用。我踩过的坑是给一个技能加了五六个依赖结果每次加载都拖进来一大堆上下文响应变慢不说代理还容易被无关信息干扰。后来我定了个规矩依赖只声明强关联的技能弱关联的靠触发条件自然匹配。4.4 参数化与项目适配不同项目的规范不一样技能不能写死。解决办法是参数化。在技能里用占位符表示可变部分比如{{test_command}}、{{coverage_threshold}}然后在项目配置里填具体值。这样一套 TDD 技能能适配 Python 项目pytest 80% 覆盖率和 JavaScript 项目jest 70% 覆盖率不用维护两份。参数化的另一个好处是团队新人能一眼看出这个项目的测试门槛是多少技能文件本身就成了活的规范文档。5. 常见问题与排查技巧实录5.1 技能不生效的排查顺序技能写了但代理不用这是最高频的问题。我的排查顺序是这样的排查项检查方法常见原因索引是否注册查看 skills.json 是否包含该技能新增技能忘了更新索引触发条件是否匹配手动对照任务描述和触发条件触发条件写得太窄或太泛文件路径是否正确确认 SKILL.md 在预期位置目录层级放错格式是否合规检查是否有语法错误描述文件格式不规范优先级是否被覆盖检查是否有同名技能项目级技能覆盖了用户级大部分问题出在前两项。触发条件写得太窄代理匹配不上写得太泛又匹配到不该匹配的任务。我的经验是触发条件要包含任务类型 前置条件 排除项三要素。5.2 代理执行偏离技能规范怎么办有时候技能加载了代理也读了但执行时还是偏离。这种情况通常是技能里的约束不够硬。解决办法是把关键约束前置并且用明确的禁止性语言。比如测试必须先写这种要求如果写成建议先写测试代理可能忽略。改成必须先编写测试并确认其失败才能开始编写实现代码执行率会高很多。模型对必须禁止只能这类词的敏感度明显高于建议尽量。另一个技巧是在流程的关键节点加自检点。比如完成测试编写后暂停并确认测试是否覆盖了所有行为点是否能在无网络环境运行确认后再进入下一步。这种显式的暂停检查能有效防止代理一路狂奔到错误方向。5.3 上下文超限的优化策略技能多了以后上下文容易超限。优化手段有几个一是精简技能正文把详细内容移到附件入口只留核心二是用索引做粗筛只加载匹配度高的技能三是定期清理不再使用的技能。我个人的习惯是每个季度review一次技能库把三个月没被触发过的技能归档。技能库不是越大越好保持精简才能保证每个技能都被充分利用。5.4 团队协作中的技能同步多人团队用agent-skills最大的问题是规范不同步。有人改了技能没通知别人还在用旧版本。解决办法是把技能库纳入版本控制和代码一起走 PR 流程。改技能要提 PR要 review要写变更说明。另外建议在技能文件头部加一个变更记录区记录每次修改的时间、修改人、修改原因。这样出问题时能快速定位是哪次改动引入的。6. 影响范围与延展思考agent-skills这套机制的影响其实超出了让代理更好用这个层面。它实际上在做一件事把团队里那些口口相传的工程规范变成机器可读、可执行的显性知识。传统上一个团队的编码规范散落在 wiki、代码 review 评论、老员工的经验里。新人要花几个月才能摸清。而agent-skills强制你把这些规范写清楚、写可判定这个过程本身就是一次规范梳理。写完之后不仅代理能用新人也能读review 时也有据可依。从更长的视角看随着 AI coding agents 越来越普及如何组织代理的能力会成为一个独立的工程领域。agent-skills目前还比较朴素就是目录加描述文件但它的方向是对的能力要可组合、可复用、可版本化。我预计接下来会出现更成熟的技能包管理机制、技能市场、技能依赖解析工具。现在开始积累自己的技能库等生态成熟时就是一笔现成的资产。最后分享一个我自己的小习惯每次在项目里发现代理做错了某件事我不会直接改代码了事而是问自己这个错误能不能通过加一条技能约束来避免。如果能就顺手更新技能库。这样技能库会随着项目推进自然生长越用越顺手。踩过的坑不白踩都变成技能里的一条约束下次代理就不会再犯。这大概就是agent-skills最实在的价值——让每一次踩坑都有复利。