agent-skills 实战：用技能链让 AI 编程助手遵循 TDD 工程纪律

1. 从“agent-skills”说起：为什么它值得你花时间研究

第一次看到agent-skills这个标题，很多人会以为它只是某个仓库里堆了一堆提示词模板。但真正用过 AI coding agents 的人会明白，它解决的是一个非常具体、非常痛的问题：同一个模型，为什么别人用起来像资深工程师，你用起来像刚入行的实习生？

答案往往不在模型本身，而在“技能”的组织方式。agent-skills本质上是一套面向 AI coding agents 的技能定义与组织方案，它把零散的提示词、工作流、工具调用规则、测试驱动开发（TDD）流程，封装成可复用、可组合、可版本管理的“技能单元”。你可以把它理解成给 AI 编程助手准备的一套“标准作业程序手册”，而不是每次对话都从零开始解释“你应该先写测试，再写实现，最后重构”。

这套东西适合谁？如果你正在用 Claude Code、Cursor、Windsurf 或者其他支持 skills CLI 的 AI 编程工具，并且已经过了“让它帮我写个函数”的初级阶段，开始思考“怎么让它在整个项目里稳定地按我的工程规范干活”，那agent-skills就是你需要认真看的东西。它不适合只想让 AI 补全几行代码的人，但适合那些想把 AI 编程助手真正嵌入日常开发流程、并且希望结果可预测、可复现的开发者。

我最初接触这个概念时，最大的疑问是：提示词模板和技能到底有什么区别？后来在几个真实项目里踩过坑才明白，模板是“一次性”的，技能是“有状态、有依赖、有触发条件”的。比如一个“写单元测试”的模板，你每次都要手动粘贴；而一个“test-driven-development”技能，可以在检测到新功能需求时自动触发，按照红-绿-重构的循环，先写失败测试，再写最小实现，最后重构，并且每一步都有明确的退出条件。这就是agent-skills的核心价值：把工程纪律变成 AI 可以执行的技能。

2. agent-skills 的整体设计与核心思路拆解

2.1 为什么不是“一个大提示词”，而是“技能集合”

很多人刚开始用 AI coding agents 时，喜欢写一个巨长的系统提示词，把编码规范、测试要求、提交信息格式全部塞进去。我试过，效果很差。原因很简单：上下文窗口是有限的，而且模型在长提示词里会“丢失”中间部分的指令。更麻烦的是，不同任务需要不同的行为模式，写测试和重构代码需要的指令完全不同，硬塞在一起只会互相干扰。

agent-skills的设计思路是“分而治之”。每个技能只负责一个明确的工程活动，比如：

• 写失败测试
• 实现最小通过代码
• 重构而不改变行为
• 生成符合约定的提交信息
• 执行代码审查清单

这些技能可以独立调用，也可以按顺序组合。比如一个完整的功能开发流程，就是“写测试技能 → 实现技能 → 重构技能 → 提交技能”的链式调用。这种设计的好处是，每个技能的提示词可以写得很精炼，模型更容易遵循；同时，技能之间通过明确的输入输出契约连接，减少了歧义。

2.2 技能的定义结构：元数据、触发条件与执行体

一个典型的agent-skills技能定义，通常包含三个部分：

元数据：技能名称、版本、作者、适用场景描述。这部分看起来简单，但非常重要。因为当你有几十个技能时，AI agent 需要根据当前任务自动选择合适的技能，元数据就是它的“索引”。我见过有人把技能命名成skill-1、skill-2，结果 agent 根本不知道该用哪个。好的命名应该像tdd-write-failing-test这样，一看就知道干什么。

触发条件：什么情况下这个技能应该被激活。可以是显式的命令，比如用户输入/tdd；也可以是隐式的上下文检测，比如 agent 发现当前对话涉及“新功能”且“没有对应测试”。触发条件的设计直接决定了技能是“好用”还是“烦人”。如果触发太敏感，agent 会不停打断你；如果太迟钝，你又得手动调用。

执行体：技能的具体内容，通常是一段结构化的提示词，加上对工具调用的约束。比如 TDD 写测试技能的执行体，会明确要求 agent：先阅读现有测试文件的结构，然后生成一个会失败的测试用例，并且禁止在这一步写实现代码。执行体里还会包含“退出条件”，比如“当测试文件成功创建且运行后报错，技能完成”。

2.3 与 skills CLI 的配合：让技能可安装、可共享

agent-skills通常和skills CLI一起使用。这个 CLI 工具的作用，类似于包管理器。你可以用它来：

