1. 从"agent-skills"这个标题说起：它到底在解决什么问题

第一次看到agent-skills这个仓库名，我脑子里冒出来的第一个念头是：这又是一个把提示词打包成文件夹的项目吗？翻了一圈之后发现，它想做的事情比"提示词合集"要实在得多——它试图给 AI coding agent 定义一套可复用、可组合、可测试的能力单元，也就是所谓的 skill。

先把概念说清楚。这里的 skill 不是模型权重里的能力，而是外挂给 agent 的一套"操作手册 + 工具封装 + 验收标准"。你可以把它理解成给一个刚入职的实习生发的岗位 SOP：告诉他这类任务该按什么顺序做、用哪些命令、做到什么程度算合格。agent-skills这个项目就是把这些 SOP 标准化，让不同的 agent（Claude Code、各类 CLI agent、IDE 里的编码助手）都能加载同一套技能定义。

为什么这件事值得单独做一个项目？因为现在大多数人用 AI coding agent 的方式还停留在"聊天框里许愿"的阶段。你说一句"帮我加个登录功能"，agent 就开始自由发挥，写出来的东西能不能跑、边界情况处理没有、测试覆盖了没有，全靠运气。而 skill 化的思路是把"许愿"变成"派活"：任务有明确的输入输出、有固定的执行流程、有可验证的完成标准。

关键词里出现的test-driven-development其实透露了这个项目的核心取向——它把 TDD 当作一种 skill 来对待。这很关键。TDD 不是一个"建议你这么做"的软性规范，而是一套有严格节奏的流程：先写失败的测试、再写最小实现让它通过、最后重构。这套节奏非常适合被固化成一个 skill，因为它的每一步都有明确的判定条件，agent 不需要"理解意图"，只需要"执行流程并检查断言"。

所以agent-skills的定位可以概括成三句话：它是 agent 能力的模块化封装方案；它用 CLI 的方式做技能的安装、加载和管理；它把 TDD 这类工程实践变成了 agent 可以直接执行的流程，而不是停留在文档里的口号。适合谁来研究？如果你已经在用 Claude Code 或者类似的编码 agent，但总觉得输出质量不稳定、每次都要重复交代同样的规矩，那这个项目值得你花时间拆一拆。

2. skills CLI 的设计逻辑：为什么是命令行而不是配置文件

2.1 技能分发为什么绕不开一个 CLI

很多人第一反应是：技能不就是几个 markdown 文件吗，我手动拷到目录里不就行了，为什么要搞个 CLI？我一开始也这么想，直到我同时维护三四个项目、每个项目用的 agent 不一样、技能版本还各不相同的时候，才发现手动拷贝是灾难。

skills CLI存在的第一个理由是版本一致性。技能定义会迭代，今天你写的"代码审查 skill"要求检查五个点，下周可能变成七个点。如果靠手动拷贝，你根本不知道某个项目里用的是哪个版本。CLI 通过一个清单文件锁定版本，跟package.json锁定依赖是一个道理。

第二个理由是跨 agent 的可移植性。不同 agent 加载技能的目录约定、文件格式、元数据字段可能都不一样。CLI 充当了适配层：你写一份技能定义，CLI 负责把它转换成目标 agent 能识别的形式。这跟构建工具把同一份源码编译成不同平台产物是一个思路。

第三个理由比较隐蔽但很重要：可发现性。当技能多起来之后，"我到底装了哪些技能、每个技能干什么用"会变成一个真问题。CLI 提供的list、info这类子命令，本质上是在做技能的索引和检索。没有这层，技能库就会退化成一堆没人记得住的文件夹。

2.2 一个技能单元应该包含哪些部分

基于我对这类项目的理解，一个完整的 skill 通常由四块内容组成，缺一块都会影响可用性：

这里我要特别强调触发条件。这是最容易被忽略、但最影响体验的部分。一个技能如果触发条件写得太宽，比如"只要涉及代码就激活"，那它会污染所有对话；写得太窄，比如要求精确匹配某个文件名，那它基本不会被用到。好的触发条件应该描述的是任务类型而不是关键词，比如"当用户要求为已有函数补充测试时"就比"当消息里出现 test 时"要准确得多。

2.3 技能之间的组合与依赖

单个技能能解决的问题有限，真正有价值的是技能的组合。比如"写测试"和"重构"这两个技能，在 TDD 流程里是交替使用的：写测试 → 实现 → 重构 → 再写测试。如果技能之间不能组合，那 agent 每次只能执行一个孤立的动作，流程就断了。

