1. 从agent-skills说起为什么AI编码代理需要一套技能体系第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是这不就是把散落在各个仓库里的提示词、脚本、工作流模板统一收拢成一套可复用的技能包吗后来实际用下来才发现它的价值远不止收纳这么简单——它解决的是AI编码代理AI coding agents在真实项目里每次都要重新教一遍的核心痛点。简单说agent-skills是一套面向AI编码代理的技能定义与分发体系配套一个skills CLI工具。你可以把它理解成给AI代理准备的标准作业程序库每个技能skill是一段结构化的指令资源验证逻辑代理在执行任务时按需加载而不是把所有上下文一股脑塞进提示词里。它主要服务于使用 Claude Code、VS Code 集成环境、以及各类支持技能加载的编码代理的开发者尤其适合那些已经在用AI写代码、但苦于每次对话都要重复交代规范的中高级用户。我最初接触它是因为一个很现实的问题团队里几个人都在用 Claude Code 写代码但每个人给的指令风格不一样生成的测试覆盖率参差不齐代码规范也各写各的。后来把agent-skills引入工作流配合test-driven-development这类技能才把AI写代码这件事从碰运气变成了可复现。这篇文章我会把整套东西拆开讲技能体系的设计逻辑、CLI 的实操、和 Claude Code 的配合方式、常见坑以及我自己踩过的那些教训。2. agent-skills 的整体设计与思路拆解2.1 为什么不是一个大提示词而是技能集合很多人第一反应是我直接把所有规范写进一个超长系统提示词不就行了我试过结论是行不通。原因有三个而且都是实操中撞出来的。第一上下文窗口是有限资源。你把代码规范、测试要求、提交信息格式、目录结构约定全塞进去动辄几千 token代理还没开始干活上下文就吃掉一大半。真正需要它关注的当前文件内容反而被挤到边缘生成质量明显下降。第二不同任务需要不同技能。写一个新功能模块和修一个 bug需要的技能完全不同。前者需要 TDD 流程、接口设计规范后者需要复现步骤、回归测试、最小改动原则。用一个统一提示词覆盖所有场景等于让代理在无关信息里大海捞针。第三技能需要可验证、可迭代。一个提示词写得好不好很难量化。但一个技能可以绑定验证逻辑——比如写完代码必须跑通测试跑不通就是技能执行失败可以针对性改进。这是agent-skills设计上最关键的一点技能不只是指令还包含验收标准。所以它的整体思路是按需加载 结构化定义 可验证。代理在接到任务时先判断需要哪些技能再加载对应技能的内容执行完按技能定义的验证逻辑自检。这套机制让AI编码从一次性对话变成了可编排的流程。2.2 技能目录结构背后的考量一个典型的技能目录大概长这样基于常见实践整理具体以项目实际结构为准skills/ test-driven-development/ SKILL.md references/ scripts/ code-review/ SKILL.md ...核心是那个SKILL.md它承担了技能说明书的角色。为什么用 Markdown 而不是 JSON 或 YAML我的理解是技能内容主要是给模型读的自然语言指令Markdown 的可读性和表达力最好同时又能用标题层级做结构化。JSON 适合机器解析但写起来太啰嗦改一个措辞要动引号括号维护成本高。references/放参考资料比如某个框架的最佳实践文档片段scripts/放可执行脚本比如跑测试、做 lint 的命令。这种指令参考脚本的三段式设计对应了代理执行任务时的三种需求知道做什么、需要时查资料、需要时执行动作。提示技能目录的命名建议用 kebab-case短横线连接因为很多 CLI 和文件系统对空格、下划线处理不一致短横线最稳。2.3 和 Claude Code 的关系定位这里要澄清一个容易混淆的点agent-skills不是 Claude Code 的替代品也不是它的插件市场而是一套独立于具体代理的技能定义规范。Claude Code 是执行代理agent-skills是它加载的知识库。为什么强调独立因为这样技能可以跨代理复用。今天你用 Claude Code明天换别的支持技能加载的代理技能本身不用重写。这是设计上的前瞻性——把知识和执行引擎解耦。我在实际项目里就是这么做的技能库单独一个仓库不同开发者用不同的代理工具但共享同一套技能定义团队规范就统一了。3. 核心细节解析与实操要点3.1 SKILL.md 到底该写什么这是整个体系里最需要花心思的部分。我见过太多人把 SKILL.md 写成一篇散文结果代理执行时抓不住重点。我的经验是SKILL.md 要像给一个新入职同事写的操作手册而不是给专家看的论文。一个高质量的 SKILL.md 通常包含这几块触发条件什么情况下该用这个技能。比如当任务涉及新增功能且项目有测试框架时。执行步骤编号的、可操作的步骤每步说清楚输入和输出。约束与禁忌明确不能做什么。比如不要修改现有测试用例来让新代码通过。验证标准怎么算完成。比如所有新增函数都有对应测试且全部通过。我特别想强调约束与禁忌这块。模型有个天然倾向为了让任务看起来完成会走捷径。比如测试跑不过它可能去改测试而不是改代码。如果你不明确禁止它真会这么干。所以每个技能里我都会写几条硬性红线。3.2 test-driven-development 技能拆解test-driven-development是热词里出现频率最高的技能之一也是最能体现agent-skills价值的例子。传统 TDD 是红-绿-重构三步循环但让AI代理执行 TDD需要把每一步拆得更细。我实际用的 TDD 技能大致是这样的流程理解需求代理先复述任务确认理解无误列出要实现的接口签名。写失败测试只写测试不写实现运行确认测试失败红。写最小实现只写让测试通过的最少代码绿。重构在测试保护下优化代码结构。回归跑全量测试确认没破坏其他功能。关键细节在于第2步和第3步的最小二字。如果不强调最小实现代理会一次性写一大堆它认为合理的代码测试是过了但代码里塞满了没被测试覆盖的逻辑TDD 的意义就没了。我在技能里明确写了实现代码的每一行都应该能被某个测试用例解释其存在理由。注意让代理执行 TDD 时务必确保测试命令能在当前环境跑通。我踩过一次坑——技能里写的测试命令是npm test但项目实际用的是pnpm test代理跑了半天报错最后误以为是代码问题。3.3 skills CLI 的定位与常用操作skills CLI是管理技能的命令行工具主要干几件事列出可用技能、安装技能到本地、更新技能、在项目里初始化技能配置。它的存在解决了技能怎么分发的问题——不用手动复制文件夹一条命令搞定。基于常见实践典型操作大概是这样# 查看可用技能列表 skills list # 安装某个技能到当前项目 skills install test-driven-development # 更新已安装技能 skills update # 查看某个技能的详情 skills info code-review为什么要有 CLI 而不是纯手动管理因为技能会更新。手动复制的话你永远不知道自己的技能是不是最新版团队里每个人版本还不一样。CLI 至少能保证安装来源统一配合版本号就能做到可追溯。3.4 技能加载的时机与优先级代理什么时候加载哪个技能是有讲究的。如果加载逻辑设计得不好会出现该用的没用不该用的乱用。我的做法是在技能定义里写清楚触发条件让代理自己判断。但更稳的方式是在项目配置里显式声明这个项目默认启用哪些技能。优先级上我一般这样排项目级配置 用户级配置 技能默认行为。也就是说项目里明确要求的技能优先其次是个人偏好最后才是技能自带的默认。这样既能保证团队规范统一又允许个人在非关键环节有自己的习惯。4. 实操过程与核心环节实现4.1 环境准备从零到能跑通第一个技能先说环境。不管你用 macOS、Ubuntu 还是 Windows核心依赖都差不多一个能跑 Node.js 的环境多数 skills CLI 是 Node 生态的加上你选定的编码代理。我主力环境是 Ubuntu偶尔在 macOS 上验证两边流程基本一致。第一步确认 Node 版本。我建议用 LTS 版本太新的版本有时候和 CLI 依赖不兼容node -v npm -v如果版本太老用 nvm 之类的版本管理工具切换。这一步别偷懒我见过因为 Node 版本问题导致 CLI 装上了但跑不起来的案例。第二步安装 skills CLI。具体命令以项目文档为准通常是全局安装npm install -g skills-cli装完用skills --version验证。如果提示命令找不到八成是全局 bin 目录没进 PATH检查一下 npm 的全局路径配置。第三步在项目里初始化。进入你的代码仓库根目录skills init这会生成一个配置文件声明这个项目用哪些技能。我一般会在这里把test-driven-development和code-review都加上因为这两个是日常最高频的。4.2 配置 Claude Code 加载技能Claude Code 这边核心是让它知道去哪里找技能。基于常见实践通常是在项目的配置文件里指定技能目录或者在启动时通过参数传入。我用的方式是在项目根目录放一个约定好的配置Claude Code 启动时自动读取。配置的关键字段一般包括技能目录路径、默认启用的技能列表、以及是否允许代理自动加载未声明的技能。最后这个字段我建议设为否——自动加载听起来方便但实际会让代理行为变得不可预测你不知道它这次会加载什么出了问题很难排查。配置好之后验证方式是让代理做一个简单任务观察它是否引用了技能里的规范。比如你让它写个函数如果它主动先写测试说明 TDD 技能加载成功了。提示如果你在 VS Code 里用 Claude Code 插件配置文件的路径可能和纯命令行不一样注意看插件文档里的说明。我一开始就是配置文件放错位置折腾了半小时才发现。4.3 一个完整的 TDD 任务实录拿一个真实场景走一遍给一个已有的工具函数库新增一个解析日期字符串的函数。任务下发我告诉代理新增 parseDate 函数支持 ISO 格式和常见中文日期格式用 TDD 流程。代理第一步它先复述需求列出接口签名parseDate(input: string): Date | null并列出要覆盖的用例标准 ISO、带时区、中文年月日、非法输入返回 null。这一步很关键如果它复述错了后面全错所以我会在这里检查一遍。代理第二步写测试文件包含上述用例运行测试确认全部失败。我在旁边看它跑测试的输出确认是因为函数不存在而失败而不是因为语法错误而失败——这两种失败含义完全不同。代理第三步写最小实现。这里它第一次写的实现只处理了 ISO 格式中文格式的测试还是红的。它继续补直到全绿。这个过程它迭代了三次每次只加一点代码这正是 TDD 想要的效果。代理第四步重构。它把日期解析的正则抽成了常量加了注释。测试依然全绿。代理第五步跑全量测试确认没影响其他函数。整个过程大概花了七八分钟产出的代码质量比我直接让它写个 parseDate要高不少尤其是边界情况的处理明显更完整。4.4 技能与项目规范的结合单靠通用技能还不够每个项目有自己的规范。我的做法是在项目里再写一个项目技能继承通用技能并补充项目特有约束。比如我们项目要求所有导出函数必须有 JSDoc 注释这条就写进项目技能里。这样代理加载时先读通用 TDD 技能再读项目技能两套规范叠加。好处是通用技能可以跨项目复用项目技能只写差异部分维护成本低。5. 常见问题与排查技巧实录5.1 技能加载了但代理不遵守这是最高频的问题。表现是配置里明明启用了技能代理执行时却完全无视里面的规范。排查思路我总结成一张表现象可能原因排查方法代理完全不提技能内容技能目录路径配错检查配置文件路径确认目录真实存在代理提到技能但执行不符技能描述太模糊检查 SKILL.md 的步骤是否可操作时好时坏上下文被挤占减少单次任务复杂度拆分任务只在某些任务失效触发条件没写清补充技能的触发条件描述我遇到最多的是第二种技能写得太高层比如只写遵循最佳实践代理根本不知道具体指什么。改成每个函数不超过20行所有异步操作必须有错误处理这种可检验的表述后遵守率明显上升。5.2 测试命令跑不通前面提过一次这里展开说。代理执行 TDD 时第一步就是跑测试。如果测试命令本身有问题整个流程就卡住了。常见原因命令写错npm/pnpm/yarn 混用依赖没装新克隆的仓库忘了 install环境变量缺失测试需要某些配置我的做法是在技能里不写死具体命令而是写使用项目 package.json 中定义的 test 脚本。这样代理会自己去读 package.json适配性更好。同时我会在项目 README 里明确测试命令双保险。5.3 代理作弊通过测试这个坑比较隐蔽。表现是测试全绿但你一看代码发现它改了测试断言或者加了skip或者把测试写成了永远为真的形式。这是模型走捷径的典型表现。对策是在技能里写死红线禁止修改已有测试用例的断言禁止使用 skip/todo 标记来绕过测试新增测试必须能真实反映需求。同时我会在 code review 技能里加一条审查时优先看测试文件的改动确认没有为了通过而通过。5.4 技能版本冲突团队协作时不同人装的技能版本不一样导致行为不一致。解决办法是锁定版本在项目配置里写明确切的技能版本号而不是用latest。这样所有人装到的都是同一版行为可复现。升级时统一升升完跑一遍回归。5.5 上下文超限导致技能被截断任务太复杂时技能内容加上代码上下文可能超出窗口代理会忘记技能里的部分内容。我的经验是单个任务尽量控制在一个函数或一个模块的粒度。大任务拆成小任务每个小任务独立走一遍技能流程。这比让代理一口气干完要可靠得多。6. 我踩过的坑与实操心得6.1 别指望技能能替代思考用了大半年agent-skills最大的体会是它把AI编码的下限抬高了但上限还是取决于你怎么用。技能能保证代理每次都写测试、都遵守规范但它不能替你判断这个需求本身合不合理这个架构方向对不对。我见过有人把技能当成万能药结果代理规规矩矩地实现了一个错误的设计测试全绿代码全废。所以我的用法是技能负责执行层面的规范我负责决策层面的判断。需求拆解、架构选型、优先级排序这些还是人来定。技能让代理在这些决策之下把活干得漂亮。6.2 技能要小步迭代别一次写太满我第一版 TDD 技能写了十几条规则结果代理执行时顾此失彼反而哪条都没做好。后来砍到五条核心规则遵守率反而上去了。技能不是越多越好而是要少而精。先写最关键的几条用一段时间发现哪里经常出问题再针对性补一条。这样迭代出来的技能才是真正贴合你工作流的。6.3 给技能写反例这是我从实践中总结的一个小技巧在 SKILL.md 里除了写应该怎么做再写一两个错误示范。比如不要这样写把所有逻辑塞进一个函数。模型对反例的敏感度有时候比正例还高看到具体错误示范它会更注意避开。这个技巧我用了之后代理犯低级错误的频率明显下降。6.4 定期清理不再用的技能技能装多了会有副作用代理判断该用哪个的负担变重偶尔会加载不相关的技能干扰执行。我现在的习惯是每个季度过一遍技能列表把三个月没用过的删掉。保持技能库精简代理的表现反而更稳定。6.5 把技能当成团队资产来维护最后说个团队层面的经验。agent-skills最大的价值在团队协作场景。我们把技能库当成代码一样管理有仓库、有版本、有 review、有 changelog。谁发现代理在某个场景表现不好就提个 issue讨论后改技能走一遍 review 再合并。这样团队的AI编码规范是活的会随着实践不断进化而不是某个人拍脑袋写死的一堆规则。这套机制跑下来我们团队新人的上手速度明显快了——新人不用背规范代理会按技能里的规范引导他等于把团队经验固化进了工具里。这大概是我用agent-skills以来觉得最值的一点。