• 从远程仓库安装技能包
• 列出本地已安装的技能
• 更新技能到新版本
• 移除不再需要的技能

为什么需要 CLI？因为手动复制粘贴技能定义太容易出错了。而且当团队协作时，你需要确保每个人用的技能版本一致。skills CLI通过一个清单文件（类似package.json）来锁定版本，这样就不会出现“我这边能跑，你那边不行”的情况。

我自己的做法是，在项目根目录放一个skills.json，里面声明这个项目需要的技能和版本。新成员克隆项目后，只需要运行skills install，所有技能就就位了。这比在 README 里写“请把以下提示词复制到你的配置里”要可靠得多。

3. 核心细节解析与实操要点

3.1 技能文件的目录结构与命名规范

一个组织良好的agent-skills仓库，目录结构通常长这样：

skills/ tdd/ write-failing-test/ skill.md metadata.json implement-minimal/ skill.md metadata.json refactor/ skill.md metadata.json git/ commit-message/ skill.md metadata.json

每个技能一个文件夹，里面至少有一个skill.md存放提示词内容，一个metadata.json存放元数据。这种结构的优点是，技能可以独立版本控制，也方便 CLI 工具扫描和加载。

命名上，我强烈建议用“领域-动作-对象”的格式。比如tdd-write-failing-test比test1好得多。因为当 agent 需要自动选择技能时，它会根据名称和描述做匹配。名称越语义化，匹配越准确。

注意：不要用中文命名技能文件夹。虽然有些工具支持，但在跨平台和 CLI 处理时容易出编码问题。用英文小写加连字符，是最稳妥的。

3.2 触发条件的三种实现方式

触发条件是技能能否“自动生效”的关键。根据我的实测，有三种方式比较可靠：

第一种：显式命令触发。用户在对话中输入/skill-name，agent 直接加载对应技能。这种方式最可控，适合那些你不想被自动触发的技能，比如“生成提交信息”。

第二种：上下文关键词触发。当用户消息中出现特定关键词时，agent 自动加载技能。比如检测到“写测试”或“TDD”，就加载tdd-write-failing-test。这种方式适合高频、明确的任务。但要注意关键词不能太泛，否则会误触发。我试过用“测试”作为关键词，结果 agent 在我只是问“这个测试为什么失败”时也加载了写测试技能，很烦。

第三种：状态机触发。这是最复杂但也最强大的方式。技能定义里包含前置状态和后置状态，agent 根据当前项目状态决定是否触发。比如“实现最小通过代码”技能的前置状态是“存在一个失败的测试”，后置状态是“测试通过”。这种方式需要 agent 能读取项目状态（比如运行测试命令），对工具集成要求较高，但效果最好。

3.3 TDD 技能链的详细拆解

test-driven-development是agent-skills里最经典的技能链。我把它拆成三个技能，每个都有明确的输入输出：

技能一：写失败测试。输入是功能描述，输出是一个新的测试文件或测试用例，并且这个测试运行后必须失败。执行体里会要求 agent：先阅读现有测试的命名风格和断言库，然后生成测试代码，最后运行测试命令确认失败。如果测试通过了，说明功能已经存在，技能会报错并停止。

技能二：实现最小通过代码。输入是失败的测试，输出是能让测试通过的最少代码。这里的关键约束是“最小”。很多 AI agent 会忍不住把整个功能都实现了，甚至加上额外的优化。执行体里必须明确禁止：不要写测试没覆盖的逻辑，不要做性能优化，不要改无关文件。

技能三：重构。输入是通过的测试和现有实现，输出是重构后的代码，且测试仍然通过。重构技能会要求 agent：先识别代码坏味道，然后小步修改，每步都运行测试。如果测试失败，立即回滚。

这三个技能串起来，就是一个完整的 TDD 循环。我实测下来，用技能链比让 agent 自由发挥，代码质量稳定得多。尤其是“最小实现”这个约束，能有效防止 AI 过度设计。

4. 实操过程与核心环节实现

4.1 环境准备：从零搭建 agent-skills 工作流

假设你已经在用 Claude Code 或者类似的 AI coding agent，并且已经配置好了基本的模型接入。接下来要做的，是让 agent 能识别和使用技能。

第一步，安装skills CLI。通常可以通过包管理器安装，比如npm install -g skills-cli或者从源码构建。安装完成后，运行skills --version确认可用。

第二步，初始化技能目录。在项目根目录运行skills init，它会创建一个skills/文件夹和一个skills.json清单文件。如果你已经有现成的技能仓库，可以直接git clone到skills/下。

