agent-skills：为AI编程助手构建可复用技能系统与TDD实践

1. 从 agent-skills 说起：为什么我们需要给 AI 编程助手装上一套技能系统

第一次看到agent-skills这个项目名的时候，我脑子里蹦出来的第一个念头是：这不就是给 AI coding agents 做的一套“技能包”吗？后来翻了一圈它的设计思路和社区讨论，发现这个判断基本靠谱，但又不完全准确。它更像是一套面向 AI 编程代理的技能抽象层与命令行工具集，核心目标是把“让 AI 干某件事”这件事，从一次性、散落在各个 prompt 里的临时指令，变成可复用、可版本管理、可组合的标准化技能单元。

这件事为什么重要？因为过去一年我在实际项目里用 Claude Code、Cursor、各种 CLI agent 做开发辅助，最大的痛点从来不是模型不够聪明，而是每次都要重新解释一遍上下文。比如我想让 agent 帮我按 TDD 流程写一个模块，我得先告诉它测试框架是什么、目录结构怎么放、命名规范是什么、跑测试的命令是什么。下次换个项目，同样的解释再来一遍。agent-skills 想解决的，就是把这个“解释成本”沉淀下来，变成一个个独立的 skill，让 agent 在需要的时候自己加载。

所以这篇博文我打算从几个层面把它讲透：它到底解决什么问题、核心设计思路是什么、怎么落地实操、踩过哪些坑。适合谁看？如果你已经在用 Claude Code 或者类似的 AI coding agent 做日常开发，并且开始觉得“每次重复交代背景”很烦，那这篇就是写给你的。如果你还没入门，也没关系，我会把基础概念顺带讲清楚，保证你能跟上。

需要先说明一点：agent-skills 这类项目目前还在快速演进，很多细节社区里不同人的实践方式不完全一样。下面涉及具体操作的部分，我会明确区分哪些是项目本身的设计、哪些是我基于常见实践补充的合理方案，你照着抄的时候心里有数。

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

2.1 把“技能”当成一等公民：从 prompt 到 skill 的抽象

传统做法里，我们让 AI coding agent 干活，基本靠两种方式：一种是在对话里直接下指令，另一种是写一个 system prompt 或者项目级的规则文件（比如CLAUDE.md、.cursorrules）。这两种方式的问题在于，它们是扁平的、全量的——不管这次任务用不用得上，所有规则一股脑塞给模型，既浪费上下文窗口，又容易让模型抓不住重点。

agent-skills 的思路是把能力拆成一个个独立的 skill。每个 skill 是一个自包含的单元，包含：这个技能叫什么、什么时候该用它、用的时候需要哪些输入、具体执行步骤是什么、产出应该长什么样。这有点像给 agent 建了一个“技能库”，它可以根据当前任务按需调用，而不是每次都把整本说明书背一遍。

我打个生活化的比方。传统 prompt 就像你雇了个新员工，每次让他干活都得把公司所有规章制度念一遍；agent-skills 更像是给这个员工配了一本分门别类的手册，做报销翻报销那章，写代码翻代码规范那章，各取所需。这个抽象带来的直接好处是上下文利用率大幅提升，尤其是当你同时维护好几个项目、每个项目规范还不一样的时候。

2.2 为什么选择 CLI 作为主要交互形态

项目里有个关键词是skills CLI，这说明它把命令行作为核心入口。这个选择我觉得挺务实的，原因有几个。

第一，AI coding agent 本身很多就是跑在终端里的，Claude Code 就是典型代表。CLI 形态和 agent 的工作环境天然契合，不需要额外起一个 GUI 或者服务。第二，CLI 天然适合做组合和自动化，你可以把 skill 的加载、执行、验证串成脚本，接进 CI 流程。第三，CLI 的产物是文本，文本就意味着可 diff、可 review、可版本控制，这对团队协作太重要了。

对比一下，如果做成一个图形界面，虽然上手门槛低，但很难嵌入到现有的开发工作流里。我见过不少团队尝试用网页工具管理 prompt，最后都因为“和代码仓库脱节”而放弃。CLI 这条路虽然看起来朴素，但它是能真正长在工程实践里的形态。

2.3 与 test-driven-development 的深度绑定

热词里出现了test-driven-development，这不是偶然。agent-skills 这类项目特别强调 TDD，背后有很实际的工程考量。

