1. 从“装完就吃灰”说起agent-skills 到底解决什么问题如果你最近半年一直在折腾 AI coding agents大概率经历过这个循环兴冲冲装好 Claude Code配好模型打开终端然后……不知道让它干什么。问它写个贪吃蛇它给你吐 200 行能跑但没法维护的代码让它改个 bug它把整个文件重写一遍还顺手删了你两个函数。用了几次之后你默默把它丢进角落继续手动敲代码。问题不在模型能力而在你没有给它一套可复用的“工作方法论”。agent-skills 这个项目本质上就是干这件事的它把资深工程师在真实项目里反复验证过的开发流程拆解成 AI coding agent 能理解、能执行的技能模块让 agent 从“随机发挥的实习生”变成“按流程办事的靠谱同事”。我最初接触 agent-skills 是因为一个很具体的痛点团队里三个人用 Claude Code同一个需求三个人跑出来的代码风格、测试覆盖、提交粒度完全不一样。有人让 agent 一口气写完所有功能再测试结果 debug 花了两小时有人坚持先写测试再写实现虽然前期慢但后期几乎不用返工。差异的根源就是缺少统一的技能约束。agent-skills 的核心价值可以概括成三句话第一它把“怎么做”从“做什么”里剥离出来形成独立的技能包第二它用 skills CLI 统一管理这些技能安装、卸载、切换都有标准命令第三它内置了 test-driven-development 这类经过实战检验的开发范式让 agent 的行为可预测、可复现。适合谁来参考如果你是刚接触 Claude Code 的新手它能帮你跳过“瞎试”阶段直接进入有章法的开发节奏如果你已经用了一段时间但觉得输出不稳定它能给你一套结构化的约束框架如果你是团队负责人想统一多人协作时 agent 的行为规范这套东西可以直接抄作业。2. agent-skills 的整体设计思路拆解2.1 为什么要把“技能”从 agent 里拆出来传统做法是把所有指令塞进一个巨大的 system prompt 里告诉 agent“你要先写测试、再写实现、最后重构”。问题是这个 prompt 会越来越长模型注意力被稀释而且不同项目需要的技能组合不一样——写前端组件和写数据库迁移流程能一样吗agent-skills 的设计哲学是技能即模块。每个技能是一个独立的目录里面包含技能描述、触发条件、执行步骤、检查清单。agent 在接到任务时先判断当前场景匹配哪些技能再按技能定义的流程执行。这样做的好处是技能可以独立迭代不会互相污染可以按项目类型组合比如 Web 项目加载“组件开发技能”“测试技能”数据项目加载“迁移技能”“验证技能”技能可以被版本控制团队共享同一套标准。我实测下来最直观的感受是agent 的输出从“每次都不一样”变成了“每次都在预期范围内”。以前让它写个 API它可能用 Express 也可能用 Fastify可能写测试也可能不写加载了对应技能之后它会先确认技术栈再按技能里定义的步骤走最后自动跑一遍检查清单。2.2 skills CLI 的设计取舍skills CLI 是整个项目的入口工具负责技能的安装、卸载、列表、更新。它的设计有几个值得说的取舍。第一它不绑定特定 agent。虽然当前生态里 Claude Code 是主要使用者但 skills CLI 本身是通用的技能目录结构也是开放的。这意味着你可以在 Claude Code 里用也可以在支持类似机制的其他 agent 里用。这个选择很聪明——工具链不锁死生态才能长起来。第二它用文件系统做状态管理。技能安装就是往指定目录写文件卸载就是删文件没有数据库、没有服务端。这种“笨办法”的好处是透明、可审计、可手动干预。你随时可以打开技能目录看里面到底写了什么也可以手动改一个技能来适配自己的项目。我踩过的一个坑是早期版本卸载技能时没清理干净缓存导致重新安装后行为异常后来发现是缓存目录里残留了旧文件手动删掉就好了。所以现在养成了习惯装完技能先ls一下目录确认文件结构符合预期。第三它支持技能组合与覆盖。你可以装一个基础技能包再装一个项目专属技能包后者可以覆盖前者的某些步骤。这个机制在团队协作里特别有用公司级技能定义通用规范项目级技能定义项目特有流程agent 执行时按优先级合并。2.3 test-driven-development 为什么被放在核心位置在 agent-skills 内置的技能里test-driven-development 是我用得最多、也最推荐新手优先掌握的一个。原因很简单AI agent 最大的问题是“自信地写错代码”。它不会告诉你“我不确定”它会直接给你一段看起来对但实际有问题的实现。TDD 技能通过强制“先写测试、再写实现、最后重构”的流程把验证环节前置让 agent 在写实现之前就必须想清楚输入输出是什么。这个技能的具体约束包括接到需求后先写一个会失败的测试运行测试确认它确实失败写最少的实现让测试通过运行测试确认通过重构代码同时保持测试通过。每一步都有明确的检查点agent 不能跳步。我实测下来加载 TDD 技能后agent 一次通过率从大概 40% 提升到了 75% 以上返工时间大幅减少。3. 核心细节解析与实操要点3.1 技能目录结构长什么样一个标准的 agent-skill 目录通常包含这几个文件my-skill/ ├── SKILL.md # 技能主描述文件 ├── checklist.md # 执行检查清单 ├── examples/ # 示例输入输出 │ ├── input.md │ └── output.md └── scripts/ # 辅助脚本可选 └── validate.shSKILL.md是核心里面定义了技能名称、适用场景、触发条件、执行步骤、注意事项。我建议写这个文件时遵循一个原则把 agent 当成一个聪明但没经验的新人。步骤要具体到“运行什么命令、看什么输出、判断什么条件”不要写“确保代码质量”这种模糊表述。checklist.md是执行完之后的验收清单。比如 TDD 技能的检查清单包括测试是否先于实现编写、测试是否曾经失败过、实现是否是最小化的、所有测试是否通过、是否有重构空间。agent 每完成一步就勾选一项最后确认全部通过才算完成。examples/目录放几个典型场景的输入输出示例帮助 agent 理解技能的实际应用。这个目录不是必须的但有示例的技能agent 执行准确率明显更高。3.2 安装与配置的实操步骤假设你已经装好了 Claude Code接下来安装 agent-skills 的流程大致如下。注意不同版本命令可能有差异以你实际安装的版本为准。第一步确认 skills CLI 可用。在终端运行skills --version如果提示命令不存在说明 CLI 还没装或者没加到 PATH 里。Windows 用户特别注意安装后可能需要重启终端或者手动把安装目录加到环境变量。第二步查看可用技能列表。运行skills list --available会列出官方仓库里所有可安装的技能。我建议新手先装test-driven-development和code-review这两个一个管写代码一个管检查代码。第三步安装技能。运行skills install test-driven-developmentCLI 会把技能文件下载到本地技能目录。默认目录通常在用户主目录下的.agent-skills/里具体路径可以用skills config查看。第四步验证安装。运行skills list --installed确认技能出现在已安装列表里。然后打开技能目录检查SKILL.md内容是否完整。第五步在 Claude Code 里启用技能。这一步不同版本配置方式不同常见做法是在项目根目录的配置文件里声明要加载的技能或者在启动 Claude Code 时通过参数指定。我个人的习惯是在项目里放一个.claude/skills.json里面列出这个项目需要的技能这样换项目时自动切换技能组合。注意安装技能后一定要重启 Claude Code 会话否则新技能不会生效。我因为这个坑浪费过半小时一直以为技能没装好其实是会话没刷新。3.3 技能触发的判断逻辑agent 怎么知道什么时候该用哪个技能这取决于技能定义里的触发条件。以 TDD 技能为例触发条件通常写成“当用户要求实现新功能、修复 bug、或重构代码时触发”。agent 接到任务后会先匹配触发条件匹配成功才加载技能流程。这里有个实操技巧触发条件要写得具体但不要太窄。写得太窄很多场景匹配不上技能形同虚设写得太宽agent 在不该用的时候也用反而拖慢速度。我的经验是一个技能覆盖 3 到 5 类典型场景比较合适。比如 TDD 技能覆盖“新功能实现、bug 修复、重构、接口变更”这四类基本涵盖了日常开发的大部分编码任务。另外多个技能同时触发时要有优先级。比如“代码审查”技能和“TDD”技能可能同时匹配一个任务这时候应该先执行 TDD 流程完成后再执行代码审查。优先级可以在技能配置里定义数字越小优先级越高。3.4 技能与项目上下文的结合技能是通用的但项目是具体的。agent-skills 允许技能读取项目上下文来调整行为。比如 TDD 技能里可以定义“测试框架优先使用项目已有的测试框架如果项目里没有测试框架则询问用户选择”。这样同一个技能在不同项目里都能用不需要为每个项目写一套技能。我建议在项目根目录放一个project-context.md里面写清楚技术栈、测试命令、代码规范、目录结构约定。技能执行时会读取这个文件agent 的行为就更贴合项目实际。这个文件不用写太长一页以内足够关键是准确。4. 实操过程与核心环节实现4.1 从零开始用 TDD 技能实现一个功能模块假设我们要实现一个“用户注册”功能后端用 Node.js Express数据库用 PostgreSQL测试框架用 Jest。以下是加载 TDD 技能后的完整实操流程。第一步需求澄清。agent 接到“实现用户注册功能”这个需求后不会直接写代码而是先问几个问题注册需要哪些字段密码有什么强度要求是否需要邮箱验证重复邮箱怎么处理这一步很关键很多返工都是因为需求没澄清就动手。我实测下来agent 问的问题通常比我自己想的还全面尤其是边界条件。第二步写失败测试。agent 会在tests/目录下创建register.test.js写一个测试用例调用注册接口传入合法邮箱和密码期望返回 201 状态码和用户信息。然后运行npm test确认测试失败因为实现还不存在。这一步的检查点是测试必须失败而且失败原因必须是“功能未实现”而不是“语法错误”或“导入错误”。第三步写最小实现。agent 创建routes/register.js写一个最简单的实现让测试通过。注意是“最小实现”不是“完整实现”。比如先不处理重复邮箱、不加密密码、不验证邮箱格式只保证合法输入能返回 201。然后运行测试确认通过。第四步补充测试用例。测试通过后agent 会继续补充边界测试重复邮箱返回 409、密码太短返回 400、邮箱格式错误返回 400、缺少字段返回 400。每补充一个测试先确认它失败再修改实现让它通过。这个循环会重复多次直到所有边界条件都覆盖。第五步重构。所有测试通过后agent 会检查代码是否有重复、是否有更清晰的写法。比如把密码加密逻辑抽成独立函数、把验证逻辑抽成中间件。每次重构后都运行全部测试确保没有破坏已有功能。第六步运行检查清单。最后 agent 会逐项确认 TDD 检查清单测试是否先于实现、测试是否曾经失败、实现是否最小化、所有测试是否通过、是否有重构。全部通过后任务才算完成。整个流程走下来我统计过时间比直接让 agent 写实现大概多花 30% 的时间但返工时间减少了 70% 以上。尤其是需求变更时有测试覆盖的代码改起来放心得多。4.2 技能组合实战TDD 代码审查单独用 TDD 技能已经能大幅提升质量但加上代码审查技能效果更好。代码审查技能的触发条件是“当代码实现完成、测试通过后触发”它会自动检查几个维度命名是否清晰、函数是否过长、是否有重复代码、错误处理是否完善、是否有安全隐患。我实测的一个场景是agent 用 TDD 写完注册功能后代码审查技能自动触发指出“密码加密用了 MD5不安全建议用 bcrypt”。这个建议很及时如果等到上线前才发现改起来就麻烦了。另一个场景是审查技能发现“错误处理里直接返回了数据库错误信息可能泄露敏感信息”这也是人工审查容易忽略的点。两个技能组合使用时执行顺序很重要。我的配置是TDD 优先级 10代码审查优先级 20。agent 先走完 TDD 流程再走代码审查流程。如果代码审查发现问题会回到 TDD 流程修复修复后再审查直到通过。4.3 参数选择与配置细节技能配置里有几个参数值得细说。超时时间每个技能步骤可以设置超时默认是 300 秒。如果某个步骤经常超时比如运行大型测试套件可以调大到 600 秒。但不要设太大否则 agent 卡住时你等太久。重试次数测试失败后 agent 自动重试的次数默认 3 次。我建议保持默认因为重试太多次说明实现思路有问题应该人工介入而不是让 agent 反复试。日志级别调试技能时把日志级别调到 debug可以看到 agent 每一步的决策过程。平时用 info 级别就够了debug 日志太多反而干扰。技能目录路径默认在用户主目录下但团队协作时建议改成项目内目录比如.agent-skills/这样技能配置可以跟项目一起提交到版本控制团队成员共享同一套技能。提示修改技能配置后记得运行skills reload让配置生效不需要重启整个会话。4.4 技能的自定义与扩展官方技能不可能覆盖所有场景自定义技能是常态。我自定义过一个“数据库迁移技能”专门处理 schema 变更。技能步骤包括先写迁移文件、再写回滚文件、在测试库运行迁移、验证数据完整性、在预发库运行、最后在生产库运行。每一步都有检查点尤其是回滚文件必须测试通过才能继续。写自定义技能时我的经验是先手动做一遍把每一步的命令和判断条件记下来再整理成技能文件。不要凭空想象流程那样写出来的技能往往不实用。另外自定义技能要写清楚“不适用场景”比如数据库迁移技能不适用于数据修复数据修复应该走另一个技能。5. 常见问题与排查技巧实录5.1 技能不生效的排查思路技能装了但 agent 不用这是最常见的问题。排查顺序如下第一确认技能已安装且在已安装列表里。运行skills list --installed如果技能不在列表里说明安装失败重新安装。第二确认会话已刷新。安装技能后必须重启 Claude Code 会话否则技能不会加载。这个坑我踩过多次现在养成了装完技能就重启的习惯。第三确认触发条件匹配。打开SKILL.md看触发条件是否覆盖你当前的任务类型。如果任务类型不在触发条件里agent 不会加载技能。解决办法是修改触发条件或者手动指定技能。第四确认技能优先级。多个技能同时匹配时优先级低的可能被跳过。检查技能配置里的优先级数字确保目标技能优先级足够高。第五查看 agent 日志。把日志级别调到 debug看 agent 在决策时是否考虑了目标技能以及为什么没选中。日志里通常会有明确的原因。5.2 测试频繁失败的应对策略TDD 技能下测试频繁失败通常有三个原因。一是测试本身写错了。agent 写的测试可能断言条件不对比如期望 200 但实际应该 201。解决办法是人工审查测试用例确认断言条件正确。二是实现思路有问题。agent 可能选了一个不适合当前项目的实现方式导致测试一直不过。这时候应该人工介入给 agent 更明确的实现方向或者换一个技能流程。三是环境问题。测试依赖的数据库没启动、环境变量没配置、依赖包没安装都会导致测试失败。解决办法是先手动运行一次测试命令确认环境没问题再让 agent 执行。我整理了一个速查表问题现象可能原因排查方法解决方式技能装了但不用会话未刷新重启会话重启 Claude Code技能装了但不用触发条件不匹配查看 SKILL.md修改触发条件技能装了但不用优先级太低查看技能配置调高优先级测试一直失败测试断言错误人工审查测试修正断言条件测试一直失败实现思路不对查看 agent 日志人工指定实现方向测试一直失败环境问题手动运行测试修复环境配置技能执行超时步骤太复杂查看日志拆分技能步骤技能执行超时超时设置太短查看配置调大超时时间5.3 技能冲突的处理经验多个技能同时触发时可能冲突。比如 TDD 技能要求“先写测试”而某个快速原型技能要求“先写实现快速验证”两者流程矛盾。处理原则是明确优先级高优先级技能覆盖低优先级技能。如果冲突频繁说明技能划分有问题应该重新设计技能边界让每个技能覆盖的场景更清晰。我遇到过一次冲突代码审查技能和格式化技能同时触发审查技能要求“不要自动修改代码只提建议”格式化技能要求“自动格式化代码”。两个技能打架agent 行为混乱。解决办法是把格式化技能的触发条件改成“代码审查通过后触发”这样就不会同时执行了。5.4 技能更新的注意事项技能更新后已安装的旧版本不会自动替换。需要先卸载旧版本再安装新版本。卸载命令是skills uninstall skill-name安装命令是skills install skill-name。更新前建议先备份自定义的技能配置避免更新后配置丢失。另外技能更新可能改变触发条件或执行步骤导致之前能用的场景现在不匹配了。更新后建议跑一遍典型场景确认行为符合预期。我一般会在更新后跑三个场景新功能实现、bug 修复、代码审查确认都没问题才继续用。6. 技能生态的扩展玩法与个人体会6.1 把技能当成团队知识库来维护agent-skills 最有价值的扩展玩法是把它当成团队知识库。每个技能文件其实就是一份“怎么做某件事”的文档只不过读者是 agent 而不是人。团队里谁踩过坑、谁总结出好流程都可以写成技能文件让 agent 自动执行。我们团队现在的做法是每个季度回顾一次把重复出现的问题整理成技能。比如“数据库迁移经常忘记写回滚文件”就写一个迁移技能强制要求回滚文件比如“API 接口经常忘记加限流”就写一个接口开发技能把限流作为检查项。半年下来积累了十几个自定义技能新人入职时直接装技能包agent 的行为就自动符合团队规范了。6.2 技能与 CI/CD 的结合技能不仅能约束 agent 的编码行为还能和 CI/CD 流程结合。比如在 CI 里加一步“技能检查”确认提交的代码符合技能定义的规范。如果不符合CI 失败提示开发者用对应技能重新处理。我试过的一个方案是在 pre-commit hook 里调用 skills CLI检查当前变更是否触发了某个技能如果触发了但没执行就提示开发者。这个方案还在实验阶段但初步效果不错能减少“忘记走流程”的情况。6.3 我个人的使用节奏最后分享我个人的使用节奏供参考。日常开发时我常驻加载 TDD 技能和代码审查技能这两个覆盖了大部分编码任务。遇到特定场景时临时加载对应技能比如数据库变更时加载迁移技能部署时加载部署技能。每周花半小时回顾技能日志看哪些技能经常触发、哪些技能从没触发过没触发过的技能要么删掉要么修改触发条件。踩过几次坑之后我最大的体会是技能不是越多越好而是越准越好。装一堆技能但都不生效不如装两三个但每个都精准匹配。另外技能要定期维护项目技术栈变了、团队规范变了技能也要跟着更新否则 agent 会按过时的流程执行反而添乱。这个内容后续还可以这样扩展把技能和项目模板结合新建项目时自动加载对应技能包或者把技能和代码生成工具结合生成代码时自动带上技能约束。这些方向我还在探索有进展再分享。