第三步，配置 agent 加载技能。不同的 agent 配置方式不同。以 Claude Code 为例，你需要在项目配置里指定技能目录的路径，并启用技能自动加载。具体配置项名称可能随版本变化，但核心是告诉 agent：“去这个目录找技能定义，并根据触发条件使用它们。”

第四步，验证技能是否生效。创建一个简单的测试技能，比如hello-world，触发条件设为显式命令/hello。然后在 agent 对话里输入/hello，看它是否加载了技能并执行。如果没反应，检查技能目录路径和 metadata 格式是否正确。

提示：技能加载失败最常见的原因是 metadata.json 格式错误。建议用 JSON 校验工具检查一遍，确保没有多余的逗号或缺失的引号。

4.2 编写第一个自定义技能：以“生成符合规范的提交信息”为例

我们来实现一个实用的技能：git-commit-message。它的目标是，当用户说“提交代码”时，agent 自动生成符合 Conventional Commits 规范的提交信息。

metadata.json 内容：

{ "name": "git-commit-message", "version": "1.0.0", "description": "根据暂存区的变更生成符合 Conventional Commits 规范的提交信息", "triggers": ["提交代码", "commit", "生成提交信息"], "author": "your-name" }

skill.md 内容：

# 生成提交信息 ## 前置条件 - 当前目录是 Git 仓库 - 暂存区有变更 ## 执行步骤 1. 运行 `git diff --cached --stat` 查看暂存区文件列表 2. 运行 `git diff --cached` 查看具体变更内容 3. 根据变更类型选择提交前缀： - 新增功能：feat - 修复缺陷：fix - 文档更新：docs - 代码格式：style - 重构：refactor - 测试相关：test - 构建或工具：chore 4. 生成提交信息，格式为：`<type>(<scope>): <subject>` 5. 如果变更涉及多个类型，选择最主要的类型 6. 提交信息正文用中文描述具体改了什么，每行不超过 72 字符 ## 输出示例 feat(auth): 增加手机号验证码登录 - 新增短信验证码发送接口 - 登录页增加验证码输入框 - 验证码有效期设为 5 分钟 ## 退出条件 - 提交信息已生成并展示给用户 - 用户确认后执行 `git commit`

这个技能写好后，放到skills/git/commit-message/下，运行skills install注册。之后在 agent 里说“提交代码”，它就会自动加载这个技能，按步骤生成提交信息。

我实测下来，这个技能能节省大量时间，尤其是当变更文件很多时，手动写提交信息很容易漏掉关键改动。但要注意，agent 生成的提交信息偶尔会过于笼统，比如“更新代码”这种。所以我在技能里加了“正文用中文描述具体改了什么”，并且要求用户确认后才提交，避免直接提交错误信息。

4.3 技能链的编排：如何让多个技能按顺序执行

单个技能好用，但真正的威力在于技能链。agent-skills通常支持在 metadata 里声明next字段，指定当前技能完成后自动加载的下一个技能。

比如tdd-write-failing-test的 metadata 里可以写：

{ "name": "tdd-write-failing-test", "next": "tdd-implement-minimal" }

这样当写测试技能完成后，agent 会自动加载实现技能。实现技能的 metadata 里再指向重构技能，形成链条。

但这里有个坑：自动链式执行很容易失控。如果某个技能执行失败，但 agent 仍然继续加载下一个技能，就会产生混乱。我的做法是，在技能执行体里明确加入“失败处理”：如果当前步骤失败，停止链式执行，并报告错误。同时，在 metadata 里加一个continueOnError: false的字段，让 CLI 或 agent 知道不要继续。

另外，链式执行时，技能之间的数据传递要清晰。比如写测试技能输出的测试文件路径，需要传递给实现技能。这通常通过 agent 的上下文变量来实现，但不同 agent 实现方式不同。我建议在技能定义里用明确的占位符，比如{{test_file_path}}，并在执行体里说明如何填充。

5. 常见问题与排查技巧实录

5.1 技能不触发或触发错误

这是最常见的问题。表现是：你明明说了“写测试”，但 agent 没有加载 TDD 技能，或者你只是问了个问题，它却突然开始写测试。

排查思路：

