1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新员工来培养的技能体系。关键词里同时出现了skills CLI、Claude Code、test-driven-development这三者放在一起指向一个很明确的方向——用命令行工具管理技能包让编码智能体按照测试驱动开发的节奏干活。先把概念对齐。所谓agent skills可以理解成给 AI 编码助手准备的岗位操作手册。它不是一段临时拼凑的 prompt而是结构化的、可复用的、带触发条件的技能单元。每个技能通常包含什么时候该用触发描述、用的时候要遵守什么流程步骤约束、产出物长什么样模板或校验规则。skills CLI则是管理这些技能单元的命令行入口负责安装、列出、启用、禁用、更新。为什么这件事值得单独拿出来讲因为大多数人用 AI 写代码的方式还停留在对话式许愿把需求丢过去等它吐代码跑不通再贴报错来回拉扯。这种方式在一次性脚本上还行一旦进入真实项目——有测试、有代码规范、有 CI 门禁——就会暴露出三个致命问题上下文漂移聊到后面忘了前面的约束、流程缺失跳过测试直接改实现、不可复现同样的需求两次结果不一样。agent-skills 想解决的正是这三件事。这篇文章适合谁看如果你已经在用 Claude Code 这类终端里的编码智能体但总觉得它不够听话改完不跑测试风格飘忽那这套技能体系值得你花时间研究。如果你还没上手也没关系我会把安装、配置、技能编写、TDD 流程串讲一遍尽量让零基础的人也能跟着走通。下面所有内容都基于我对这类工具链的常见实践理解来展开具体命令以你本地实际版本为准。2. 环境准备把 skills CLI 和编码智能体装到能用2.1 先想清楚装在哪台机器上这一步很多人会忽略但它直接影响后面顺不顺手。我的建议是把 skills CLI 和编码智能体装在同一个开发环境里也就是你日常写代码的那台机器或那个容器。原因很简单技能包里的很多操作是要读写项目文件、执行测试命令的如果 CLI 在一个环境、智能体在另一个环境路径和依赖就会对不上排查起来非常痛苦。具体到操作系统macOS 和 Ubuntu 是最常见的两个选择。macOS 上一般用 Homebrew 管理命令行工具Ubuntu 上则是 apt 加 npm 全局安装的组合。Windows 用户如果不想折腾建议直接用 WSL把整个工具链放在 Linux 子系统里避免路径分隔符和权限模型带来的额外问题。提示安装前先确认 Node.js 版本。这类 CLI 工具通常要求 Node 18 以上版本太低会出现依赖解析失败或运行时语法报错。用node -v看一眼不达标就先升级。2.2 安装顺序与验证方法安装顺序我推荐先 CLI后智能体。因为 skills CLI 本身是个独立工具装完就能验证而编码智能体往往需要额外的账号或模型配置放在后面处理出问题时更容易定位是哪一环。安装完成后别急着写技能先做三步验证运行skills --version或等价的版本命令确认 CLI 能正常执行。运行skills list看当前已安装的技能列表哪怕是空的也说明命令链路通了。在项目目录下跑一次skills init如果该版本提供生成默认的技能目录结构。这三步做完你就有了一副骨架。接下来才是往里面填技能。2.3 智能体侧的配置要点编码智能体这边核心是让它知道去哪里找技能。常见做法是在项目根目录放一个约定好的配置目录比如.agent/skills/或类似路径CLI 负责往这里写智能体负责从这里读。有些实现是通过配置文件显式声明技能路径有些是约定优于配置直接扫描固定目录。这里有个容易踩的坑全局技能和项目级技能的优先级。全局技能放在用户主目录下所有项目共享项目级技能放在仓库里只对当前项目生效。当两者同名时通常项目级会覆盖全局级。理解这个优先级你才能决定哪些技能该一次写好到处用哪些该跟着项目走。3. 技能包到底长什么样拆解一个 TDD 技能3.1 技能的最小结构一个技能单元本质上是一个带元信息的文档。元信息部分回答我是谁、我什么时候被触发正文部分回答触发之后具体怎么做。以测试驱动开发这个技能为例它的元信息大概会包含名称比如test-driven-development触发条件当任务涉及新增功能、修改业务逻辑、修复缺陷时激活适用场景描述一段自然语言帮助智能体判断当前任务是否匹配正文部分则是流程约束通常写成有序步骤每一步都带明确的完成标准。这一点很关键——不是告诉智能体要写测试而是告诉它先写一个会失败的测试运行它确认它确实失败再写实现。3.2 为什么 TDD 特别适合做成技能我个人的观察是TDD 是 AI 编码里最该被约束、也最容易被跳过的环节。原因在于大模型的默认倾向是尽快给出能跑的代码它会本能地跳过先写失败测试这一步因为那看起来像是在制造问题而不是解决问题。把它固化成技能等于给智能体加了一道流程门禁。技能里可以明确写在编写任何实现代码之前必须先产出一个测试文件并运行测试命令确认其失败。只有在观察到失败之后才允许进入实现阶段。这种先失败后通过的顺序约束恰恰是 TDD 的精髓也是防止智能体假装测试通过的有效手段。因为如果它没真正跑过测试就无法确认失败状态流程就卡住了。3.3 技能里的红-绿-重构怎么落地红绿重构三步在技能文档里可以拆成三个明确的阶段每个阶段都有可验证的产出阶段动作完成标准常见偏差红写测试并运行测试失败且失败原因符合预期测试直接通过说明没测到点子上绿写最小实现测试通过顺手写了超出需求的代码重构清理结构测试仍通过重构后忘了重跑测试这张表建议直接放进技能文档里让智能体每一步都对照检查。尤其是红阶段的常见偏差——测试直接通过往往意味着测试写得太宽泛或者被测代码早就存在这时候要让它回头审视测试的有效性。4. 用 skills CLI 管理技能安装、启用与版本控制4.1 安装技能包的几种方式skills CLI 一般支持几种安装来源从本地目录安装、从远程仓库安装、从打包好的技能集合安装。本地目录适合你自己写的私有技能远程仓库适合社区共享的技能技能集合则是一次装一批。我建议新手先从装一个官方或社区维护的 TDD 技能开始跑通之后再自己写。因为自己从零写技能很容易写成一段更长的 prompt失去结构化约束的意义。先看别人怎么组织元信息和流程再模仿着改效率高得多。安装命令的形态通常是skills install 来源装完之后用skills list确认。如果装的是项目级技能记得把生成的目录提交到版本控制里这样团队其他人拉下来就能用同一套技能保证行为一致。4.2 启用、禁用与作用域技能装多了之后管理就成了问题。有些技能是常驻的比如代码风格检查有些是按需的比如数据库迁移。CLI 一般提供启用/禁用的开关让你控制哪些技能在当前项目生效。这里我的经验是常驻技能要少而精。因为每个激活的技能都会占用智能体的上下文预算技能太多反而会让它抓不住重点。我的做法是项目级只保留三到五个核心技能其余的都放在全局但默认禁用需要时再临时启用。4.3 版本锁定与团队协作技能是会演进的。今天好用的 TDD 技能下个月可能改了流程。如果不做版本锁定团队里不同人用的技能版本不一致产出的代码风格和测试习惯就会分叉。解决办法和依赖管理是一个思路在项目里记录技能的确切版本安装时按锁定版本拉取。这样即使上游更新了你的项目行为也不会突然变化。要升级时显式地改版本号然后跑一遍回归测试确认新技能没有引入意外行为。注意技能升级后务必用一个小任务先试跑观察智能体的行为是否符合预期再在正式任务上使用。我见过升级后技能触发条件变宽导致智能体在不该用 TDD 的场景也强行先写测试反而拖慢简单任务。5. 把技能接进 Claude Code 的实际操作5.1 让智能体看见技能目录Claude Code 这类终端智能体读取技能的机制通常是扫描约定目录。你要做的是确保技能目录在它的可见范围内。如果技能放在项目根目录下的隐藏目录里一般没问题如果放在项目外就需要通过配置显式告诉它路径。配置完之后最直接的验证方式是给智能体一个明确需要 TDD 的任务比如给这个函数加一个边界条件处理然后观察它是否先写测试。如果它直接改实现说明技能没被触发需要回头检查触发条件写得够不够明确。5.2 触发条件怎么写才靠谱触发条件是技能能否生效的关键。写得太窄该触发时不触发写得太宽不该触发时乱触发。我的写法是场景 动作双条件场景描述任务类型新增功能、修 bug、重构动作描述期望行为先写测试、先写文档。举个例子TDD 技能的触发条件可以写成当任务涉及修改或新增业务逻辑代码时在编写实现之前激活本技能。这样既限定了场景业务逻辑代码又限定了时机编写实现之前比单纯写用于测试驱动开发精确得多。5.3 和终端命令执行的配合编码智能体能不能直接执行终端命令直接决定了 TDD 技能能不能真正跑起来。因为运行测试确认失败这一步本质上就是执行一条测试命令。如果智能体只能生成代码不能执行命令那 TDD 就退化成了写测试文件但从不运行约束力大打折扣。所以配置时一定要确认智能体有执行测试命令的权限并且能读取命令输出。有些环境出于安全考虑会限制命令执行这时候要么调整权限要么退而求其次让智能体生成测试命令、由你手动执行、再把结果贴回去。后者虽然麻烦但至少保住了先失败后通过的流程。6. 实测中容易翻车的几个点6.1 技能被选择性忽略最常见的问题是智能体明明加载了技能却在具体任务里不遵守。原因往往有两个一是技能描述太长关键约束被淹没在细节里二是当前对话上下文里用户的即时指令和技能约束冲突智能体倾向于听用户的。应对办法是把最硬的约束放在技能文档最前面用加粗或独立段落强调。同时在和智能体交互时避免下达和技能冲突的指令。比如技能要求先写测试你就别催它直接给我能跑的代码。6.2 测试写得太聪明TDD 技能跑起来之后另一个坑是智能体写的测试过于复杂一个测试覆盖太多分支导致失败时定位困难。这时候可以在技能里加一条约束每个测试只验证一个行为。这条约束能显著提升测试的可维护性也让红阶段的失败原因更清晰。6.3 重构阶段失控到了重构阶段智能体有时会顺手改掉一些不该改的东西比如重命名公共接口、调整模块边界。这些改动可能让测试仍然通过但破坏了对外契约。技能里应该明确重构阶段只允许改变内部结构不允许改变外部行为且每次改动后必须重跑全部相关测试。6.4 技能与项目规范的冲突如果项目本身有既定的测试框架和目录结构而技能默认用的是另一套就会打架。解决办法是在技能里留出项目适配的说明或者干脆为项目定制一份技能。我倾向于后者——核心流程复用社区技能具体命令和路径按项目改写这样既省事又贴合实际。7. 我个人的几点使用体会用下来最大的感受是agent-skills 这类东西的价值不在于让 AI 更聪明而在于让 AI 更稳定。它把那些你希望每次都发生、但 AI 总是忘记发生的步骤变成了流程上的硬约束。TDD 只是其中一个例子同样的思路可以用在代码审查、文档生成、依赖升级等场景。另一个体会是技能要小步迭代。别指望一次写出一份完美的技能文档先用最小版本跑起来观察智能体在哪里跑偏再针对性地补约束。我自己的 TDD 技能改了七八版才达到基本不用盯着的程度。最后分享一个小技巧给技能加一个自检清单让智能体在完成任务后逐条核对。比如是否先写了失败测试是否运行了测试命令重构后是否重跑测试。这个清单不需要很长三五条就够但能显著减少流程走了一半就交差的情况。