1. 从agent-skills说起为什么我们需要给AI编码代理装上一套技能库第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是终于有人把这件事单独拎出来做了。过去大半年我一直在用各种AI编码代理AI coding agents写代码、改bug、跑测试从最早的Claude Code到后面陆续接入的其他模型踩过的坑能写满一个笔记本。最大的感受就是——模型本身的能力固然重要但真正决定它能不能干活的是它手里有没有一套趁手的技能。agent-skills这个项目本质上就是给AI编码代理准备的一套可复用的技能集合配套一个skills CLI工具来管理这些技能。你可以把它理解成给代理装的一个工具箱里面装着测试驱动开发test-driven-development、代码审查、重构、文档生成这些常见任务的标准化流程。代理不再需要每次从零开始摸索怎么做一件事而是直接调用已经封装好的技能。这个项目解决的核心问题很具体AI编码代理在执行复杂任务时缺乏结构化的、可复用的工作流。你让它写个函数它没问题但你让它按照TDD的方式实现一个功能模块它往往会跳过写测试这一步直接给你一堆实现代码。这不是模型笨而是它没有一个明确的技能模板告诉它做这类事情应该分几步走。适合谁来参考这份内容三类人一是已经在用Claude Code或者其他AI编码代理但觉得输出质量不稳定的开发者二是想给自己的团队搭建一套标准化AI辅助开发流程的技术负责人三是对AI编码代理这个方向感兴趣想了解底层工作机制的技术爱好者。不管你之前有没有接触过skills这个概念下面的内容都能让你有一套可以直接抄作业的方案。2. agent-skills的整体设计思路与核心架构拆解2.1 为什么是技能而不是提示词很多人第一反应是这不就是提示词工程吗我写几个好的prompt不就行了我一开始也这么想但实际用下来发现完全不是一回事。提示词是一次性的、上下文相关的你这次写了一个很好的prompt让代理做代码审查下次换个项目、换个语言这个prompt可能就不适用了。而技能是结构化的、可复用的、带元数据的。一个技能包里面通常包含技能名称、适用场景描述、执行步骤、输入输出规范、依赖条件、示例。它更像是一个函数定义而不是一段自然语言描述。agent-skills的设计哲学就是把这些技能标准化让代理能够根据当前任务自动匹配并加载对应的技能。这背后的逻辑是代理的能力上限不取决于模型参数而取决于它能调用的技能库有多丰富、多规范。2.2 技能目录结构的设计考量一个典型的技能在agent-skills里的组织方式大概是这样的skills/ test-driven-development/ SKILL.md examples/ templates/ code-review/ SKILL.md examples/ refactoring/ SKILL.md examples/每个技能一个目录核心是SKILL.md文件。这个文件用Markdown格式描述技能的完整定义。为什么选Markdown而不是JSON或者YAML因为Markdown对模型更友好——模型在训练时见过大量的Markdown文档它能更好地理解Markdown里的层级结构和语义。而且Markdown写起来也方便开发者不需要记复杂的schema。examples/目录放的是这个技能的实际使用示例templates/放的是可复用的模板文件。这种结构的好处是代理在加载技能时可以先读SKILL.md了解技能定义然后根据需要读取示例和模板形成一个完整的执行上下文。2.3 skills CLI的角色定位skills CLI是这个项目的命令行工具负责技能的安装、管理、更新和调用。为什么需要一个CLI而不是纯靠文件系统因为技能需要版本管理、依赖解析和跨项目共享。我实测下来skills CLI主要解决三个问题技能发现你不需要手动去GitHub上找技能CLI可以直接列出可用的技能库版本控制不同项目可能依赖不同版本的技能CLI帮你管理这些依赖关系快速集成一条命令就能把技能安装到当前项目的代理配置中这跟npm管理JavaScript包、pip管理Python包是一个思路。技能本身也是代码资产需要一套包管理机制来维护。2.4 与Claude Code的集成方式agent-skills跟Claude Code的集成是我最关心的部分。Claude Code本身支持通过配置文件加载自定义指令agent-skills就是利用这个机制把技能注入到Claude Code的执行上下文中。具体来说当你在Claude Code里触发一个任务时它会先扫描当前项目安装的技能根据任务描述匹配相关技能然后把技能定义作为额外的上下文传给模型。模型看到的不只是你的需求描述还有做这类事情的标准流程是什么。这种集成方式的好处是非侵入式的——你不需要修改Claude Code的源码也不需要写复杂的插件只需要按照规范组织技能文件然后通过CLI安装即可。3. 核心技能详解与实操要点3.1 test-driven-development技能让代理先写测试再写实现TDD技能是agent-skills里我认为最有价值的一个。原因很简单AI编码代理最大的毛病就是急于求成——你让它实现一个功能它恨不得一口气把实现代码全写完测试往往是最后补的甚至根本不写。TDD技能的核心逻辑是强制代理按照红-绿-重构的循环来工作红先写一个失败的测试明确预期行为绿写最少的实现代码让测试通过重构在测试保护下优化代码结构这个技能在SKILL.md里会明确定义每个步骤的输入输出。比如第一步写失败测试技能会要求代理测试文件命名遵循项目现有规范每个测试只验证一个行为测试必须能够独立运行测试失败信息要清晰描述预期与实际我踩过的一个坑是如果不给代理明确的测试框架信息它可能会用错断言库。比如项目用的是Jest它给你写成Mocha的语法。所以TDD技能的SKILL.md里应该包含项目技术栈的检测逻辑或者至少让代理在写测试前先确认测试框架。提示TDD技能的效果高度依赖于项目已有的测试基础设施。如果项目本身没有测试框架建议先让代理帮你搭建好测试环境再启用TDD技能。3.2 code-review技能标准化的代码审查流程代码审查技能解决的是代理审查代码时抓不住重点的问题。没有技能约束的情况下你让代理review一段代码它可能会花大量篇幅夸你的变量命名好却漏掉了潜在的并发问题。agent-skills里的code-review技能定义了一套审查清单审查维度检查要点严重级别正确性边界条件、空值处理、异常路径高安全性输入验证、敏感数据泄露、注入风险高性能循环嵌套、重复计算、内存泄漏中可维护性函数长度、命名清晰度、注释完整性中风格一致性缩进、导入顺序、命名规范低这个表格是技能定义的一部分代理在审查时会按照这个清单逐项检查并按照严重级别排序输出。我实测下来有了这个清单之后代理的审查质量提升非常明显——它不再泛泛而谈而是能给出具体的、可操作的修改建议。3.3 技能加载与匹配机制技能加载的时机和方式直接影响代理的表现。agent-skills采用的是按需加载策略代理先分析任务描述提取关键词然后从已安装的技能库中匹配相关技能。匹配算法本身不复杂主要是基于关键词和语义相似度。但这里有个设计细节值得注意技能匹配不是全有或全无的而是可以同时加载多个相关技能。比如一个任务既涉及写新功能又涉及重构代理可能会同时加载TDD技能和重构技能。我建议在项目根目录放一个skills.config.json显式声明这个项目需要哪些技能。这样做的好处是避免代理加载不相关的技能浪费上下文窗口。配置示例{ skills: [ test-driven-development, code-review ], autoLoad: true, matchThreshold: 0.7 }matchThreshold控制匹配的严格程度值越高越严格。我一般设在0.7左右既能保证相关性又不会漏掉有用的技能。3.4 技能编写的最佳实践如果你要自己写技能有几个原则是我踩坑之后总结出来的第一技能描述要具体到可执行。不要写写好代码要写函数不超过50行每个函数只做一件事参数不超过4个。模糊的描述等于没有描述。第二每个技能只解决一类问题。我见过有人把代码审查和性能优化写在一个技能里结果代理执行时经常混淆两个阶段的目标。拆开之后效果好很多。第三示例比描述更重要。模型对示例的学习能力远强于对抽象描述的理解。一个技能里放3-5个高质量示例比写1000字的规范说明更有效。第四版本化你的技能。技能也是代码会迭代。用语义化版本号管理在SKILL.md的frontmatter里标注版本和兼容性信息。4. 完整实操流程从零搭建一套可用的技能体系4.1 环境准备与skills CLI安装假设你已经在用Claude Code并且项目是一个Node.js项目。第一步是安装skills CLI。根据我的经验最稳妥的方式是通过npm全局安装npm install -g agent-skills/cli安装完成后验证skills --version如果提示命令找不到检查npm全局bin目录是否在PATH里。在Ubuntu上通常是~/.npm-global/bin或者/usr/local/binMac上一般是/usr/local/bin。这个问题我遇到过好几次新手很容易卡在这里。接下来初始化技能配置cd your-project skills init这个命令会在项目根目录创建skills.config.json和.skills/目录。.skills/是技能的实际安装位置建议加到.gitignore里因为技能可以通过配置文件重新安装不需要提交到仓库。4.2 安装与配置核心技能安装TDD技能skills install test-driven-development安装code-review技能skills install code-review安装完成后.skills/目录下会出现对应的技能文件夹。你可以打开SKILL.md看看内容确认技能定义符合你的预期。然后配置Claude Code的集成。在项目根目录的.claude/目录下如果没有就创建一个添加或修改settings.json{ skills: { enabled: true, configPath: ./skills.config.json, autoMatch: true } }这个配置告诉Claude Code在启动时加载技能配置并在执行任务时自动匹配相关技能。4.3 用TDD技能完成一个真实功能开发我拿一个实际例子来演示。假设我们要实现一个用户注册时校验密码强度的功能。第一步触发TDD技能在Claude Code里输入使用TDD方式实现密码强度校验功能要求 - 至少8个字符 - 包含大写字母、小写字母、数字 - 返回校验结果和具体失败原因第二步代理写失败测试代理会先加载TDD技能然后按照技能定义的流程先写测试文件。它生成的测试大概长这样describe(validatePasswordStrength, () { it(should reject password shorter than 8 characters, () { const result validatePasswordStrength(Ab1); expect(result.valid).toBe(false); expect(result.reason).toContain(8); }); it(should reject password without uppercase letter, () { const result validatePasswordStrength(abcdefg1); expect(result.valid).toBe(false); expect(result.reason).toContain(大写); }); // ... 更多测试用例 });第三步确认测试失败代理会运行测试确认所有测试都失败因为实现还不存在。这一步很关键它验证了测试确实在检验行为而不是永远通过。第四步写最小实现代理写最少的代码让测试通过function validatePasswordStrength(password) { if (password.length 8) { return { valid: false, reason: 密码长度至少8个字符 }; } if (!/[A-Z]/.test(password)) { return { valid: false, reason: 需要包含大写字母 }; } if (!/[a-z]/.test(password)) { return { valid: false, reason: 需要包含小写字母 }; } if (!/[0-9]/.test(password)) { return { valid: false, reason: 需要包含数字 }; } return { valid: true, reason: }; }第五步运行测试确认通过代理运行测试确认全部通过。第六步重构在测试保护下代理可能会把校验规则抽成配置数组让代码更易扩展。整个流程走下来我最大的感受是代理的行为变得可预测了。没有TDD技能的时候它可能直接给你一个实现测试随便写两个意思一下。有了技能约束它会老老实实按步骤走。4.4 用code-review技能审查代码功能实现完之后我习惯让代理用code-review技能审查一遍。输入使用code-review技能审查刚才实现的密码校验功能代理会按照技能定义的审查清单逐项检查输出格式大概是## 审查结果 ### 高严重级别 - [正确性] 第12行正则表达式 /[A-Z]/ 没有考虑Unicode大写字母的情况 建议使用 /\p{Lu}/u 替代 ### 中严重级别 - [可维护性] 校验规则硬编码在函数中新增规则需要修改函数体 建议将规则抽成配置数组 ### 低严重级别 - [风格] 返回对象中的 reason 字段在成功时为空字符串建议改为 null这种结构化的审查输出比让代理自由发挥要实用得多。你可以直接把审查结果当成todo list来用。5. 常见问题与排查技巧实录5.1 技能不生效怎么办这是最常见的问题。代理没有按照技能定义的方式工作说明技能没有被正确加载。排查步骤确认skills.config.json里的技能名称拼写正确检查.skills/目录下是否存在对应的技能文件夹查看Claude Code的启动日志确认技能加载没有报错尝试手动触发技能匹配在任务描述里显式提到技能名称我遇到过一次是因为skills.config.json的路径配置错了CLI默认从当前目录找但Claude Code的工作目录可能不同。后来改成绝对路径就好了。5.2 技能匹配不准确有时候代理会加载不相关的技能或者该加载的技能没加载。这通常是匹配阈值设置的问题。matchThreshold设得太低会加载太多无关技能设得太高会漏掉相关技能。我的经验值是0.6-0.75之间。如果你的任务描述比较模糊可以适当降低阈值如果任务描述很具体可以提高阈值。另一个技巧是在任务描述里加入技能相关的关键词。比如你想触发TDD技能就在描述里明确写用TDD方式或者先写测试。5.3 技能之间的冲突当你同时加载多个技能时可能会出现指令冲突。比如TDD技能要求先写测试而某个快速原型技能要求先写实现。这种冲突会导致代理行为不稳定。解决方法是在skills.config.json里设置技能优先级{ skills: [ { name: test-driven-development, priority: 10 }, { name: rapid-prototyping, priority: 5 } ] }优先级高的技能在冲突时胜出。或者更简单的做法不要同时加载功能重叠的技能。5.4 常见问题速查表问题现象可能原因解决方法技能完全不生效配置路径错误检查configPath是否为绝对路径代理忽略技能步骤技能描述不够具体在SKILL.md中增加可执行的步骤定义加载了错误技能匹配阈值过低提高matchThreshold到0.7以上技能执行到一半停止上下文窗口不足减少同时加载的技能数量不同项目技能冲突全局安装vs项目安装优先使用项目级安装技能更新后行为变化版本不兼容锁定技能版本号5.5 几个我踩过的坑坑一技能文件编码问题。有一次我写了一个包含中文的技能描述保存时用了GBK编码结果代理读出来是乱码。后来统一用UTF-8就好了。这个坑很隐蔽因为文件在编辑器里看起来是正常的。坑二技能目录名和技能名不一致。skills CLI默认用目录名作为技能标识如果你在SKILL.md里写的技能名和目录名不一样匹配时就会出问题。建议保持一致。坑三过度依赖技能。技能是辅助不是万能药。有些任务本身就很模糊再好的技能也帮不了你。这时候应该先把任务拆解清楚再让代理执行。坑四忘记更新技能。技能库本身也在迭代新版本可能修复了bug或者增加了新功能。建议定期运行skills update更新所有已安装的技能。6. 技能体系的扩展与团队协作6.1 为团队定制私有技能当团队规模变大时公共技能库可能满足不了需求。这时候就需要定制私有技能。agent-skills支持从私有仓库安装技能skills install your-org/your-skill --registry https://your-registry.com私有技能可以封装团队内部的编码规范、架构约定、部署流程等。比如我们团队有一个API设计规范技能定义了URL命名、状态码使用、错误响应格式等。新来的同事用Claude Code写API时代理会自动按照这个规范生成代码省去了大量review时间。6.2 技能的组合与编排单个技能解决单个问题但实际任务往往需要多个技能配合。agent-skills支持技能编排你可以在配置里定义技能的执行顺序{ workflows: { feature-development: [ test-driven-development, code-review, documentation ] } }这样当你触发feature-development工作流时代理会依次执行TDD、代码审查、文档生成三个技能。这种编排能力让技能体系从工具箱升级成了流水线。6.3 技能效果的度量与优化怎么知道一个技能好不好用我一般从三个维度评估任务完成率代理使用技能后任务一次通过的比例人工干预次数执行过程中需要人工纠正的次数输出一致性相同任务多次执行输出质量的稳定性我建议在团队内部维护一个简单的技能评分表定期review哪些技能效果好、哪些需要优化。技能也是代码资产需要持续维护。6.4 与CI/CD的集成思路技能体系不仅可以用于本地开发还可以集成到CI/CD流程中。比如在PR创建时自动触发code-review技能审查变更把审查结果作为PR评论。这样即使没有人工review也能保证基本的代码质量。实现方式是通过Claude Code的headless模式在CI脚本里调用claude-code --skill code-review --input review the changes in this PR --output review.md然后把review.md的内容发到PR评论里。这个方案我们团队已经在用了效果还不错能拦住大部分低级问题。7. 关于技能体系的一些个人体会用agent-skills这套东西大半年下来我最大的体会是AI编码代理的上限取决于你给它多少结构化的知识。模型本身的能力已经很强了但它不知道你的项目用什么测试框架、你的团队有什么编码规范、你的部署流程有哪些步骤。技能就是把这些隐性知识显性化让代理能够按照你期望的方式工作。另一个体会是技能不是越多越好。我一开始装了一大堆技能结果代理每次执行任务都要加载一堆不相关的内容反而影响了效果。后来精简到只保留最常用的几个效果明显提升。技能体系需要定期清理就像清理依赖包一样。还有一个反直觉的发现写技能比写代码更需要迭代。一个技能写出来第一次用可能效果一般需要根据实际使用情况反复调整描述、补充示例、优化步骤。我有个TDD技能改了七八版才达到比较满意的效果。所以不要指望一次写出完美的技能要把它当成一个持续改进的过程。最后分享一个小技巧如果你不确定某个技能该怎么写可以先让Claude Code自己生成一个初版然后你在这个基础上修改。比如输入帮我写一个code-review技能的SKILL.md包含审查清单和输出格式它会给你一个不错的起点。然后你根据实际使用情况调整比从零开始写要快得多。这套技能体系后续还可以往几个方向扩展一是增加更多领域的技能比如数据库迁移、性能分析、安全审计二是做技能的市场化让社区可以分享和复用技能三是跟更多的AI编码代理集成不只限于Claude Code。这些方向都挺有意思的等我有新的实践再来分享。