agent-skills 技能库：用 TDD 驱动 AI 编码代理的工程化实践

1. 从"agent-skills"这个标题里能读出什么

第一次看到agent-skills这个仓库名，我的直觉是：这不是又一个"提示词大全"，而是一套给 AI coding agent 用的能力封装规范。事实也确实如此——它把"让 AI 写代码"这件事从"随手丢一句 prompt"升级成了"按技能模块调用、按测试驱动验收"的工程化流程。

先把定位说清楚。agent-skills本质上是一个技能集合仓库，里面沉淀的是一批可复用的、面向 AI 编码代理（AI coding agents）的任务模板与工作流。它配套一个skillsCLI，用来把这些技能安装、注册、分发到不同的 agent 运行环境里。关键词里出现的test-driven-development是它最核心的一条技能线——也就是说，它不只是教 AI"怎么写"，而是教 AI"先写测试、再写实现、最后自检"。

它解决的真实痛点很具体：大多数人用 AI 写代码，卡在三个地方。第一，每次都要重新描述上下文，重复劳动；第二，AI 写完的代码没人验证，跑不跑得起来全靠运气；第三，不同项目、不同语言、不同框架的"最佳实践"散落在各个聊天记录里，无法沉淀。agent-skills的思路是把这些经验固化成"技能包"，让 agent 按需加载，而不是每次从零开始。

适合谁来参考？三类人最受益：一是已经在用 Claude Code、VS Code 里各类 AI 编码插件的开发者，想让 AI 的输出更稳定；二是团队里负责搭建 AI 辅助开发规范的人，需要一套可复制的技能组织方式；三是对 TDD 有执念、但苦于 AI 生成的代码质量参差的工程师。哪怕你只是刚接触 AI coding agent，读完也能明白"技能"这层抽象到底值不值得引入。

下面我会按"它到底怎么组织技能 → 为什么用 CLI 而不是复制粘贴 → TDD 技能线怎么落地 → 实际接入时踩过的坑 → 怎么把它扩展成自己的技能库"这条线展开，尽量把每一步的"为什么"讲透。

2. agent-skills 的技能组织逻辑：为什么不是简单的提示词集合

2.1 技能（skill）和提示词（prompt）的本质区别

很多人第一反应是："技能不就是长一点的提示词吗？"我一开始也这么想，直到把两者放在工程视角下对比，才发现差别很大。

提示词是一次性的、上下文绑定的。你写一段"帮我用 Python 写一个带重试的 HTTP 客户端"，这段文字只在当前对话里有效，换个会话就没了，换个项目也不一定适用。它没有版本、没有依赖、没有验收标准。

技能是可复用、可组合、可验收的。一个合格的 skill 通常包含四部分：触发条件（什么时候该用这个技能）、执行步骤（具体做什么）、约束规则（不能做什么）、验收方式（怎么判断做对了）。这四部分里，验收方式是最容易被忽略、也最关键的——没有验收，技能就退化成了提示词。

我用一个生活化的类比：提示词像是"跟朋友口头说一句帮我带杯咖啡"，技能像是"写进 SOP 的咖啡采购流程"——包括什么情况下要买、买什么规格、预算多少、买回来怎么确认没买错。前者靠默契，后者靠流程。

2.2 一个 skill 的典型结构拆解

基于这类仓库的常见组织方式，一个 skill 目录通常长这样：

skills/ test-driven-development/ SKILL.md # 技能主描述：触发条件、步骤、约束 examples/ # 示例输入输出 templates/ # 可复用的代码/配置模板 code-review/ SKILL.md checklist.md

SKILL.md是核心。它一般会写清楚：

• name：技能标识，CLI 注册时用
• description：一句话说明这个技能干什么，agent 靠它判断是否匹配当前任务
• when_to_use：触发场景，越具体越好
• steps：有序的执行步骤
• constraints：硬性约束，比如"必须先写测试再写实现"
• verification：怎么验证结果正确

这里有个容易被忽略的设计点：description 的写法直接决定 agent 能不能正确调用这个技能。如果 description 写得太泛（比如"帮助写代码"），agent 几乎不会选中它；写得越贴近具体任务（比如"为已有函数补充单元测试并运行验证"），命中率越高。这跟搜索引擎的 query 匹配是一个道理。

2.3 为什么技能要分目录而不是塞进一个大文件

我见过有人把所有技能写进一个巨大的prompts.md，几百行堆在一起。短期看省事，长期看是灾难。原因有三：

第一，加载成本。agent 的上下文窗口是有限的，把无关技能全塞进去，等于稀释了真正相关技能的权重。分目录后可以按需加载，只把匹配的技能注入上下文。

第二，维护成本。一个技能要改，你得在几百行里找到它、改完还得确认没影响到别的技能。分文件后，改动范围清晰。