AI 生成代码最大的风险是什么？是它看起来很对，但实际跑起来一堆边界问题。你让 agent 写个函数，它给你写得漂漂亮亮，结果空输入、超长输入、并发场景全没考虑。TDD 的价值在于，它把“正确性”这件事从主观判断变成了可执行的验证。你先写测试，测试定义了行为边界，agent 再根据测试去实现，最后跑测试验证。整个闭环里，agent 的产出有了客观的验收标准。

我在实际项目里深刻体会到，给 agent 配一套能自动跑的测试，比给它写一千字的需求描述都管用。因为测试是机器可验证的，agent 能自己跑、自己看结果、自己迭代。这也是为什么 agent-skills 会把 TDD 相关的 skill 作为重点方向——它让 agent 从“生成代码”进化到“生成并验证代码”。

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

3.1 一个 skill 到底由哪些部分组成

虽然不同实现细节有差异，但一个典型的 skill 通常包含这几个要素，我按重要性排一下：

• 触发条件（when to use）：描述什么场景下该激活这个技能。这部分写得好不好，直接决定 agent 能不能在正确的时机调用它。写得太宽泛，agent 会滥用；写得太窄，该用的时候想不起来。
• 执行指令（instructions）：具体要做什么、按什么顺序做、有哪些约束。这是 skill 的主体。
• 输入输出约定（I/O contract）：需要哪些参数、产出什么格式。有了明确约定，skill 之间才能组合。
• 验证方式（validation）：怎么判断这次执行成功了。对编程类 skill 来说，通常就是跑测试。

我建议你在写自己的 skill 时，把“触发条件”当成最重要的部分来打磨。因为 agent 的决策质量，很大程度上取决于它能不能准确判断“现在该用哪个技能”。这就像给一个团队定分工，职责边界清晰，协作才顺畅。

3.2 技能粒度怎么把握：太粗和太细都是坑

这是我在实践里踩得最狠的一个坑。一开始我图省事，写了个巨无霸 skill，叫“帮我开发一个功能”，里面塞了需求分析、设计、编码、测试、文档一大堆步骤。结果 agent 执行起来非常不稳定，经常在中途迷失，或者跳过某些步骤。

后来我改成细粒度，把“写单元测试”“实现函数”“重构”“生成文档”拆成独立 skill。这下灵活了，但新问题来了：agent 经常不知道该按什么顺序组合它们，或者组合错了。

我的经验是，粒度应该按“一个可独立验证的产出”来切。比如“写一个通过测试的函数实现”就是一个合适的粒度，因为它有明确的验收标准（测试通过）。而“开发一个功能”太粗，“写一行代码”又太细。你可以用这个标准去衡量自己的 skill 划分：每个 skill 结束时，是不是有一个可以客观判断成功与否的结果？如果是，粒度就差不多了。

3.3 让 skill 可组合：接口设计的关键

skill 真正的威力在于组合。单个 skill 再强，也只是一个工具；能串起来形成工作流，才是系统。要让 skill 可组合，关键在于输入输出的标准化。

举个具体例子。假设你有两个 skill：一个叫generate-test，输入是函数签名和需求描述，输出是测试文件路径；另一个叫implement-to-pass，输入是测试文件路径，输出是实现代码。这两个 skill 能串起来，是因为前者的输出正好是后者的输入。如果你把generate-test的输出设计成一段自然语言描述，那implement-to-pass就没法直接接上，中间还得加个转换步骤。

所以设计 skill 的时候，我强烈建议你先想清楚它在工作流里的上下游是谁，然后倒推它的输入输出格式。能用结构化数据（JSON、文件路径、明确的标识符）就别用自然语言，这样组合起来才稳。

提示：skill 的输入输出尽量用机器可解析的格式。自然语言适合人读，但不适合 skill 之间传递。这一点在搭建多步骤工作流时尤其关键。

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

4.1 环境准备：把 CLI 跑起来

假设你已经有一个能用的 AI coding agent 环境（比如 Claude Code 已经装好并能正常对话），接下来是接入 agent-skills 的 CLI。由于项目还在演进，具体命令可能变化，我给出的是通用思路，你对照官方文档调整。

第一步是获取 CLI 工具。通常这类工具会通过包管理器分发，比如 npm 或者 pip。你需要先确认本机的运行时环境版本满足要求。我一般会先跑一下版本检查，避免因为版本太老导致奇怪的报错。

