1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新同事来培养的技能体系。项目正文和关键词都是空的但热搜词已经把方向交代得很清楚了——agent-skills、AI coding agents、skills CLI、Claude Code、test-driven-development。这几个词放在一起指向一个非常具体的场景你已经在用 Claude Code 这类终端里的 AI 编程代理干活了但发现它时好时坏于是想给它装一套技能包让它稳定地按你的工程规范做事。这件事的价值在哪我举个自己的例子。刚开始用 Claude Code 的时候我让它写一个带分页的查询接口它给我返回了一段能跑但完全不符合项目分层规范的代码——controller 里直接拼 SQL异常处理全靠 try-catch 包一层测试一个没有。我改了三遍它每次都能理解我的意思但下次换个任务又回到老样子。问题不在于模型笨而在于它不知道我的项目里什么叫做好代码。agent-skills要解决的就是这个问题把团队的工程习惯、测试规范、代码风格沉淀成 agent 可以加载和执行的技能让它的行为从随机发挥变成按规矩办事。所以这篇内容适合三类人看一是已经在用 Claude Code 或类似 AI coding agent、但被它的不稳定性折磨过的开发者二是想给团队引入 AI 编程代理、但担心代码质量失控的技术负责人三是单纯好奇skills CLI 到底是个什么东西、值不值得折腾的观望者。我会从技能的本质讲起一路讲到怎么落地、怎么避坑尽量把每个为什么都说透。2. agent-skills 到底解决了 AI 编程代理的哪个痛点2.1 为什么提示词救不了工程一致性大多数人接触 AI 编程代理的第一反应是写提示词。项目根目录放一个CLAUDE.md把用 TypeScript 严格模式所有函数必须写单元测试禁止 any这些规则列上去。我一开始也这么干效果有但很有限。原因很简单提示词是建议不是约束。模型在上下文里看到这些规则会尽量遵守但当任务变复杂、上下文变长、或者它觉得这样写更快的时候规则就被稀释掉了。更麻烦的是提示词是扁平的。你把二十条规则堆在一个文件里模型没法判断哪条在什么场景下优先。比如快速原型阶段可以跳过测试和所有代码必须有测试这两条如果同时存在模型就懵了。而agent-skills的思路是把技能结构化每个技能是一个独立的单元有自己的触发条件、执行步骤、验证标准。这就像从给新员工发一本员工手册升级成给新员工一套标准作业程序SOP每个任务对应一份。2.2 技能Skill和提示词Prompt的本质区别我用一个类比来说明。提示词像是你口头跟装修师傅说帮我装个厨房要好看点。技能像是你递给他一份图纸水电走线在哪、瓷砖用什么规格、验收标准是什么、哪一步做完要拍照确认。区别不在于信息量而在于可执行性和可验证性。具体到agent-skills的语境里一个技能通常包含几个要素名称与描述让 agent 知道这个技能是干什么的、触发条件什么情况下该用这个技能、执行指令具体怎么做往往是分步骤的、验证方式怎么确认做对了。热搜词里出现的test-driven-development就是一个典型的技能——它不是一句要写测试而是一套流程先写失败的测试、再写最小实现让测试通过、最后重构。这套流程被固化成一个技能后agent 每次遇到实现新功能的任务就会自动走这个流程而不是随机决定要不要写测试。2.3 skills CLI把技能变成可管理的资产skills CLI这个词很关键。它意味着技能不是散落在各个项目里的 markdown 文件而是可以通过命令行安装、更新、组合的资产。这带来几个实际好处复用你在 A 项目里打磨好的API 设计技能可以直接装到 B 项目。版本管理技能可以像依赖一样锁定版本团队里每个人用的都是同一套。组合不同技能可以叠加比如TDD 技能代码审查技能提交信息规范技能。我实测下来这个 CLI 化的设计是agent-skills区别于普通提示词仓库的核心。它把 AI 编程代理的配置从手工活变成了工程活。3. 拆解一个 agent skill 的内部结构3.1 技能文件的骨架长什么样虽然输入里没有给出具体的技能文件格式但基于agent-skills这类项目的常见实践一个技能通常是一个目录里面至少有一个主描述文件多为 markdown 或 YAML可能还附带脚本、模板、示例。我按最常见的结构给你拆一下skills/ test-driven-development/ SKILL.md # 技能主描述名称、触发条件、执行步骤 templates/ # 可选的代码模板 examples/ # 可选的正反例SKILL.md是核心。它一般包含 frontmatter元数据和正文指令。元数据里最关键的是name和description——description 写得好不好直接决定 agent 能不能在正确的时机想起这个技能。这一点很多人会忽略后面我会专门讲。3.2 触发条件技能被想起来的机制AI 编程代理加载技能的方式通常是渐进式披露启动时只加载所有技能的名称描述很轻量当它判断当前任务和某个技能相关时才把那个技能的完整内容读进上下文。这个机制决定了描述写不清楚技能就等于不存在。我踩过这个坑。有一次我写了个技能叫数据库迁移规范描述写的是处理数据库相关变更。结果 agent 在需要改表结构的时候压根没触发这个技能直接手写了一段 ALTER TABLE。后来我把描述改成当需要新增/修改/删除数据库表结构、字段、索引时使用包含迁移文件命名、回滚脚本编写、生产环境变更检查清单它立刻就稳定触发了。描述里要包含什么时候用而不只是这是什么。3.3 执行指令把经验翻译成步骤技能正文的写法直接决定 agent 执行得稳不稳。我的经验是能写成有序步骤的就别写成段落。模型对编号步骤的遵循度明显高于散文式描述。而且每一步最好包含做什么和怎么验证。举个例子一个提交代码技能可能是这样运行git status确认改动范围如果有未预期的文件停下来询问。运行项目的 lint 和测试命令全部通过才继续。按 Conventional Commits 规范生成提交信息格式为type(scope): description。执行提交然后运行git log -1确认提交信息正确。每一步都有明确的动作和检查点。这比请规范地提交代码有用一百倍。3.4 验证方式让 agent 自己检查作业这是agent-skills里最容易被低估的部分。好的技能不只是告诉 agent怎么做还告诉它怎么知道自己做对了。比如 TDD 技能的验证方式是测试先失败、再通过代码审查技能的验证方式是对照检查清单逐项确认。我个人的做法是在每个技能末尾加一个完成标准小节用 checklist 的形式列出。agent 在结束任务前会对照这个清单自查能挡掉相当一部分低级错误。4. 把 agent-skills 接进 Claude Code 的完整流程4.1 环境准备先确认你的 agent 能读技能在动手之前得先确认你的 Claude Code 环境是通的。热搜词里有一堆关于安装、配置、版本升级的问题我按最常见的路径说。Claude Code 的安装方式在不同系统上略有差异macOS 和 Ubuntu 上通常通过包管理器或官方脚本安装VS Code 用户则可以通过插件接入。安装完成后用claude --version确认版本用claude进入交互模式跑一个简单任务确认模型能正常响应。注意如果你所在的环境访问官方服务受限可以关注 Claude Code 是否支持通过配置接入其他兼容模型的方式。具体以官方文档为准不要轻信来路不明的第三方脚本。环境通了之后关键是确认你的 Claude Code 版本支持技能加载。技能机制是较新版本才引入的能力老版本可能读不到skills目录。升级到最新版本是最省事的做法。4.2 安装 skills CLI 与初始化技能目录skills CLI的安装通常通过包管理器完成。以常见的 Node 生态为例# 全局安装 skills CLI具体包名以项目文档为准 npm install -g skills-cli # 在项目里初始化技能目录 skills init初始化后项目里会多出一个skills/目录或者.agent-skills/取决于工具约定。这个目录就是你和 agent 之间的契约区。我建议把它纳入版本控制这样团队每个人拉下来的技能集是一致的。如果你不想用 CLI也可以手动创建目录结构。CLI 的价值主要在于安装、更新、组合第三方技能纯手写技能的话手动建目录也能跑。4.3 从零写第一个技能以 TDD 为例我拿test-driven-development这个热搜词里的技能做示范。假设我要写一个让 agent 严格走 TDD 流程的技能--- name: test-driven-development description: 当需要实现新功能、修复 bug 或重构代码时使用。强制先写测试再写实现确保每一步都有测试覆盖。 --- # 测试驱动开发 ## 执行步骤 1. 理解需求用一句话写出这个功能/修复的验收标准。 2. 编写一个会失败的测试运行它确认它确实失败红。 3. 编写让测试通过的最小实现不要提前优化。 4. 运行测试确认通过绿。 5. 在测试保护下重构代码每次重构后重跑测试。 6. 重复 2-5 直到需求完成。 ## 完成标准 - [ ] 每个新增行为都有对应测试 - [ ] 测试曾经真实失败过不是写完实现补的测试 - [ ] 所有测试通过 - [ ] 没有为了通过测试而写的硬编码这个技能的关键在于步骤 2 的确认它确实失败。很多人写 TDD 会跳过这一步结果测试写错了也不知道。强制 agent 确认红的状态能挡掉大量假测试。4.4 验证技能是否真的生效写完技能不等于生效。我一般用三步验证触发测试给 agent 一个明确属于该技能范围的任务看它有没有加载技能。可以在对话里问它你现在用了哪些技能。流程测试观察它的执行顺序是否符合技能定义。比如 TDD 技能看它是不是先写测试。边界测试给一个模糊任务看它会不会误触发。误触发比不触发更烦人。如果技能没触发九成是 description 写得不够具体。回去改描述把什么时候用写清楚。5. 技能设计里那些文档不会告诉你的坑5.1 技能不是越多越好我一开始很兴奋一口气写了十几个技能命名规范、注释规范、日志规范、错误处理规范……结果 agent 变得畏手畏脚每个任务都要加载一堆技能上下文被塞满反而变慢了而且技能之间开始打架。比如注释规范要求详细注释简洁代码技能要求少写注释agent 就卡在那纠结。后来我砍到五个核心技能只保留那些高频、高价值、容易出错的场景。判断标准很简单这个技能如果不用agent 犯错的概率高不高犯错代价大不大两个都高才值得写成技能。5.2 技能之间会冲突得设计优先级技能冲突是真实存在的。除了上面说的注释问题还有快速原型和完整测试覆盖的冲突。解决办法有两个一是在技能里写明适用边界比如本技能仅用于生产代码原型代码不适用二是设计技能的组合规则明确哪个技能优先。我在实践中的做法是给每个技能加一个priority字段或者在项目级的配置里声明技能加载顺序。当两个技能冲突时高优先级的说了算。5.3 描述写得太聪明反而触发不了这是个反直觉的坑。我见过有人把技能描述写得特别精炼比如优化代码质量。结果 agent 完全不知道什么时候该用。描述要笨一点把具体场景、关键词都列出来。宁可啰嗦不要含蓄。因为 agent 是靠语义匹配来触发技能的你写得越具体匹配越准。5.4 技能要跟着项目演进别写完就不管技能是活的。项目重构了目录结构变了技能里的路径引用就失效了。我建议把技能维护纳入日常流程每次项目有大的架构调整顺手检查一遍相关技能。可以给技能加个last_verified字段记录上次确认有效的时间超过三个月就复查一遍。6. 让技能真正提升代码质量的几个进阶玩法6.1 把代码审查做成可执行的技能代码审查是最值得技能化的场景之一。我写过一个提交前自审技能让 agent 在提交前对照清单检查有没有调试代码残留、有没有硬编码的密钥、异常处理是否完整、测试是否覆盖新增逻辑。这个技能跑下来挡掉过好几次我差点提交的console.log和临时写死的 token。关键在于清单要可判定。代码质量高这种没法判定没有 console.log可以判定。每条检查项都要能用是/否回答。6.2 用技能固化团队的隐性知识每个团队都有一堆没写进文档的规矩这个模块的改动要通知谁、那个配置改了要同步哪个环境、某个接口的限流阈值是多少。这些隐性知识以前靠口口相传新人踩坑才能学会。把它们写成技能后agent 在相关任务里会自动提醒相当于给团队配了个不会忘事的老人。我特别推荐把上线检查清单做成技能。上线前要确认的东西太多人脑记不住agent 照着清单走一遍稳得多。6.3 技能 测试让 agent 的产出可验证热搜词里test-driven-development和agent-skills同时出现不是偶然。测试是验证 agent 产出最可靠的手段。你把 TDD 技能和项目的测试套件结合起来agent 每写一段代码测试就跑一遍错了立刻发现。这比人肉 review 高效得多。我的做法是在技能里直接引用项目的测试命令让 agent 每完成一个步骤就自动跑测试。测试通过才进入下一步。这样 agent 的产出天然带着已验证的标签。6.4 技能的版本化与团队共享技能既然是资产就该像代码一样管理。用 git 管理skills/目录每次修改走 PR 流程让团队 review。这样技能的质量有保障变更也有记录。如果团队规模大可以建一个内部的技能仓库各项目按需引用。我见过做得好的团队会把技能分成通用技能如 TDD、提交规范和项目技能如本项目的 API 约定两层。通用技能从内部仓库统一拉取项目技能放在项目里。这样既保证了规范统一又保留了项目灵活性。7. 关于 agent-skills 的几个常见疑问7.1 不用 Claude Code这套东西能用吗能。agent-skills的核心是技能这个抽象它不绑定特定工具。只要你的 AI 编程代理支持加载外部指令文件就能用类似的思路。区别只在于加载机制和文件格式。所以即使你用的是别的 agent理解技能的设计思路也有价值。7.2 技能和 MCP、插件是什么关系这是三个不同层次的东西。MCPModel Context Protocol解决的是agent 能访问什么外部资源插件解决的是agent 能调用什么工具而技能解决的是agent 该怎么做一件事。打个比方MCP 是给 agent 接通了数据库插件是给了它一把螺丝刀技能是告诉它修这个型号的机器要按这个顺序拧螺丝。三者互补不冲突。7.3 技能会不会让 agent 变死板会如果你写得太死。技能的目的是保证关键流程的一致性不是限制 agent 的所有行为。我的原则是流程性的事情用技能固化创造性的事情留给 agent 发挥。比如先写测试是流程固化这个功能怎么设计是创造放开。把握好这个度agent 既稳定又灵活。7.4 小项目值得搞技能吗看情况。如果项目就你一个人、代码量不大、你也不打算长期维护那写技能的时间可能不如直接改代码。但如果你打算长期用 AI 编程代理哪怕小项目写两三个核心技能也是划算的——因为技能是可以复用到下一个项目的。技能的投入是一次性的收益是跨项目的。8. 我踩过的几个真实坑以及怎么绕过去说几个具体的。第一个坑是技能目录位置放错。我一开始把skills/放在了项目子目录里结果 agent 在项目根目录启动时读不到。后来才知道技能目录要放在 agent 的工作根目录下或者通过配置显式指定路径。这个坑排查了我半小时因为 agent 不会报错说找不到技能它只是默默地不用。第二个坑是技能里的命令写死了绝对路径。我在技能里写了cd /Users/myname/project npm test换台机器就废了。正确做法是用相对路径或者用项目里定义的脚本别名如npm test让技能和环境解耦。第三个坑是技能描述里的关键词和实际任务对不上。我写了个技能叫处理 API 错误但实际任务里我说的是接口报错了怎么兜底语义匹配没对上技能没触发。后来我在描述里把接口报错兜底异常这些词都加进去触发率立刻上来了。描述要覆盖用户可能用的各种说法而不是你自己习惯的说法。第四个坑是技能更新后没重启 agent。有些 agent 会缓存技能列表改了技能文件不重启不生效。我改了半天描述纳闷为什么没反应重启一下就好了。这个坑不致命但很浪费时间养成改完技能就重启的习惯。9. 从 agent-skills 看 AI 编程代理的下一步用了一段时间agent-skills之后我最大的感受是AI 编程代理的竞争正在从模型多聪明转向工程化多成熟。模型能力大家都能买到但怎么让模型稳定地、可复现地、符合团队规范地干活这是每个团队要自己解决的问题。技能体系就是这个问题的一个解法。我个人的判断是未来技能库会像现在的依赖库一样普遍。你新起一个项目除了npm install还会skills install一套团队标准技能。新人入职除了配环境还会同步技能库。这个趋势已经能看到了。最后分享一个我自己的小习惯每次 agent 犯了重复性的错误我不会只改这一次的代码而是问自己这个错误能不能用技能挡掉。如果能就顺手写个技能。这样积累下来agent 犯的错越来越少我的技能库越来越厚。这个正循环是我用agent-skills最大的收获。 agent-skills 实战：用技能体系驯服 AI 编程代理
1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新同事来培养的技能体系。项目正文和关键词都是空的但热搜词已经把方向交代得很清楚了——agent-skills、AI coding agents、skills CLI、Claude Code、test-driven-development。这几个词放在一起指向一个非常具体的场景你已经在用 Claude Code 这类终端里的 AI 编程代理干活了但发现它时好时坏于是想给它装一套技能包让它稳定地按你的工程规范做事。这件事的价值在哪我举个自己的例子。刚开始用 Claude Code 的时候我让它写一个带分页的查询接口它给我返回了一段能跑但完全不符合项目分层规范的代码——controller 里直接拼 SQL异常处理全靠 try-catch 包一层测试一个没有。我改了三遍它每次都能理解我的意思但下次换个任务又回到老样子。问题不在于模型笨而在于它不知道我的项目里什么叫做好代码。agent-skills要解决的就是这个问题把团队的工程习惯、测试规范、代码风格沉淀成 agent 可以加载和执行的技能让它的行为从随机发挥变成按规矩办事。所以这篇内容适合三类人看一是已经在用 Claude Code 或类似 AI coding agent、但被它的不稳定性折磨过的开发者二是想给团队引入 AI 编程代理、但担心代码质量失控的技术负责人三是单纯好奇skills CLI 到底是个什么东西、值不值得折腾的观望者。我会从技能的本质讲起一路讲到怎么落地、怎么避坑尽量把每个为什么都说透。2. agent-skills 到底解决了 AI 编程代理的哪个痛点2.1 为什么提示词救不了工程一致性大多数人接触 AI 编程代理的第一反应是写提示词。项目根目录放一个CLAUDE.md把用 TypeScript 严格模式所有函数必须写单元测试禁止 any这些规则列上去。我一开始也这么干效果有但很有限。原因很简单提示词是建议不是约束。模型在上下文里看到这些规则会尽量遵守但当任务变复杂、上下文变长、或者它觉得这样写更快的时候规则就被稀释掉了。更麻烦的是提示词是扁平的。你把二十条规则堆在一个文件里模型没法判断哪条在什么场景下优先。比如快速原型阶段可以跳过测试和所有代码必须有测试这两条如果同时存在模型就懵了。而agent-skills的思路是把技能结构化每个技能是一个独立的单元有自己的触发条件、执行步骤、验证标准。这就像从给新员工发一本员工手册升级成给新员工一套标准作业程序SOP每个任务对应一份。2.2 技能Skill和提示词Prompt的本质区别我用一个类比来说明。提示词像是你口头跟装修师傅说帮我装个厨房要好看点。技能像是你递给他一份图纸水电走线在哪、瓷砖用什么规格、验收标准是什么、哪一步做完要拍照确认。区别不在于信息量而在于可执行性和可验证性。具体到agent-skills的语境里一个技能通常包含几个要素名称与描述让 agent 知道这个技能是干什么的、触发条件什么情况下该用这个技能、执行指令具体怎么做往往是分步骤的、验证方式怎么确认做对了。热搜词里出现的test-driven-development就是一个典型的技能——它不是一句要写测试而是一套流程先写失败的测试、再写最小实现让测试通过、最后重构。这套流程被固化成一个技能后agent 每次遇到实现新功能的任务就会自动走这个流程而不是随机决定要不要写测试。2.3 skills CLI把技能变成可管理的资产skills CLI这个词很关键。它意味着技能不是散落在各个项目里的 markdown 文件而是可以通过命令行安装、更新、组合的资产。这带来几个实际好处复用你在 A 项目里打磨好的API 设计技能可以直接装到 B 项目。版本管理技能可以像依赖一样锁定版本团队里每个人用的都是同一套。组合不同技能可以叠加比如TDD 技能代码审查技能提交信息规范技能。我实测下来这个 CLI 化的设计是agent-skills区别于普通提示词仓库的核心。它把 AI 编程代理的配置从手工活变成了工程活。3. 拆解一个 agent skill 的内部结构3.1 技能文件的骨架长什么样虽然输入里没有给出具体的技能文件格式但基于agent-skills这类项目的常见实践一个技能通常是一个目录里面至少有一个主描述文件多为 markdown 或 YAML可能还附带脚本、模板、示例。我按最常见的结构给你拆一下skills/ test-driven-development/ SKILL.md # 技能主描述名称、触发条件、执行步骤 templates/ # 可选的代码模板 examples/ # 可选的正反例SKILL.md是核心。它一般包含 frontmatter元数据和正文指令。元数据里最关键的是name和description——description 写得好不好直接决定 agent 能不能在正确的时机想起这个技能。这一点很多人会忽略后面我会专门讲。3.2 触发条件技能被想起来的机制AI 编程代理加载技能的方式通常是渐进式披露启动时只加载所有技能的名称描述很轻量当它判断当前任务和某个技能相关时才把那个技能的完整内容读进上下文。这个机制决定了描述写不清楚技能就等于不存在。我踩过这个坑。有一次我写了个技能叫数据库迁移规范描述写的是处理数据库相关变更。结果 agent 在需要改表结构的时候压根没触发这个技能直接手写了一段 ALTER TABLE。后来我把描述改成当需要新增/修改/删除数据库表结构、字段、索引时使用包含迁移文件命名、回滚脚本编写、生产环境变更检查清单它立刻就稳定触发了。描述里要包含什么时候用而不只是这是什么。3.3 执行指令把经验翻译成步骤技能正文的写法直接决定 agent 执行得稳不稳。我的经验是能写成有序步骤的就别写成段落。模型对编号步骤的遵循度明显高于散文式描述。而且每一步最好包含做什么和怎么验证。举个例子一个提交代码技能可能是这样运行git status确认改动范围如果有未预期的文件停下来询问。运行项目的 lint 和测试命令全部通过才继续。按 Conventional Commits 规范生成提交信息格式为type(scope): description。执行提交然后运行git log -1确认提交信息正确。每一步都有明确的动作和检查点。这比请规范地提交代码有用一百倍。3.4 验证方式让 agent 自己检查作业这是agent-skills里最容易被低估的部分。好的技能不只是告诉 agent怎么做还告诉它怎么知道自己做对了。比如 TDD 技能的验证方式是测试先失败、再通过代码审查技能的验证方式是对照检查清单逐项确认。我个人的做法是在每个技能末尾加一个完成标准小节用 checklist 的形式列出。agent 在结束任务前会对照这个清单自查能挡掉相当一部分低级错误。4. 把 agent-skills 接进 Claude Code 的完整流程4.1 环境准备先确认你的 agent 能读技能在动手之前得先确认你的 Claude Code 环境是通的。热搜词里有一堆关于安装、配置、版本升级的问题我按最常见的路径说。Claude Code 的安装方式在不同系统上略有差异macOS 和 Ubuntu 上通常通过包管理器或官方脚本安装VS Code 用户则可以通过插件接入。安装完成后用claude --version确认版本用claude进入交互模式跑一个简单任务确认模型能正常响应。注意如果你所在的环境访问官方服务受限可以关注 Claude Code 是否支持通过配置接入其他兼容模型的方式。具体以官方文档为准不要轻信来路不明的第三方脚本。环境通了之后关键是确认你的 Claude Code 版本支持技能加载。技能机制是较新版本才引入的能力老版本可能读不到skills目录。升级到最新版本是最省事的做法。4.2 安装 skills CLI 与初始化技能目录skills CLI的安装通常通过包管理器完成。以常见的 Node 生态为例# 全局安装 skills CLI具体包名以项目文档为准 npm install -g skills-cli # 在项目里初始化技能目录 skills init初始化后项目里会多出一个skills/目录或者.agent-skills/取决于工具约定。这个目录就是你和 agent 之间的契约区。我建议把它纳入版本控制这样团队每个人拉下来的技能集是一致的。如果你不想用 CLI也可以手动创建目录结构。CLI 的价值主要在于安装、更新、组合第三方技能纯手写技能的话手动建目录也能跑。4.3 从零写第一个技能以 TDD 为例我拿test-driven-development这个热搜词里的技能做示范。假设我要写一个让 agent 严格走 TDD 流程的技能--- name: test-driven-development description: 当需要实现新功能、修复 bug 或重构代码时使用。强制先写测试再写实现确保每一步都有测试覆盖。 --- # 测试驱动开发 ## 执行步骤 1. 理解需求用一句话写出这个功能/修复的验收标准。 2. 编写一个会失败的测试运行它确认它确实失败红。 3. 编写让测试通过的最小实现不要提前优化。 4. 运行测试确认通过绿。 5. 在测试保护下重构代码每次重构后重跑测试。 6. 重复 2-5 直到需求完成。 ## 完成标准 - [ ] 每个新增行为都有对应测试 - [ ] 测试曾经真实失败过不是写完实现补的测试 - [ ] 所有测试通过 - [ ] 没有为了通过测试而写的硬编码这个技能的关键在于步骤 2 的确认它确实失败。很多人写 TDD 会跳过这一步结果测试写错了也不知道。强制 agent 确认红的状态能挡掉大量假测试。4.4 验证技能是否真的生效写完技能不等于生效。我一般用三步验证触发测试给 agent 一个明确属于该技能范围的任务看它有没有加载技能。可以在对话里问它你现在用了哪些技能。流程测试观察它的执行顺序是否符合技能定义。比如 TDD 技能看它是不是先写测试。边界测试给一个模糊任务看它会不会误触发。误触发比不触发更烦人。如果技能没触发九成是 description 写得不够具体。回去改描述把什么时候用写清楚。5. 技能设计里那些文档不会告诉你的坑5.1 技能不是越多越好我一开始很兴奋一口气写了十几个技能命名规范、注释规范、日志规范、错误处理规范……结果 agent 变得畏手畏脚每个任务都要加载一堆技能上下文被塞满反而变慢了而且技能之间开始打架。比如注释规范要求详细注释简洁代码技能要求少写注释agent 就卡在那纠结。后来我砍到五个核心技能只保留那些高频、高价值、容易出错的场景。判断标准很简单这个技能如果不用agent 犯错的概率高不高犯错代价大不大两个都高才值得写成技能。5.2 技能之间会冲突得设计优先级技能冲突是真实存在的。除了上面说的注释问题还有快速原型和完整测试覆盖的冲突。解决办法有两个一是在技能里写明适用边界比如本技能仅用于生产代码原型代码不适用二是设计技能的组合规则明确哪个技能优先。我在实践中的做法是给每个技能加一个priority字段或者在项目级的配置里声明技能加载顺序。当两个技能冲突时高优先级的说了算。5.3 描述写得太聪明反而触发不了这是个反直觉的坑。我见过有人把技能描述写得特别精炼比如优化代码质量。结果 agent 完全不知道什么时候该用。描述要笨一点把具体场景、关键词都列出来。宁可啰嗦不要含蓄。因为 agent 是靠语义匹配来触发技能的你写得越具体匹配越准。5.4 技能要跟着项目演进别写完就不管技能是活的。项目重构了目录结构变了技能里的路径引用就失效了。我建议把技能维护纳入日常流程每次项目有大的架构调整顺手检查一遍相关技能。可以给技能加个last_verified字段记录上次确认有效的时间超过三个月就复查一遍。6. 让技能真正提升代码质量的几个进阶玩法6.1 把代码审查做成可执行的技能代码审查是最值得技能化的场景之一。我写过一个提交前自审技能让 agent 在提交前对照清单检查有没有调试代码残留、有没有硬编码的密钥、异常处理是否完整、测试是否覆盖新增逻辑。这个技能跑下来挡掉过好几次我差点提交的console.log和临时写死的 token。关键在于清单要可判定。代码质量高这种没法判定没有 console.log可以判定。每条检查项都要能用是/否回答。6.2 用技能固化团队的隐性知识每个团队都有一堆没写进文档的规矩这个模块的改动要通知谁、那个配置改了要同步哪个环境、某个接口的限流阈值是多少。这些隐性知识以前靠口口相传新人踩坑才能学会。把它们写成技能后agent 在相关任务里会自动提醒相当于给团队配了个不会忘事的老人。我特别推荐把上线检查清单做成技能。上线前要确认的东西太多人脑记不住agent 照着清单走一遍稳得多。6.3 技能 测试让 agent 的产出可验证热搜词里test-driven-development和agent-skills同时出现不是偶然。测试是验证 agent 产出最可靠的手段。你把 TDD 技能和项目的测试套件结合起来agent 每写一段代码测试就跑一遍错了立刻发现。这比人肉 review 高效得多。我的做法是在技能里直接引用项目的测试命令让 agent 每完成一个步骤就自动跑测试。测试通过才进入下一步。这样 agent 的产出天然带着已验证的标签。6.4 技能的版本化与团队共享技能既然是资产就该像代码一样管理。用 git 管理skills/目录每次修改走 PR 流程让团队 review。这样技能的质量有保障变更也有记录。如果团队规模大可以建一个内部的技能仓库各项目按需引用。我见过做得好的团队会把技能分成通用技能如 TDD、提交规范和项目技能如本项目的 API 约定两层。通用技能从内部仓库统一拉取项目技能放在项目里。这样既保证了规范统一又保留了项目灵活性。7. 关于 agent-skills 的几个常见疑问7.1 不用 Claude Code这套东西能用吗能。agent-skills的核心是技能这个抽象它不绑定特定工具。只要你的 AI 编程代理支持加载外部指令文件就能用类似的思路。区别只在于加载机制和文件格式。所以即使你用的是别的 agent理解技能的设计思路也有价值。7.2 技能和 MCP、插件是什么关系这是三个不同层次的东西。MCPModel Context Protocol解决的是agent 能访问什么外部资源插件解决的是agent 能调用什么工具而技能解决的是agent 该怎么做一件事。打个比方MCP 是给 agent 接通了数据库插件是给了它一把螺丝刀技能是告诉它修这个型号的机器要按这个顺序拧螺丝。三者互补不冲突。7.3 技能会不会让 agent 变死板会如果你写得太死。技能的目的是保证关键流程的一致性不是限制 agent 的所有行为。我的原则是流程性的事情用技能固化创造性的事情留给 agent 发挥。比如先写测试是流程固化这个功能怎么设计是创造放开。把握好这个度agent 既稳定又灵活。7.4 小项目值得搞技能吗看情况。如果项目就你一个人、代码量不大、你也不打算长期维护那写技能的时间可能不如直接改代码。但如果你打算长期用 AI 编程代理哪怕小项目写两三个核心技能也是划算的——因为技能是可以复用到下一个项目的。技能的投入是一次性的收益是跨项目的。8. 我踩过的几个真实坑以及怎么绕过去说几个具体的。第一个坑是技能目录位置放错。我一开始把skills/放在了项目子目录里结果 agent 在项目根目录启动时读不到。后来才知道技能目录要放在 agent 的工作根目录下或者通过配置显式指定路径。这个坑排查了我半小时因为 agent 不会报错说找不到技能它只是默默地不用。第二个坑是技能里的命令写死了绝对路径。我在技能里写了cd /Users/myname/project npm test换台机器就废了。正确做法是用相对路径或者用项目里定义的脚本别名如npm test让技能和环境解耦。第三个坑是技能描述里的关键词和实际任务对不上。我写了个技能叫处理 API 错误但实际任务里我说的是接口报错了怎么兜底语义匹配没对上技能没触发。后来我在描述里把接口报错兜底异常这些词都加进去触发率立刻上来了。描述要覆盖用户可能用的各种说法而不是你自己习惯的说法。第四个坑是技能更新后没重启 agent。有些 agent 会缓存技能列表改了技能文件不重启不生效。我改了半天描述纳闷为什么没反应重启一下就好了。这个坑不致命但很浪费时间养成改完技能就重启的习惯。9. 从 agent-skills 看 AI 编程代理的下一步用了一段时间agent-skills之后我最大的感受是AI 编程代理的竞争正在从模型多聪明转向工程化多成熟。模型能力大家都能买到但怎么让模型稳定地、可复现地、符合团队规范地干活这是每个团队要自己解决的问题。技能体系就是这个问题的一个解法。我个人的判断是未来技能库会像现在的依赖库一样普遍。你新起一个项目除了npm install还会skills install一套团队标准技能。新人入职除了配环境还会同步技能库。这个趋势已经能看到了。最后分享一个我自己的小习惯每次 agent 犯了重复性的错误我不会只改这一次的代码而是问自己这个错误能不能用技能挡掉。如果能就顺手写个技能。这样积累下来agent 犯的错越来越少我的技能库越来越厚。这个正循环是我用agent-skills最大的收获。