agent-skills这类项目通常会在元数据里声明依赖关系，让 CLI 在安装时自动拉取前置技能。这跟包管理器的依赖解析是一回事。我在实际使用中踩过的一个坑是：循环依赖。技能 A 依赖 B，B 又依赖 A，安装时直接死循环。所以设计技能时一定要保证依赖是有向无环的，把公共部分抽成独立的原子技能。

提示：设计技能依赖时，先画出依赖图再动手写。我见过太多人凭感觉写依赖，最后装都装不上。

3. 把 TDD 做成 skill：流程固化的关键细节

3.1 为什么 TDD 特别适合被 skill 化

前面提到 TDD 有严格的节奏，这里展开说说为什么这个特性让它成为 skill 化的理想对象。

TDD 的核心循环是"红-绿-重构"：先写一个会失败的测试（红），然后写刚好能让它通过的最少代码（绿），最后在不改变行为的前提下清理代码（重构）。这个循环的每一步都有客观的判定条件——测试失败就是失败，通过就是通过，没有模糊地带。这跟"帮我优化一下这段代码"这种主观任务完全不同。

正因为判定条件客观，agent 执行 TDD skill 时不需要"理解"什么叫"优化好了"，它只需要运行测试、看结果、决定下一步。这大幅降低了 agent 出错的概率，也让整个流程可以被自动化验证。

3.2 一个 TDD skill 的执行步骤拆解

我把这类 skill 的典型执行流程拆成下面几步，每一步都对应 agent 的一个明确动作：

1. 解析需求，确定测试目标：agent 先要搞清楚"要测什么行为"。这一步的产出是一句话描述的行为规格，比如"当输入为空时，函数应返回空数组"。
2. 编写失败测试：根据行为规格写出测试代码，然后运行，确认它确实失败。这一步不能跳过——如果测试一上来就通过，说明要么测试写错了，要么功能已经存在。
3. 编写最小实现：只写让测试通过所需的代码，不多写一行。这是 TDD 最反直觉的地方，很多人忍不住"顺手把其他情况也处理了"，结果破坏了节奏。
4. 运行测试确认通过：全绿之后才能进入下一步。
5. 重构：在测试保护下清理代码，每次重构后都要重新运行测试。
6. 循环：回到第 1 步处理下一个行为。

这里第 2 步和第 3 步的顺序是绝对不能颠倒的。我见过有人为了"效率"先写实现再补测试，结果测试变成了对实现的描述，而不是对需求的描述，完全失去了 TDD 的意义。

3.3 让 agent 真正"先写测试"的难点

说起来简单，让 agent 老老实实先写测试其实很难。原因是训练数据里绝大多数代码都是"实现在前、测试在后"的，agent 有很强的惯性直接开始写实现。

解决这个问题的办法是在 skill 里加入强制检查点。比如要求 agent 在写任何实现代码之前，必须先输出测试文件的内容并运行一次，把失败输出贴出来。如果 agent 跳过了这一步直接写实现，skill 的验收标准就会判定失败。

另一个技巧是把"写测试"和"写实现"拆成两个独立的技能，中间用一个"确认测试失败"的技能隔开。这样 agent 在流程上就没法绕过测试环节了。这种拆分看起来啰嗦，但实测下来对约束 agent 行为非常有效。

注意：不要指望一次就把 TDD skill 调好。我前几次写的 skill，agent 总能找到各种理由跳过测试步骤，后来是靠不断加检查点才收敛的。

4. 在 Claude Code 里落地 agent-skills 的实操路径

4.1 环境准备阶段容易忽略的几件事

在 Claude Code 里使用技能，第一步是把技能放到它约定的目录下。不同版本的目录约定可能不同，所以先确认你当前版本的加载路径，别照着旧教程一顿操作最后发现根本没加载。

我建议的准备顺序是这样的：

• 先确认 Claude Code 的版本，用claude --version之类的命令查看，版本不同加载机制可能有差异。
• 找到技能目录的约定位置，通常在用户配置目录下的一个固定子目录里。
• 先用一个最简单的技能做加载测试，确认能被识别，再批量导入。
• 检查技能的元数据格式是否符合当前版本要求，字段名大小写、必填项这些细节最容易出错。

这里有个很实际的坑：技能文件编码和换行符。如果你在 Windows 上编辑技能文件然后拿到 Linux 环境用，CRLF 换行符有时会导致解析异常。统一用 LF 能省掉很多莫名其妙的报错。