# 检查 node 环境（如果 CLI 是 npm 分发的） node -v npm -v # 检查 python 环境（如果 CLI 是 pip 分发的） python3 --version pip3 --version

第二步是安装。安装完别急着用，先跑一下帮助命令，看看有哪些子命令、参数怎么传。这一步能帮你快速建立对工具全貌的认知。

# 查看帮助，了解可用命令 skills --help # 查看某个子命令的详细用法 skills <subcommand> --help

第三步是初始化项目级的 skill 目录。大多数这类工具会在项目根目录下创建一个约定好的文件夹（比如.skills/或skills/），用来存放 skill 定义文件。初始化之后，你会得到一个基础模板，照着改就行。

4.2 写第一个 skill：从 TDD 场景切入

我建议第一个 skill 就从 TDD 场景开始，因为它的验证闭环最清晰，最容易看到效果。下面是一个 skill 定义的结构示例，我用伪代码加注释的方式展示，你对照自己项目的实际格式调整。

# skill 名称，简短明确 name: write-failing-test # 触发条件：什么时候该用这个 skill when: | 当需要为新功能或 bug 修复编写测试时使用。 适用于已有明确函数签名或接口定义的场景。 # 输入约定 inputs: - target: 被测函数或模块的标识 - behavior: 期望的行为描述 - framework: 测试框架（如 pytest, jest） # 执行指令 instructions: | 1. 根据 target 定位被测代码所在文件 2. 根据 behavior 设计至少 3 个测试用例，覆盖正常路径和边界情况 3. 使用 framework 指定的框架编写测试 4. 运行测试，确认测试失败（红） 5. 输出测试文件路径和失败信息 # 输出约定 outputs: - test_file: 测试文件路径 - failure_log: 测试失败日志 # 验证方式 validation: | 测试必须处于失败状态，且失败原因是断言不通过， 而不是语法错误或导入错误。

这个 skill 的关键设计点在于：它明确要求“测试必须失败”。这看起来反直觉，但正是 TDD 的精髓——先看到红，才能确认测试真的在测东西。如果测试一上来就通过，那要么是测试写错了，要么是功能已经实现了，两种情况都需要 agent 停下来重新判断。

4.3 串起完整工作流：红-绿-重构

有了write-failing-test，再配一个implement-to-pass，就能串成 TDD 的核心循环。下面是我实际用的一套组合流程，你可以直接参考。

第一步，agent 调用write-failing-test，产出测试文件和失败日志。第二步，agent 调用implement-to-pass，输入是上一步的测试文件路径，要求写出能让测试通过的最小实现。第三步，agent 跑测试，确认变绿。第四步，如果项目有重构 skill，再调用一次做代码清理，重构后重新跑测试确保还是绿的。

这个流程里有个细节值得说：“最小实现”这个约束很重要。如果不加约束，agent 容易过度设计，写一堆当前测试用不到的功能。加上“最小”之后，它会聚焦在让测试通过这件事上，代码反而更干净。这也是 TDD 本身倡导的理念，agent-skills 只是把它工程化了。

# 伪代码：串起工作流 skills run write-failing-test --target src/calc.py --behavior "加法处理负数" # 产出 test_calc.py，测试失败 skills run implement-to-pass --test-file tests/test_calc.py # 产出实现，测试通过 skills run refactor --scope src/calc.py # 重构后重跑测试

4.4 参数选择与验证：怎么判断 skill 写得好不好

写完 skill 不能就完事了，得验证它是否真的可靠。我一般用三个指标来衡量：

这三个指标不用一开始就追求很高，先跑通再说。我自己的经验是，第一版 skill 触发准确率能到 60% 就不错了，剩下的靠迭代“触发条件”的描述来优化。每次 agent 该用没用、或者不该用乱用，都是一次优化机会，把那个场景补进触发条件里。

注意：不要为了追求指标好看而把触发条件写得极其宽泛。宽泛的触发条件会让 agent 频繁误用 skill，短期指标好看，长期工作流会乱套。

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

5.1 agent 不调用我写的 skill 怎么办

这是最高频的问题。原因通常有三个：触发条件描述和实际任务对不上、skill 没有被正确加载、或者 agent 的上下文里已经有更强势的指令覆盖了它。

