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 技能改了七八版，才达到"基本不用盯着"的程度。
最后分享一个小技巧：给技能加一个"自检清单"，让智能体在完成任务后逐条核对。比如"是否先写了失败测试""是否运行了测试命令""重构后是否重跑测试"。这个清单不需要很长，三五条就够，但能显著减少"流程走了一半就交差"的情况。