• 检查触发关键词是否太宽泛。比如“测试”这个词，在“这个测试为什么失败”里也会出现。解决办法是改用更具体的短语，比如“写一个新测试”或“TDD 开始”。
• 检查 metadata.json 里的triggers数组格式是否正确。必须是字符串数组，不能是逗号分隔的字符串。
• 检查技能是否已安装。运行skills list确认技能在列表中。
• 检查 agent 的技能加载配置。有些 agent 需要重启或重新加载配置才能识别新技能。

我踩过的一个坑是，技能文件夹名和 metadata 里的name不一致，导致 CLI 扫描不到。后来统一用文件夹名作为技能名，问题就解决了。

5.2 技能执行结果不符合预期

比如 TDD 写测试技能生成的测试，运行后居然通过了。这说明 agent 没有遵循“必须失败”的约束。

排查思路：

• 检查执行体里是否明确写了“运行测试并确认失败”。如果只是说“生成测试”，agent 可能不会主动运行。
• 检查 agent 是否有权限运行测试命令。有些环境默认禁止 agent 执行终端命令，需要在配置里开启。
• 检查测试框架的退出码。有些测试框架在测试通过时返回 0，失败时返回非 0。agent 需要能正确解析退出码。

我的经验是，在技能执行体里加入具体的命令示例，比如npm test -- --grep "新功能"，并说明“如果退出码为 0，说明测试通过了，这是错误的，请重新生成一个会失败的测试”。这样 agent 的遵循率会高很多。

5.3 技能版本冲突与依赖管理

当团队多人维护技能时，容易出现版本冲突。比如 A 更新了tdd-write-failing-test到 2.0，但 B 还在用 1.0，导致行为不一致。

解决办法是使用skills.json锁定版本，类似package-lock.json。每次安装技能时，CLI 会记录精确版本。更新技能时，需要显式运行skills update <skill-name>，并且提交更新后的skills.json。

另外，技能之间可能有依赖关系。比如tdd-implement-minimal依赖tdd-write-failing-test的输出格式。如果前者更新了输出格式，后者也需要同步更新。我建议在 metadata 里加dependencies字段，声明依赖的技能和版本范围。CLI 在安装时可以检查依赖是否满足。

5.4 常见问题速查表

6. 技能设计的进阶思路与个人经验

6.1 技能粒度：多细才算合适

这是设计agent-skills时最纠结的问题。技能太粗，比如一个“开发功能”技能包揽所有事，提示词会变得巨长，模型容易迷失。技能太细，比如“写第一行测试代码”和“写第二行测试代码”分开，又会导致技能数量爆炸，管理成本太高。

我的经验法则是：一个技能应该对应一个可验证的工程活动，并且有明确的完成标志。比如“写失败测试”是一个可验证活动，完成标志是“测试文件存在且运行失败”。“实现最小通过代码”也是可验证活动，完成标志是“测试运行通过”。而“思考功能设计”就不是一个适合做成技能的活动，因为它没有明确的完成标志。

按照这个法则，一个中等复杂度的功能开发，大概需要 5 到 8 个技能。这个数量既不会让 agent 难以选择，也不会让提示词过于臃肿。

6.2 如何让技能“记住”项目上下文

AI coding agents 的一个弱点是，它们容易忘记项目特定的约定。比如你的项目用pytest而不是unittest，用black格式化而不是autopep8。如果每个技能都重复写这些约定，维护起来很痛苦。

解决办法是引入“项目上下文技能”。这是一个特殊的技能，不执行具体任务，只提供项目级的信息。它的触发条件是“始终加载”，执行体里包含项目的技术栈、代码规范、测试命令、目录结构说明等。其他技能在执行时，可以引用这个上下文技能的内容。

比如在tdd-write-failing-test的执行体里写：“参考项目上下文技能中的测试框架和命名约定。”这样当项目从unittest迁移到pytest时，只需要更新上下文技能，其他技能不用动。

我实测下来，这个做法能显著减少技能维护成本。但要注意，上下文技能的内容不能太长，否则会占用太多上下文窗口。我一般控制在 500 字以内，只放最关键的约定。

6.3 技能测试：怎么知道技能写得好不好

技能也是代码，也需要测试。但测试技能比测试普通代码更麻烦，因为技能的行为依赖模型的理解能力，有一定随机性。

我的做法是建立一套“技能回归测试”。针对每个技能，准备几个典型的输入场景，然后运行 agent 加载技能并执行，检查输出是否符合预期。比如对于git-commit-message技能，准备三个场景：只改了一个文件、改了多个文件、改了文档。然后看 agent 生成的提交信息是否符合 Conventional Commits 规范。