第三，复用成本。技能之间可以互相引用。比如code-review技能可以引用test-driven-development里的验收标准，而不是复制一遍。分目录让这种引用成为可能。

提示：如果你打算自己维护技能库，从第一天就分目录。我见过太多"先堆一起、以后再拆"的项目，最后都没拆成。

3. skills CLI：把技能从"文件"变成"可安装的能力"

3.1 CLI 存在的意义：解决分发和版本问题

有了技能文件，下一个问题是：怎么让 agent 用上它们？最原始的做法是手动把文件复制到 agent 的配置目录。这个做法在单机、单项目时能用，一旦涉及多台机器、多个项目、多人协作，立刻崩盘——你没法保证每个人装的是同一版本，也没法优雅地升级。

skillsCLI 就是来解决这个的。它的职责可以概括为三件事：安装（install）、注册（register）、同步（sync）。

• install：从仓库拉取技能到本地某个约定目录
• register：把本地技能目录告诉 agent，让 agent 知道去哪找技能
• sync：在技能更新后，把新版本同步到所有已注册的位置

这套逻辑跟包管理器（npm、pip）非常像。你可以把agent-skills理解成一个"技能版的 npm registry"，skillsCLI 就是那个npm命令。

3.2 安装与注册的典型流程

具体命令会随版本变化，但流程逻辑是稳定的。典型操作序列大致是：

# 1. 全局安装 CLI（具体包名以仓库说明为准） npm install -g <skills-cli-package> # 2. 初始化本地技能目录 skills init # 3. 从仓库安装某个技能 skills install test-driven-development # 4. 查看已安装技能 skills list # 5. 注册到当前 agent 环境 skills register --target <agent-config-path>

这里每一步都有讲究。init会在你的用户目录下建一个约定位置（比如~/.agent-skills/），所有技能都装在这里，避免散落各处。install支持指定版本，生产环境建议锁版本，别用 latest。register的--target参数是关键——不同 agent 的配置路径不一样，注册错了 agent 根本读不到。

3.3 为什么"注册"这一步最容易被做错

我踩过的坑里，注册环节占了一半。常见问题有这么几类：

最后一条特别值得说。全局注册方便，但会让所有项目共享同一套技能，A 项目需要的技能可能干扰 B 项目。我的建议是：通用技能全局注册，项目专属技能项目级注册。这样既省事又不互相污染。

4. test-driven-development 技能线：让 AI 先写测试再写实现

4.1 为什么 TDD 特别适合交给 AI agent

TDD 的核心循环是"红-绿-重构"：先写一个会失败的测试（红），再写最少的实现让它通过（绿），最后重构。这个循环对人类来说有点反直觉——很多人习惯先写实现再补测试。但对 AI agent 来说，TDD 反而是最自然的模式。

原因在于：测试是天然的验收标准。AI 写完代码后，最大的问题是"怎么知道它写对了"。如果先有测试，agent 就有了明确的成功判据——测试通过就是对了，不通过就继续改。这比让 agent 自己"觉得写完了"可靠得多。

另外，测试还能约束 agent 的行为边界。没有测试时，agent 容易过度设计，加一堆你用不上的功能；有了测试，它只需要让测试通过，反而更克制。

4.2 TDD 技能的执行步骤拆解

一个设计良好的 TDD 技能，步骤通常是这样组织的：

1. 理解需求：agent 先复述任务，确认理解无误
2. 写失败测试：针对需求写测试用例，此时实现还不存在，测试必然失败
3. 运行测试确认失败：这一步不能省，否则你不知道测试是不是真的在测东西
4. 写最小实现：只写让测试通过的最少代码
5. 运行测试确认通过：绿了才算数
6. 重构：在测试保护下优化代码结构
7. 重复：进入下一个需求点

第 3 步和第 5 步是很多人会跳过的。跳过第 3 步，你可能写了个永远通过的假测试；跳过第 5 步，你根本不知道实现对不对。这两步是 TDD 的"锚点"，必须保留。

4.3 约束规则怎么写才有效

TDD 技能的约束部分，我建议至少包含这几条：

• 禁止在测试通过前修改测试用例（防止 agent 为了让测试通过而改测试）
• 禁止一次写多个测试（保持小步快跑）
• 每个测试只验证一个行为（避免测试耦合）
• 实现代码不得包含测试未覆盖的分支（防止偷偷加功能）

第三条和第四条是实战中总结出来的。我遇到过 agent 写一个测试验证了五个行为，结果一个失败全失败，根本定位不到问题。也遇到过 agent 在实现里加了一堆测试没覆盖的逻辑，表面测试全绿，实际埋了雷。

注意：约束规则要写成"禁止 X"而不是"尽量 Y"。"尽量"对 agent 来说等于没有约束。