排查顺序我建议这样走：先确认 skill 文件在正确的目录下、格式没写错，用 CLI 的列表命令看看能不能列出来。然后手动构造一个明显该触发它的任务，观察 agent 的反应。如果还是不触发，就把触发条件里的关键词往任务描述里靠，看看是不是措辞差异导致的。

我踩过的一个具体坑是：触发条件里写的是“编写单元测试”，但我在对话里说的是“给这个函数加个测试”，agent 就没匹配上。后来我把常见同义表达都列进触发条件，问题就解决了。触发条件要写得像“用户可能的各种说法”，而不是像“官方术语表”。

5.2 skill 执行到一半失败，怎么定位

skill 执行失败通常分两类：一类是 skill 本身逻辑有问题，另一类是外部环境问题（依赖没装、路径不对、权限不足）。区分方法很简单，看失败信息。

如果是 skill 逻辑问题，失败信息往往和业务相关，比如“找不到目标函数”“测试断言不匹配”。这时候要回去看 skill 的指令是不是有歧义，或者输入约定是不是太宽松。如果是环境问题，失败信息通常是“命令不存在”“文件找不到”“权限拒绝”这类，那就先修环境。

我一般会在 skill 里加一个前置检查步骤，先验证依赖和环境，再执行主体逻辑。这样失败的时候能快速定位是环境还是逻辑。这个习惯帮我省了大量排查时间。

5.3 多个 skill 冲突了怎么办

当 skill 数量多起来，冲突几乎不可避免。典型表现是 agent 同时激活了两个功能重叠的 skill，或者两个 skill 对同一个文件做了矛盾的操作。

解决办法有两个方向。一是在触发条件里明确互斥关系，比如 A skill 的触发条件里加一句“当 B skill 已激活时不使用本 skill”。二是引入优先级机制，给 skill 排个序，冲突时高优先级的生效。前者更精确，后者更省事，看你的场景选。

我个人的偏好是前者，因为显式声明互斥关系，读起来一目了然，维护起来也清楚。优先级机制虽然省事，但时间长了没人记得清谁高谁低，容易埋雷。

5.4 常见问题速查表

5.5 几个我踩过的坑和独家心得

第一个坑是过度依赖自然语言描述。我一开始所有 skill 的输入输出都用自然语言写，结果组合的时候 agent 经常理解偏差。后来改成结构化格式，稳定性立刻上来了。自然语言适合人读，但机器传递信息还是得靠结构。

第二个坑是skill 写太多太杂。有段时间我恨不得把每个操作都写成一个 skill，结果 agent 面对几十个 skill 反而不知道选哪个。后来我做了合并，把相关的操作归到一个 skill 里，用参数区分，数量降到十几个，效果反而更好。skill 不是越多越好，够用就行。

第三个心得是给 skill 写测试。对，skill 本身也可以测。我会准备一批典型任务描述，跑一遍看 agent 是否按预期调用 skill。这批测试用例随着 skill 迭代不断补充，相当于给 skill 系统本身做了回归测试。这个做法在 skill 数量多起来之后特别有价值，能防止改一个坏一片。

提示：skill 的迭代和代码一样，需要回归验证。准备一批固定的测试任务，每次改完 skill 都跑一遍，能避免大部分低级错误。

6. 把 agent-skills 用进真实项目的几点体会

聊了这么多技术和操作，最后说点更宏观的体会。agent-skills 这类工具真正改变的不是“AI 能不能写代码”，而是“AI 写代码这件事能不能被工程化管理”。过去我们用 AI 编程，很大程度上是碰运气，这次效果好下次不一定。有了 skill 系统之后，好的实践可以被固化、被复用、被团队共享，这才是它最大的价值。

我在团队里推这套东西的时候，最大的阻力不是技术，而是习惯。大家习惯了随手写 prompt，觉得搞一套 skill 系统太重。但用了一段时间之后，反馈普遍是“回不去了”，因为重复解释背景这件事真的太消耗精力。尤其是新项目启动的时候，一套现成的 skill 库能省下大量沟通成本。

如果你现在还在观望，我的建议是从一个最小的 TDD skill 开始，别一上来就搞大而全。跑通一个闭环，体会到“agent 自己写测试、自己实现、自己验证”的顺畅感之后，你自然会想扩展更多。这个领域变化很快，但底层逻辑是稳的：把可复用的能力沉淀下来，让 agent 按需调用。抓住这条主线，具体工具怎么变都不慌。