这些测试不需要每次都跑，但在技能更新后一定要跑一遍。我通常把测试场景写在技能文件夹下的test-cases.md里，手动执行。虽然原始，但有效。

另外，我建议在技能 metadata 里加一个changelog字段，记录每次修改的原因和影响。这样当技能行为变化时，能快速定位是哪个版本引入的。

6.4 安全边界：技能不应该做什么

agent-skills让 AI 编程助手变得更强大，但也带来了风险。一个设计不当的技能，可能会让 agent 执行危险操作，比如删除文件、强制推送代码、修改生产配置。

我在设计技能时，会遵循几条安全边界：

• 禁止技能直接执行破坏性命令。比如rm -rf、git push --force、DROP TABLE。如果确实需要，必须要求用户显式确认。
• 技能不应该访问敏感信息。比如读取环境变量里的密钥、访问数据库连接字符串。如果技能需要这些信息，应该通过安全的配置注入方式，而不是让 agent 直接读取。
• 技能应该有“干跑”模式。对于有副作用的操作，比如提交代码、部署，技能应该先展示将要执行的操作，等用户确认后再执行。
• 技能不应该绕过代码审查。即使 agent 生成的代码通过了测试，也应该走正常的代码审查流程。技能可以辅助审查，但不能替代。

这些边界看起来限制了技能的能力，但实际上它们让技能更可靠。我见过有人写了一个“自动修复所有 lint 错误”的技能，结果 agent 把整个文件的格式都改了，提交了几百行无关变更。后来加上了“只修改 lint 报错的行”的约束，问题才解决。

6.5 从个人使用到团队推广

如果你自己用agent-skills觉得不错，想推广到团队，有几个实际障碍需要提前考虑。

首先是工具链统一。团队里可能有人用 Claude Code，有人用 Cursor，有人用其他工具。不同工具对技能的支持程度不同。我的建议是，先在小范围试点，选一个大家都愿意用的工具，把技能跑通。然后再考虑跨工具兼容。

其次是技能维护责任。技能是团队共享资产，需要有人负责更新和审查。我建议指定一个“技能维护者”角色，或者轮流负责。每次技能变更都要走代码审查，确保不会引入意外行为。

最后是培训成本。不是每个人都能快速理解技能的设计思路。我通常会写一份简短的“技能使用指南”，说明每个技能是干什么的、什么时候触发、输出是什么。新成员入职时，先让他们用现成的技能，熟悉后再鼓励他们写自己的技能。

7. 技能生态的扩展方向

agent-skills目前最成熟的应用场景是 TDD 和 Git 工作流，但它的潜力远不止于此。我在实际项目中尝试过几个扩展方向，效果不错。

代码审查技能。当 agent 完成一个功能后，自动加载代码审查技能，按照团队定义的检查清单逐项审查。比如检查是否有未处理的错误、是否有硬编码的配置、是否有性能隐患。这个技能可以和 TDD 技能链结合，在重构之后自动触发。

文档生成技能。当代码变更涉及公共 API 时，自动生成或更新文档。这个技能需要能读取代码注释和类型定义，然后生成 Markdown 文档。我试过用这个技能维护 API 文档，比手动更新省事很多，但要注意 agent 生成的文档有时会遗漏边界条件。

依赖升级技能。定期检查项目依赖是否有新版本，评估升级风险，并生成升级方案。这个技能需要能读取package.json或requirements.txt，查询版本信息，然后运行测试确认升级不会破坏现有功能。这个技能风险较高，我建议只在开发环境使用，并且必须人工确认后再合并。

性能分析技能。当测试运行变慢时，自动分析瓶颈并给出优化建议。这个技能需要能运行性能分析工具，解析输出，然后定位热点代码。我实测下来，agent 给出的建议有时比较泛，需要人工筛选。

这些扩展方向的共同点是，它们都是“可验证的工程活动”，符合技能设计的基本原则。随着 AI coding agents 的能力提升，我相信会有更多有价值的技能被开发出来。但核心思路不会变：把工程纪律封装成可复用、可组合的技能，让 AI 助手真正成为团队的一员，而不是一个随机的代码生成器。

我个人在实际操作中的体会是，agent-skills最大的价值不是让 AI 写更多代码，而是让 AI 写更少但更对的代码。通过技能约束，agent 被迫遵循工程规范，减少了返工和调试的时间。刚开始配置技能会花一些时间，但一旦跑通，后续的收益是持续的。如果你还在犹豫要不要投入时间研究这个方向，我的建议是先从一个小技能开始，比如提交信息生成，感受一下效果，再决定是否深入。