5. 接入 Claude Code 与 VS Code 时的实际踩坑

5.1 环境准备阶段最容易忽略的两件事

第一件是版本对齐。agent-skills的技能格式可能随版本演进，CLI 版本和技能版本不匹配时，会出现"技能装了但解析失败"的情况。我的做法是：在项目里放一个.agent-skills-version文件，记录当前使用的 CLI 和技能版本，团队协作时先对齐这个文件。

第二件是配置目录的权限。在 Linux 或 macOS 上，如果 agent 的配置目录属于 root，而你是普通用户，register 会静默失败——它不报错，但技能就是没注册上。排查时先ls -la看一眼目录归属，别急着怀疑技能本身。

5.2 技能不生效的排查链路

遇到"技能装了但 agent 不用"的情况，我一般按这个顺序排查：

1. 确认技能真的装上了：skills list看得到吗？看不到就是 install 失败
2. 确认注册路径正确：agent 的配置里有没有指向技能目录？路径拼写对不对？
3. 确认 description 匹配：手动构造一个应该触发该技能的任务，看 agent 是否调用
4. 确认没有缓存干扰：重启 agent，或执行 sync 刷新
5. 确认技能内容本身有效：把 SKILL.md 内容直接贴给 agent，看它能不能理解

这个顺序是从"最外层"往"最内层"排查。大部分问题在前两步就能定位，真正是技能内容问题的很少。

5.3 和 VS Code 集成时的细节

在 VS Code 里用 AI 编码插件时，技能注册的 target 通常是插件的配置目录。这里有个坑：不同插件的配置目录结构不一样，有的读工作区级配置，有的只读用户级配置。如果你在项目里注册了技能但插件不认，先确认它读的是哪一级配置。

另一个细节是工作区隔离。VS Code 的多根工作区（multi-root workspace）下，每个根目录可能被视为独立项目。如果你希望技能在整个工作区生效，注册时要指向工作区级配置，而不是某个根目录。

6. 把 agent-skills 扩展成自己的技能库

6.1 什么样的经验值得沉淀成技能

不是所有经验都值得做成技能。我的判断标准是三条：高频、有明确验收标准、步骤相对稳定。

高频意味着值得投入时间封装；有验收标准意味着 agent 能自己判断做没做对；步骤稳定意味着不会三天两头改。三条都满足的，比如"为新函数补单元测试""按团队规范做代码审查""生成符合规范的 commit message"，都适合做成技能。

反过来，一次性的、需要大量人工判断的、步骤经常变的任务，做成技能反而增加维护负担。

6.2 从零写一个技能的实操步骤

假设我要做一个"生成 API 文档"的技能，流程是这样：

1. 建目录：skills/api-doc-gen/
2. 写 SKILL.md：定义 name、description、when_to_use、steps、constraints、verification
3. 写示例：在examples/放一两个输入输出样例，帮 agent 理解预期
4. 写模板：在templates/放文档模板，agent 直接套用
5. 本地测试：用skills register注册，构造任务验证
6. 迭代 description：根据命中率调整描述，直到 agent 能稳定调用

第 6 步是最耗时的，也是最关键的。description 的措辞需要反复打磨，我一般会试三到五个版本，看哪个版本的命中率最高。

6.3 技能库的版本管理建议

技能库一旦被多人使用，版本管理就成了刚需。我的建议是：

• 技能库本身用 Git 管理，每次改动走 PR
• 用语义化版本（semver）标记技能版本
• 破坏性改动（比如改了约束规则）必须升 major 版本
• 在 SKILL.md 里记录 changelog，方便使用者判断要不要升级

这套做法借鉴了开源库的版本管理经验，虽然对技能库来说有点重，但一旦团队规模上来，省下的沟通成本远超投入。

7. 我在实际使用中总结的几条经验

用了一段时间agent-skills这套东西，有几个体会比较深。

第一，技能不是越多越好。我一开始恨不得把所有能想到的任务都做成技能，结果 agent 反而不知道该用哪个，命中率下降。后来砍到只保留最高频的十几个，效果明显变好。技能库的价值在于精准，不在于数量。

第二，description 值得反复打磨。我有个技能改了七版 description 才稳定命中。别指望一次写对，把它当成一个需要调优的参数。

第三，TDD 技能线是投入产出比最高的。如果你只打算做一个技能，就做 TDD。它带来的代码质量提升最直接，而且验收标准天然清晰。

第四，别忽略 sync。技能更新后不 sync，agent 读的还是旧版本，你会以为改动没生效，白白排查半天。养成改完就 sync 的习惯。

最后分享一个小技巧：给每个技能加一个"反例"章节，写明"什么情况下不要用这个技能"。这能有效减少 agent 的误调用，比只写"什么时候用"效果好得多。