1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新同事来培养的技能体系。关键词里同时出现了skills CLI、Claude Code、test-driven-development这三者放在一起指向一个很明确的问题域——如何让一个命令行里的 AI 编码代理稳定地按照工程规范干活而不是每次都要你从头解释一遍我们团队怎么做事。大多数人用 AI 编码工具的方式是对话式的打开终端敲一句需求等它吐代码不满意再补一句。这种方式在一次性脚本上没问题但一旦进入真实项目——有测试、有 lint、有提交规范、有目录约定——你就会发现每次都要重复交代背景而且它经常自作聪明地跳过测试、改坏命名、把临时文件留在仓库里。agent-skills这类项目要解决的就是这个把怎么做事从每次对话里抽出来固化成可复用、可版本管理的技能包让 agent 在需要的时候自动加载。这篇文章适合三类人看一是已经在用 Claude Code 或类似 CLI agent、但觉得每次都要重新调教的开发者二是想给团队建立 AI 编码规范、但不知道从哪下手的技术负责人三是刚接触 agent 概念、想搞清楚skill 到底和 prompt 有什么区别的入门者。我会从技能包的本质讲起拆到目录结构、CLI 用法、TDD 技能的具体设计再聊实测中踩过的坑。2. agent-skills 到底解决了什么问题2.1 普通 prompt 和 skill 的本质区别很多人把 skill 理解成长一点的 prompt这个理解会直接导致用错。我打个比方prompt 像是你临时给同事口头交代一件事说完就散了skill 像是公司里的一份 SOP 文档放在共享盘里谁需要谁去翻而且文档本身会被 review、被更新、被版本控制。具体到技术层面差异体现在三个地方。第一是加载时机prompt 是你主动塞进上下文的skill 通常是 agent 根据当前任务判断我需要这个能力再去读取的。第二是结构化程度prompt 可以是一段自由文本skill 一般有固定的元数据头名称、描述、触发条件加正文。第三是可组合性多个 skill 可以叠加使用比如写测试的 skill 和提交规范的 skill 同时生效而多个 prompt 堆在一起很容易互相打架。提示判断一个东西是不是真正的 skill看它能不能被按需触发。如果每次都必须你手动粘贴那它本质上还是 prompt只是长一点而已。2.2 为什么是 CLI 而不是 IDE 插件关键词里skills CLI排在很前面这个选择值得说一下。IDE 插件比如 VS Code 里的各种 AI 助手的优势是图形化、上手快但劣势也很明显它和编辑器强绑定换编辑器就没了而且插件的上下文管理往往是黑盒你不太清楚它到底把哪些文件塞进了模型。CLI 形态的 skill 管理则更工程化。它天然适合放进 CI、适合写进脚本、适合和 git 一起做版本管理。你可以想象一个场景团队里新来一个人clone 仓库之后跑一条命令所有 AI 编码规范就装好了不需要他手动配置任何东西。这种基础设施化的能力是插件形态很难做到的。2.3 目标用户和使用边界agent-skills这类东西不是给我就想让 AI 帮我写个正则的人用的。它的目标用户是那些把 AI agent 当成日常生产力工具、并且对代码质量有要求的开发者。如果你只是偶尔用一下配置 skill 的投入产出比不划算。它的边界也要说清楚skill 管的是流程和规范不管模型能力。如果模型本身写不出正确的算法再好的 skill 也救不了。skill 的价值在于——当模型有能力做对的时候确保它每次都按对的方式做而不是这次记得写测试、下次就忘了。3. 一个 skill 包的目录长什么样3.1 核心文件与元数据约定虽然agent-skills的具体实现细节会随版本变化但这类项目的目录结构有很强的共性。一个典型的 skill 包大致是这样组织的agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ └── references/ │ │ └── testing-patterns.md │ ├── commit-conventions/ │ │ └── SKILL.md │ └── code-review/ │ ├── SKILL.md │ └── scripts/ │ └── lint-check.sh ├── cli/ │ └── index.js └── README.md关键在SKILL.md这个文件。它通常以 YAML frontmatter 开头声明这个技能的元信息--- name: test-driven-development description: 在实现新功能或修复 bug 时强制先写失败测试再写实现 trigger: 当任务涉及新增函数、修改业务逻辑、修复缺陷时 ---name是唯一标识description是给 agent 看的这个技能是干嘛的trigger则是判断何时加载的依据。正文部分才是真正的指令内容写清楚第一步做什么、第二步做什么、什么情况下算完成。3.2 为什么要把 references 和 scripts 分开我特别想强调references/和scripts/这两个子目录的设计。很多人写 skill 喜欢把所有东西塞进一个 md 文件结果文件长到几千行agent 读起来反而抓不住重点。正确的做法是分层SKILL.md只放决策逻辑和主流程控制在几百行以内references/放详细的参考资料比如具体的测试写法示例、边界情况清单agent 需要深入某个细节时再去读scripts/放可执行的脚本比如跑 lint、跑测试的命令封装。这样设计的好处是上下文经济。agent 的上下文窗口是有限资源主流程必须精简细节按需加载。我实测下来把一个大 skill 拆成主文件 3 个 reference之后agent 执行任务的准确率明显提升因为它不会被无关细节干扰。3.3 命名与版本管理的一些经验命名上有个坑我踩过不要用太泛的词做 skill 名比如coding、helper这种。agent 判断是否加载时靠的是 name 和 description 的语义匹配名字太泛会导致它在不该加载的时候加载。用test-driven-development、api-error-handling这种具体到动作的名字匹配精度高很多。版本管理方面skill 应该和代码一起进 git。每次你发现 agent 又犯了某个老毛病不要只是在对话里纠正它而是回头去改对应的 skill 文件然后提交。这样规范是长出来的而不是一次性设计出来的。我自己的仓库里test-driven-development这个 skill 改了不下二十次每次都是被实际问题逼出来的改进。4. skills CLI 的安装与日常用法4.1 环境准备中最容易忽略的细节CLI 类工具的安装本身不复杂通常是 npm 全局安装或者直接 clone 仓库跑脚本。但有几个细节新手经常忽略。第一是Node 版本。这类 CLI 工具往往用了较新的语法特性Node 版本太低会直接报错。装之前先node -v看一眼建议 18 以上。第二是全局 bin 路径是否在 PATH 里npm 全局安装后命令找不到十有八九是这个问题。第三是权限在类 Unix 系统上全局安装可能需要处理目录权限但我不建议直接用管理员权限跑 npm更稳妥的做法是配置一个用户级的全局目录。# 检查环境 node -v npm -v # 查看 npm 全局路径是否在 PATH 中 npm config get prefix echo $PATH如果 prefix 不在 PATH 里把它加进去然后重新打开终端。这一步看起来基础但我见过太多人卡在这里以为是工具坏了。4.2 常用命令与工作流CLI 的核心命令一般围绕列出、安装、更新、移除这几个动作。假设命令入口是skills典型用法如下# 列出当前可用的技能 skills list # 安装某个技能到当前项目 skills add test-driven-development # 查看某个技能的详细内容 skills show test-driven-development # 更新所有已安装技能 skills update这里有个工作流上的建议区分全局技能和项目级技能。像提交信息规范这种跨项目通用的装到全局像这个项目特有的 API 错误处理约定这种装到项目级跟着仓库走。混在一起会导致项目之间互相污染。4.3 让 agent 真正用上技能的关键一步装完技能不等于 agent 就会用。这里有个衔接问题CLI 把技能文件放到了某个约定目录但 agent 怎么知道去那里读通常有两种机制。一种是约定目录自动发现agent 启动时会扫描特定路径比如项目根目录下的.agent/skills/把技能元数据加载进上下文。另一种是显式声明在项目的 agent 配置文件里列出要启用的技能。我建议优先用第一种因为它对 agent 透明你不需要每次提醒。但要确认你的 agent 版本支持自动发现并且目录路径和它期望的一致。实测中路径差一个层级就会导致技能静默失效——不报错但也不生效这种问题最难查。注意技能装了但没生效是最高频的问题。排查顺序是目录路径对不对 → 元数据格式对不对 → agent 版本支不支持自动发现 → 有没有被其他配置覆盖。5. test-driven-development 技能的设计拆解5.1 为什么 TDD 特别适合做成 skill在agent-skills的关键词里test-driven-development是唯一一个具体的方法论这不是偶然。TDD 天然适合做成 skill原因有三。第一TDD 有明确的、可验证的步骤序列先写失败测试 → 运行确认失败 → 写最小实现 → 运行确认通过 → 重构。这种有明确检查点的流程正好是 agent 擅长的——它不需要创造力只需要按步骤执行并在每步验证。第二TDD 是反直觉的。模型的默认行为是直接写实现因为训练数据里大部分代码都是实现代码。如果不强制它几乎不会主动先写测试。skill 的作用就是把这个反直觉的流程钉死。第三TDD 的失败模式很清晰。如果 agent 跳过了确认测试失败这一步你很容易发现——因为测试可能一开始就是通过的说明测试根本没测到东西。这种可观测性让 skill 的调试变得简单。5.2 技能正文里应该写死哪些约束一个能真正约束住 agent 的 TDD skill正文不能只是请遵循 TDD这种废话。它需要写死具体的、可检查的约束。我总结了几条必须写进去的禁止在测试文件存在之前创建实现文件。这条是硬约束防止 agent先写实现再补测试。每次只处理一个测试用例。防止它一口气写十个测试再写一大坨实现那样就退化成先实现后测试了。必须实际运行测试命令并展示输出。不能只是我认为测试会失败要真的跑。红灯阶段必须确认失败原因是功能未实现而不是语法错误或导入失败。这条特别重要我后面会展开。把这些写成明确的必须/禁止句式比写成建议有效得多。模型对祈使句的遵循度明显高于建议句。5.3 红灯阶段的验证为什么不能省这是我在实际使用中体会最深的一点。TDD 的红灯阶段测试应该失败看起来是走形式但它其实是整个流程的质量闸门。问题在于测试失败有很多种原因可能是功能没实现正确也可能是测试文件本身有语法错误、导入路径写错、测试框架没配置好错误。如果 agent 看到测试失败了就认为红灯通过然后去写实现最后测试通过了——但通过的原因可能是它顺手把测试也改对了而不是实现真的正确。所以 skill 里必须要求 agent 在红灯阶段检查失败信息的具体内容。失败信息应该明确指向断言失败或函数未定义而不是模块找不到或语法错误。这个检查动作是把 TDD 从形式变成实质的关键。# 红灯阶段应该看到类似这样的输出 FAIL src/calculator.test.js ✕ add(1, 2) should return 3 ReferenceError: add is not defined # 而不是这样的输出 FAIL src/calculator.test.js ✕ Test suite failed to run SyntaxError: Unexpected token前者说明测试写对了、实现还没写是健康的红灯后者说明测试本身有问题得先修测试。6. 把技能接进 Claude Code 的实际配置6.1 项目级配置与全局配置的取舍Claude Code 这类 CLI agent 的配置分两层全局配置用户目录下和项目级配置项目根目录下。技能放哪一层取决于它的适用范围。我的做法是通用工程规范放全局项目特有约定放项目级。比如提交信息用约定式提交这种放全局所有项目受益这个项目的 API 层必须走统一的错误包装函数这种放项目级跟着仓库走。项目级配置的好处是团队共享。你把技能文件提交进仓库同事 clone 下来就自动生效不需要口头传达。这也是为什么我前面强调技能要进 git——它本质上是团队规范的可执行版本。6.2 让 agent 在正确的时机加载技能配置好之后还要验证 agent 是否在正确的时机加载了技能。这里有个实用技巧故意制造一个应该触发技能的场景观察 agent 的行为。比如你配置了 TDD 技能那就给它一个给现有函数加一个边界处理的任务。如果它直接改实现说明技能没生效如果它先去找测试文件、或者先写一个测试说明生效了。这种行为验证比看配置文件可靠得多因为配置对不对和生效不生效是两回事。如果没生效排查顺序是技能目录路径 → 元数据格式 → agent 版本 → 是否有其他配置覆盖。我遇到过元数据里description写得太模糊导致匹配不上的情况改成具体的动作描述后就正常了。6.3 和模型选择的关系关键词里提到了用第三方模型接入的场景。这里要说清楚一点技能的有效性和模型能力是乘法关系不是加法。技能提供流程约束模型提供执行能力。如果模型本身遵循指令的能力弱再好的技能也会被打折扣——它可能读了技能但执行时走样。所以我的建议是技能体系先在能力较强的模型上跑通、验证有效再考虑迁移到其他模型。迁移时重点观察的是流程遵循度——它是否还老老实实按步骤走还是开始跳步。如果跳步严重可能需要把技能里的约束写得更强硬或者接受这个模型只适合做更简单的任务。7. 实测中踩过的坑和排查思路7.1 技能冲突两个技能给出矛盾指令我遇到过一次典型冲突一个技能要求每次修改都先跑全量测试另一个技能要求快速迭代只跑相关测试。结果 agent 在两个指令之间反复横跳行为很不稳定。这类问题的根因是技能之间没有优先级机制。解决办法有两个一是合并冲突的技能把矛盾点在一个文件里说清楚什么情况下用哪种策略二是给技能加优先级标记让 agent 知道谁覆盖谁。我倾向于第一种因为合并的过程本身就是梳理规范的过程。7.2 技能太长导致 agent 读了但没记住前面提过上下文经济这里展开说。我一开始写 TDD 技能时恨不得把所有测试技巧都塞进去结果文件两千多行。实测发现 agent 执行时经常漏掉后面的约束——不是它不想遵守是上下文里信息太多注意力被稀释了。后来我做了拆分主文件只保留核心流程和硬约束控制在 300 行以内详细的测试模式、边界情况清单挪到references/里主文件里用一句话指路需要具体测试写法时参考 references/testing-patterns.md。改完之后流程遵循度明显提升。7.3 技能看起来生效了但实际没约束住这是最隐蔽的坑。表现是agent 确实先写了测试看起来在走 TDD但仔细看它是先在心里想好了实现然后补了一个刚好能通过的测试。测试是有了但失去了 TDD 的意义——测试没有驱动设计只是事后装饰。识别这种情况的方法是看测试的粒度。真正的 TDD测试是一个一个加的每个测试对应一小步实现。如果 agent 一次性写了五个测试然后一次性写完实现那基本可以判定是伪 TDD。对策是在技能里明确要求一次一个测试用例写完一个跑一次。7.4 排查链路的一个真实案例有次我发现 TDD 技能完全没生效agent 直接改实现。排查过程是这样的第一步确认技能文件存在且路径正确——没问题。第二步检查元数据格式发现trigger字段我写成了中文描述而 agent 的匹配逻辑可能对中文支持不好。第三步把trigger改成中英混合、并加上具体的关键词如 new feature、bug fix、implement重新测试。第四步行为验证这次 agent 先去找测试文件了。这个案例的教训是元数据里的触发条件要写得机器友好用具体的动作词而不是抽象的概念词。抽象词人看得懂但匹配算法不一定能对上。8. 关于技能体系长期维护的一些想法技能体系不是一次配好就完事的它需要持续维护。我的做法是建立一个简单的反馈循环每次 agent 犯了重复性的错误就问自己这是不是应该在技能里约束一下如果是就去改技能文件并提交。这个循环跑久了你会发现技能库慢慢变成了团队工程规范的活文档——它不只是给 AI 看的新人读一遍也能快速理解团队怎么做事。这可能是agent-skills这类项目最有价值的副产品为了让 AI 遵守规范你被迫把规范写清楚了而写清楚规范这件事对团队里的人来说同样有价值。另外提醒一点技能不要贪多。我见过有人一口气装了二十个技能结果 agent 每次任务都要在大量技能里做匹配反而变慢、变不准。从三五个核心技能开始用出效果了再加是比较稳的节奏。技能的价值在于被真正用起来而不是躺在目录里。
1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新同事来培养的技能体系。关键词里同时出现了skills CLI、Claude Code、test-driven-development这三者放在一起指向一个很明确的问题域——如何让一个命令行里的 AI 编码代理稳定地按照工程规范干活而不是每次都要你从头解释一遍我们团队怎么做事。大多数人用 AI 编码工具的方式是对话式的打开终端敲一句需求等它吐代码不满意再补一句。这种方式在一次性脚本上没问题但一旦进入真实项目——有测试、有 lint、有提交规范、有目录约定——你就会发现每次都要重复交代背景而且它经常自作聪明地跳过测试、改坏命名、把临时文件留在仓库里。agent-skills这类项目要解决的就是这个把怎么做事从每次对话里抽出来固化成可复用、可版本管理的技能包让 agent 在需要的时候自动加载。这篇文章适合三类人看一是已经在用 Claude Code 或类似 CLI agent、但觉得每次都要重新调教的开发者二是想给团队建立 AI 编码规范、但不知道从哪下手的技术负责人三是刚接触 agent 概念、想搞清楚skill 到底和 prompt 有什么区别的入门者。我会从技能包的本质讲起拆到目录结构、CLI 用法、TDD 技能的具体设计再聊实测中踩过的坑。2. agent-skills 到底解决了什么问题2.1 普通 prompt 和 skill 的本质区别很多人把 skill 理解成长一点的 prompt这个理解会直接导致用错。我打个比方prompt 像是你临时给同事口头交代一件事说完就散了skill 像是公司里的一份 SOP 文档放在共享盘里谁需要谁去翻而且文档本身会被 review、被更新、被版本控制。具体到技术层面差异体现在三个地方。第一是加载时机prompt 是你主动塞进上下文的skill 通常是 agent 根据当前任务判断我需要这个能力再去读取的。第二是结构化程度prompt 可以是一段自由文本skill 一般有固定的元数据头名称、描述、触发条件加正文。第三是可组合性多个 skill 可以叠加使用比如写测试的 skill 和提交规范的 skill 同时生效而多个 prompt 堆在一起很容易互相打架。提示判断一个东西是不是真正的 skill看它能不能被按需触发。如果每次都必须你手动粘贴那它本质上还是 prompt只是长一点而已。2.2 为什么是 CLI 而不是 IDE 插件关键词里skills CLI排在很前面这个选择值得说一下。IDE 插件比如 VS Code 里的各种 AI 助手的优势是图形化、上手快但劣势也很明显它和编辑器强绑定换编辑器就没了而且插件的上下文管理往往是黑盒你不太清楚它到底把哪些文件塞进了模型。CLI 形态的 skill 管理则更工程化。它天然适合放进 CI、适合写进脚本、适合和 git 一起做版本管理。你可以想象一个场景团队里新来一个人clone 仓库之后跑一条命令所有 AI 编码规范就装好了不需要他手动配置任何东西。这种基础设施化的能力是插件形态很难做到的。2.3 目标用户和使用边界agent-skills这类东西不是给我就想让 AI 帮我写个正则的人用的。它的目标用户是那些把 AI agent 当成日常生产力工具、并且对代码质量有要求的开发者。如果你只是偶尔用一下配置 skill 的投入产出比不划算。它的边界也要说清楚skill 管的是流程和规范不管模型能力。如果模型本身写不出正确的算法再好的 skill 也救不了。skill 的价值在于——当模型有能力做对的时候确保它每次都按对的方式做而不是这次记得写测试、下次就忘了。3. 一个 skill 包的目录长什么样3.1 核心文件与元数据约定虽然agent-skills的具体实现细节会随版本变化但这类项目的目录结构有很强的共性。一个典型的 skill 包大致是这样组织的agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ └── references/ │ │ └── testing-patterns.md │ ├── commit-conventions/ │ │ └── SKILL.md │ └── code-review/ │ ├── SKILL.md │ └── scripts/ │ └── lint-check.sh ├── cli/ │ └── index.js └── README.md关键在SKILL.md这个文件。它通常以 YAML frontmatter 开头声明这个技能的元信息--- name: test-driven-development description: 在实现新功能或修复 bug 时强制先写失败测试再写实现 trigger: 当任务涉及新增函数、修改业务逻辑、修复缺陷时 ---name是唯一标识description是给 agent 看的这个技能是干嘛的trigger则是判断何时加载的依据。正文部分才是真正的指令内容写清楚第一步做什么、第二步做什么、什么情况下算完成。3.2 为什么要把 references 和 scripts 分开我特别想强调references/和scripts/这两个子目录的设计。很多人写 skill 喜欢把所有东西塞进一个 md 文件结果文件长到几千行agent 读起来反而抓不住重点。正确的做法是分层SKILL.md只放决策逻辑和主流程控制在几百行以内references/放详细的参考资料比如具体的测试写法示例、边界情况清单agent 需要深入某个细节时再去读scripts/放可执行的脚本比如跑 lint、跑测试的命令封装。这样设计的好处是上下文经济。agent 的上下文窗口是有限资源主流程必须精简细节按需加载。我实测下来把一个大 skill 拆成主文件 3 个 reference之后agent 执行任务的准确率明显提升因为它不会被无关细节干扰。3.3 命名与版本管理的一些经验命名上有个坑我踩过不要用太泛的词做 skill 名比如coding、helper这种。agent 判断是否加载时靠的是 name 和 description 的语义匹配名字太泛会导致它在不该加载的时候加载。用test-driven-development、api-error-handling这种具体到动作的名字匹配精度高很多。版本管理方面skill 应该和代码一起进 git。每次你发现 agent 又犯了某个老毛病不要只是在对话里纠正它而是回头去改对应的 skill 文件然后提交。这样规范是长出来的而不是一次性设计出来的。我自己的仓库里test-driven-development这个 skill 改了不下二十次每次都是被实际问题逼出来的改进。4. skills CLI 的安装与日常用法4.1 环境准备中最容易忽略的细节CLI 类工具的安装本身不复杂通常是 npm 全局安装或者直接 clone 仓库跑脚本。但有几个细节新手经常忽略。第一是Node 版本。这类 CLI 工具往往用了较新的语法特性Node 版本太低会直接报错。装之前先node -v看一眼建议 18 以上。第二是全局 bin 路径是否在 PATH 里npm 全局安装后命令找不到十有八九是这个问题。第三是权限在类 Unix 系统上全局安装可能需要处理目录权限但我不建议直接用管理员权限跑 npm更稳妥的做法是配置一个用户级的全局目录。# 检查环境 node -v npm -v # 查看 npm 全局路径是否在 PATH 中 npm config get prefix echo $PATH如果 prefix 不在 PATH 里把它加进去然后重新打开终端。这一步看起来基础但我见过太多人卡在这里以为是工具坏了。4.2 常用命令与工作流CLI 的核心命令一般围绕列出、安装、更新、移除这几个动作。假设命令入口是skills典型用法如下# 列出当前可用的技能 skills list # 安装某个技能到当前项目 skills add test-driven-development # 查看某个技能的详细内容 skills show test-driven-development # 更新所有已安装技能 skills update这里有个工作流上的建议区分全局技能和项目级技能。像提交信息规范这种跨项目通用的装到全局像这个项目特有的 API 错误处理约定这种装到项目级跟着仓库走。混在一起会导致项目之间互相污染。4.3 让 agent 真正用上技能的关键一步装完技能不等于 agent 就会用。这里有个衔接问题CLI 把技能文件放到了某个约定目录但 agent 怎么知道去那里读通常有两种机制。一种是约定目录自动发现agent 启动时会扫描特定路径比如项目根目录下的.agent/skills/把技能元数据加载进上下文。另一种是显式声明在项目的 agent 配置文件里列出要启用的技能。我建议优先用第一种因为它对 agent 透明你不需要每次提醒。但要确认你的 agent 版本支持自动发现并且目录路径和它期望的一致。实测中路径差一个层级就会导致技能静默失效——不报错但也不生效这种问题最难查。注意技能装了但没生效是最高频的问题。排查顺序是目录路径对不对 → 元数据格式对不对 → agent 版本支不支持自动发现 → 有没有被其他配置覆盖。5. test-driven-development 技能的设计拆解5.1 为什么 TDD 特别适合做成 skill在agent-skills的关键词里test-driven-development是唯一一个具体的方法论这不是偶然。TDD 天然适合做成 skill原因有三。第一TDD 有明确的、可验证的步骤序列先写失败测试 → 运行确认失败 → 写最小实现 → 运行确认通过 → 重构。这种有明确检查点的流程正好是 agent 擅长的——它不需要创造力只需要按步骤执行并在每步验证。第二TDD 是反直觉的。模型的默认行为是直接写实现因为训练数据里大部分代码都是实现代码。如果不强制它几乎不会主动先写测试。skill 的作用就是把这个反直觉的流程钉死。第三TDD 的失败模式很清晰。如果 agent 跳过了确认测试失败这一步你很容易发现——因为测试可能一开始就是通过的说明测试根本没测到东西。这种可观测性让 skill 的调试变得简单。5.2 技能正文里应该写死哪些约束一个能真正约束住 agent 的 TDD skill正文不能只是请遵循 TDD这种废话。它需要写死具体的、可检查的约束。我总结了几条必须写进去的禁止在测试文件存在之前创建实现文件。这条是硬约束防止 agent先写实现再补测试。每次只处理一个测试用例。防止它一口气写十个测试再写一大坨实现那样就退化成先实现后测试了。必须实际运行测试命令并展示输出。不能只是我认为测试会失败要真的跑。红灯阶段必须确认失败原因是功能未实现而不是语法错误或导入失败。这条特别重要我后面会展开。把这些写成明确的必须/禁止句式比写成建议有效得多。模型对祈使句的遵循度明显高于建议句。5.3 红灯阶段的验证为什么不能省这是我在实际使用中体会最深的一点。TDD 的红灯阶段测试应该失败看起来是走形式但它其实是整个流程的质量闸门。问题在于测试失败有很多种原因可能是功能没实现正确也可能是测试文件本身有语法错误、导入路径写错、测试框架没配置好错误。如果 agent 看到测试失败了就认为红灯通过然后去写实现最后测试通过了——但通过的原因可能是它顺手把测试也改对了而不是实现真的正确。所以 skill 里必须要求 agent 在红灯阶段检查失败信息的具体内容。失败信息应该明确指向断言失败或函数未定义而不是模块找不到或语法错误。这个检查动作是把 TDD 从形式变成实质的关键。# 红灯阶段应该看到类似这样的输出 FAIL src/calculator.test.js ✕ add(1, 2) should return 3 ReferenceError: add is not defined # 而不是这样的输出 FAIL src/calculator.test.js ✕ Test suite failed to run SyntaxError: Unexpected token前者说明测试写对了、实现还没写是健康的红灯后者说明测试本身有问题得先修测试。6. 把技能接进 Claude Code 的实际配置6.1 项目级配置与全局配置的取舍Claude Code 这类 CLI agent 的配置分两层全局配置用户目录下和项目级配置项目根目录下。技能放哪一层取决于它的适用范围。我的做法是通用工程规范放全局项目特有约定放项目级。比如提交信息用约定式提交这种放全局所有项目受益这个项目的 API 层必须走统一的错误包装函数这种放项目级跟着仓库走。项目级配置的好处是团队共享。你把技能文件提交进仓库同事 clone 下来就自动生效不需要口头传达。这也是为什么我前面强调技能要进 git——它本质上是团队规范的可执行版本。6.2 让 agent 在正确的时机加载技能配置好之后还要验证 agent 是否在正确的时机加载了技能。这里有个实用技巧故意制造一个应该触发技能的场景观察 agent 的行为。比如你配置了 TDD 技能那就给它一个给现有函数加一个边界处理的任务。如果它直接改实现说明技能没生效如果它先去找测试文件、或者先写一个测试说明生效了。这种行为验证比看配置文件可靠得多因为配置对不对和生效不生效是两回事。如果没生效排查顺序是技能目录路径 → 元数据格式 → agent 版本 → 是否有其他配置覆盖。我遇到过元数据里description写得太模糊导致匹配不上的情况改成具体的动作描述后就正常了。6.3 和模型选择的关系关键词里提到了用第三方模型接入的场景。这里要说清楚一点技能的有效性和模型能力是乘法关系不是加法。技能提供流程约束模型提供执行能力。如果模型本身遵循指令的能力弱再好的技能也会被打折扣——它可能读了技能但执行时走样。所以我的建议是技能体系先在能力较强的模型上跑通、验证有效再考虑迁移到其他模型。迁移时重点观察的是流程遵循度——它是否还老老实实按步骤走还是开始跳步。如果跳步严重可能需要把技能里的约束写得更强硬或者接受这个模型只适合做更简单的任务。7. 实测中踩过的坑和排查思路7.1 技能冲突两个技能给出矛盾指令我遇到过一次典型冲突一个技能要求每次修改都先跑全量测试另一个技能要求快速迭代只跑相关测试。结果 agent 在两个指令之间反复横跳行为很不稳定。这类问题的根因是技能之间没有优先级机制。解决办法有两个一是合并冲突的技能把矛盾点在一个文件里说清楚什么情况下用哪种策略二是给技能加优先级标记让 agent 知道谁覆盖谁。我倾向于第一种因为合并的过程本身就是梳理规范的过程。7.2 技能太长导致 agent 读了但没记住前面提过上下文经济这里展开说。我一开始写 TDD 技能时恨不得把所有测试技巧都塞进去结果文件两千多行。实测发现 agent 执行时经常漏掉后面的约束——不是它不想遵守是上下文里信息太多注意力被稀释了。后来我做了拆分主文件只保留核心流程和硬约束控制在 300 行以内详细的测试模式、边界情况清单挪到references/里主文件里用一句话指路需要具体测试写法时参考 references/testing-patterns.md。改完之后流程遵循度明显提升。7.3 技能看起来生效了但实际没约束住这是最隐蔽的坑。表现是agent 确实先写了测试看起来在走 TDD但仔细看它是先在心里想好了实现然后补了一个刚好能通过的测试。测试是有了但失去了 TDD 的意义——测试没有驱动设计只是事后装饰。识别这种情况的方法是看测试的粒度。真正的 TDD测试是一个一个加的每个测试对应一小步实现。如果 agent 一次性写了五个测试然后一次性写完实现那基本可以判定是伪 TDD。对策是在技能里明确要求一次一个测试用例写完一个跑一次。7.4 排查链路的一个真实案例有次我发现 TDD 技能完全没生效agent 直接改实现。排查过程是这样的第一步确认技能文件存在且路径正确——没问题。第二步检查元数据格式发现trigger字段我写成了中文描述而 agent 的匹配逻辑可能对中文支持不好。第三步把trigger改成中英混合、并加上具体的关键词如 new feature、bug fix、implement重新测试。第四步行为验证这次 agent 先去找测试文件了。这个案例的教训是元数据里的触发条件要写得机器友好用具体的动作词而不是抽象的概念词。抽象词人看得懂但匹配算法不一定能对上。8. 关于技能体系长期维护的一些想法技能体系不是一次配好就完事的它需要持续维护。我的做法是建立一个简单的反馈循环每次 agent 犯了重复性的错误就问自己这是不是应该在技能里约束一下如果是就去改技能文件并提交。这个循环跑久了你会发现技能库慢慢变成了团队工程规范的活文档——它不只是给 AI 看的新人读一遍也能快速理解团队怎么做事。这可能是agent-skills这类项目最有价值的副产品为了让 AI 遵守规范你被迫把规范写清楚了而写清楚规范这件事对团队里的人来说同样有价值。另外提醒一点技能不要贪多。我见过有人一口气装了二十个技能结果 agent 每次任务都要在大量技能里做匹配反而变慢、变不准。从三五个核心技能开始用出效果了再加是比较稳的节奏。技能的价值在于被真正用起来而不是躺在目录里。