4.2 技能加载后的验证方法

技能装上了不代表能用。我习惯用三步验证法：

第一步，用list类命令确认技能出现在列表里，且状态是启用。第二步，构造一个明确应该触发该技能的任务，观察 agent 是否真的调用了它。第三步，检查 agent 的执行过程是否符合技能定义的步骤，而不是"看起来完成了任务但流程全错"。

第三步最容易被忽略。很多时候 agent 确实把任务做完了，但它是用自己的方式做的，根本没走你的 skill。这种情况下你以为 skill 生效了，其实只是运气好。要确认 skill 真的被使用，得看 agent 的执行日志里有没有引用技能定义。

4.3 和现有工作流的衔接

技能不是孤立存在的，它要嵌进你现有的开发流程。我的做法是把技能分成两类：流程类技能（比如 TDD、代码审查）和工具类技能（比如特定的构建、部署命令封装）。流程类技能在对话开始时激活，工具类技能在需要时按需调用。

衔接时要注意优先级冲突。如果你同时装了多个技能，它们的触发条件可能重叠，agent 不知道该听谁的。解决办法是在元数据里明确优先级，或者干脆把重叠的技能合并。我倾向于后者，因为优先级规则一多，维护成本就上去了。

5. 技能设计中的常见坑与排查链路

5.1 技能不触发：从现象到根因的排查

技能装了但从来不触发，这是最高频的问题。我的排查顺序是这样的：

先看触发条件是否过于具体。很多人写触发条件时喜欢堆关键词，结果 agent 的输入只要措辞稍有不同就匹配不上。把触发条件从"关键词匹配"改成"意图描述"通常能解决大半问题。

再看元数据字段是否被正确解析。有时候是字段名写错了，CLI 静默忽略了整个技能。这种情况要靠查看加载日志来发现，光看列表是看不出来的。

最后看技能之间是否互相屏蔽。如果两个技能的触发范围重叠，可能一个把另一个盖住了。临时禁用其他技能，只留一个测试，能快速定位。

5.2 技能触发了但执行走样

比不触发更麻烦的是触发了但执行不对。典型表现是 agent 跳过了技能里的某些步骤，或者顺序乱了。

根因通常是步骤描述不够强制。如果你写的是"建议先写测试"，agent 就可能不写；写成"必须先写测试并运行确认失败，否则不得进入下一步"，约束力就强很多。措辞的强制性直接影响 agent 的遵守程度，这一点我在反复调试中体会很深。

另一个原因是步骤之间存在歧义。比如"处理边界情况"这种描述，agent 根本不知道具体指哪些情况。把每一步都写成可执行、可验证的动作，是避免走样的根本办法。

5.3 技能版本升级后的兼容问题

技能会迭代，升级之后老项目可能出问题。我踩过的坑是：新版本技能改了元数据格式，老项目里锁定的旧版本加载器解析不了，直接报错。

应对办法是给技能做语义化版本，并且在项目里锁定版本号，跟锁依赖一个道理。升级时先在测试项目里验证，确认没问题再推到主项目。别图省事直接全局升级，出问题的时候回滚很麻烦。

6. 把技能库当成长期资产来经营

用了一段时间之后我意识到，技能库不是一次性配置，而是需要持续经营的资产。几个我总结出来的经验：

保持技能的原子性。一个技能只做一件事，做透。我早期喜欢写"大而全"的技能，一个技能包揽从需求分析到部署的全流程，结果就是任何一个环节出问题都要改整个技能，牵一发动全身。拆成原子技能后，复用率和可维护性都上来了。

给技能写测试。听起来有点绕——给约束 agent 的技能写测试。但这是可行的：构造一批典型输入，检查 agent 是否按预期触发了技能、是否走完了流程。技能本身的质量也需要被验证，否则你永远不知道它是不是在"假装工作"。

定期清理。技能库会积累，有些技能随着项目变化已经没用了，有些被新技能取代了。定期过一遍，把废弃的删掉，能减少触发冲突，也让 agent 的选择更清晰。

记录踩坑。每个技能旁边记一句"为什么这么写"，比如"这里必须加检查点，否则 agent 会跳过测试"。这些注释在几个月后你自己回头看的时候，价值巨大。

最后分享一个我个人的小习惯：每次 agent 执行技能出了意外，我都会问自己一句"是技能没写清楚，还是 agent 能力不够"。大部分时候答案是前者。技能设计的本质，是把模糊的期望翻译成精确的指令，这件事没有终点，只有不断逼近。