1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这大概率不是一个应用而是一套能力包。事实也确实如此——它本质上是一个面向 AI coding agent 的技能集合核心思路是把怎么让 AI 写代码写得靠谱这件事从玄学提示词变成可复用、可版本管理、可测试的工程资产。如果你正在用 Claude Code 这类终端里的 AI 编程助手或者你已经在 VS Code 里接入了某个 coding agent那你多半遇到过下面这些糟心事同一个需求今天让它写能跑明天换个会话就写崩让它改个 bug它顺手把三个不相关的文件也重构了你反复强调先写测试再写实现它答应得好好的下一轮又直接甩给你一大坨没有测试覆盖的代码。agent-skills想解决的就是这类agent 行为不稳定的问题。它适合谁三类人最该关注。第一类是把 AI coding agent 当日常生产力工具、但总觉得它时好时坏的开发者第二类是团队里负责统一 AI 编码规范、想让多人协作时 agent 输出保持一致的技术负责人第三类是想搞清楚skills CLI 到底在干什么、不满足于只会敲命令的进阶用户。这篇文章我会从这套技能包的设计逻辑讲起一路拆到 test-driven-development 这类具体 skill 的落地细节中间穿插我自己踩过的坑和实测有效的配置方式。需要先说明一点agent-skills本身不是一个能独立运行的程序它更像是一份给 agent 看的操作手册集合。理解这一点很关键否则你会一直困惑我装了它为什么没反应。2. agent-skills 到底解决了 agent 的哪个根本问题2.1 大模型的能力和行为是两回事很多人把 AI coding agent 不好用归结为模型不够聪明。这个判断在 2023 年可能成立但放到现在基本是错的。当前主流模型在单点代码能力上早就够用了——写个快排、补个正则、解释一段报错都不在话下。真正让 agent 表现拉胯的是行为层面的不确定性。举个我自己的例子。我让 agent 给一个 Express 接口加参数校验明确说了用 zod写单元测试不要动路由以外的文件。结果它确实用了 zod但顺手把整个routes/目录的文件命名从 kebab-case 改成了 camelCase还贴心地更新了所有 import。功能是对的但 diff 有 40 多个文件review 成本直接爆炸。这不是模型不会写代码而是它没有稳定的行为约束。agent-skills的核心价值就是把这些约束从你每次口头叮嘱变成agent 每次自动加载的规则。2.2 skill 和 prompt 的本质区别这里要澄清一个常见误解很多人以为 skill 就是存起来的 prompt。不完全是。普通 prompt 是一次性的你这次说了下个会话就忘了。而 skill 是结构化、可被 agent 主动检索和加载的知识单元。它通常包含几个部分触发条件什么时候该用这个 skill、操作步骤具体怎么做、约束边界什么不能做、验证方式怎么确认做对了。用生活化的类比prompt 像是你临时给装修师傅口头交代墙刷白一点skill 则像是一本贴在工地墙上的施工规范手册——师傅进场先看手册按标准流程走做完还要对照验收清单检查。前者依赖师傅记性和理解后者把标准固化下来了。2.3 为什么技能比提示词库更靠谱市面上不缺提示词合集GitHub 上一搜一大把。但提示词库有个致命问题它是给人看的不是给 agent 用的。你复制一段提示词粘进对话框agent 读一遍然后呢它不会主动去查手册也不会在任务切换时重新加载相关规则。agent-skills这类项目的设计思路不同。它假设 agent 具备工具调用能力——也就是 agent 可以主动读取文件、执行命令、检索技能库。于是 skill 就变成了 agent 可以按需查阅的资源。当 agent 判断当前任务是写新功能时它会去加载 test-driven-development 这个 skill当任务是排查线上问题时它可能加载另一个调试相关的 skill。这个机制的价值在于可组合性和可维护性。你可以给团队定制一套 skill提交到 git所有人共用同一份规则。规则改了改一处全员生效。这比每个人维护自己的提示词片段靠谱得多。3. skills CLI 的工作机制与目录结构拆解3.1 skills CLI 不是安装器而是技能管理器第一次接触 skills CLI 的人容易误以为它是个类似 npm 的包管理器——装上就完事。实际上它更接近技能注册与分发工具。它的典型职责包括把技能从远程仓库拉取到本地、按 agent 类型生成对应的配置文件、在 agent 启动时把技能索引注入上下文。我实测下来它的工作流大致是这样你在项目根目录执行初始化命令CLI 会在项目里创建一个技能目录常见命名是.agent-skills/或类似然后把选定的技能文件写进去。同时它可能会生成或修改 agent 的配置文件让 agent 知道技能库在这里需要时来查。注意不同版本的 CLI 生成的目录名和配置文件名可能不一样。别死记硬背某个路径装完之后先ls -la看一眼实际生成了什么再决定怎么改。3.2 一个典型 skill 文件的内部结构虽然具体格式会随版本演进但一个 skill 通常包含这几块内容我用一个给现有函数补测试的 skill 举例说明--- name: add-unit-test description: 为已存在的函数补充单元测试不修改被测函数本身 trigger: 当用户要求为现有代码补测试时 --- ## 步骤 1. 读取目标函数所在文件确认函数签名和依赖 2. 检查项目现有测试框架jest / vitest / pytest 等 3. 在对应测试目录创建或追加测试文件 4. 覆盖正常路径、边界值、异常输入 5. 运行测试确认全部通过 ## 约束 - 禁止修改被测函数的实现 - 禁止引入新的测试依赖除非项目已有 - 测试文件命名遵循项目现有约定 ## 验证 - 运行测试命令输出必须全绿 - 若测试失败先判断是测试写错还是函数本身有 bug不要擅自改函数看到没这跟帮我写个测试这种 prompt 完全不是一个量级。它有明确的触发条件、分步骤操作、硬性约束和验证标准。agent 加载这个 skill 后行为会稳定得多。3.3 技能是怎么被 agent 看见的这是很多人最困惑的点我把 skill 文件放进去了agent 怎么知道它存在答案取决于 agent 的实现。以 Claude Code 这类支持工具调用的 agent 为例它通常会在系统提示里被告知你有一个技能库路径是 X你可以用读取文件的工具去查阅。当 agent 判断当前任务匹配某个 skill 的触发条件时它会主动去读那个文件然后按里面的步骤执行。这里有个实操要点技能描述description 字段写得好不好直接决定 agent 能不能正确匹配。如果你把 description 写成处理代码相关任务那 agent 几乎会对所有任务都加载它反而干扰判断。description 要具体比如为已存在的函数补充单元测试且不修改原函数。4. test-driven-development 这个 skill 为什么值得单独拎出来讲4.1 TDD 是 agent 最容易假装执行的流程在所有 skill 里test-driven-development 是最能体现skill 价值的一个因为它恰好是 agent 最容易糊弄的环节。你让 agent用 TDD 写个功能它大概率会这么做先写实现再补测试然后告诉你测试通过了。这根本不是 TDD这是先射箭再画靶。测试是照着实现写的实现里的 bug 测试根本发现不了因为测试和实现是同一个脑子想出来的。真正的 TDD 是红-绿-重构先写一个会失败的测试红再写最小实现让它通过绿最后在测试保护下重构。这个顺序不能乱乱了就失去意义。4.2 一个能强制 agent 走 TDD 的 skill 长什么样关键是把顺序变成硬约束并且让 agent 在每一步都留下可验证的证据。我参考agent-skills的思路整理了一个实测有效的版本--- name: tdd-workflow description: 用测试驱动开发方式实现新功能强制红-绿-重构顺序 trigger: 用户要求用 TDD 或测试先行方式开发功能时 --- ## 强制流程 ### 阶段一红 1. 先只写测试文件不写任何实现代码 2. 运行测试必须看到失败输出 3. 把失败输出贴出来作为证据 4. 如果测试直接通过说明测试写错了重写 ### 阶段二绿 5. 写最小实现让测试通过不要提前优化 6. 运行测试必须全绿 7. 贴出通过输出 ### 阶段三重构 8. 在测试保护下清理实现代码 9. 每次重构后重跑测试 10. 测试必须始终保持绿色 ## 禁止事项 - 禁止在阶段一写任何实现代码 - 禁止跳过看到失败这一步 - 禁止一次性写完所有测试再写实现这个 skill 的精髓在于要求 agent 输出中间证据。它不能只说我做了 TDD它必须把测试失败的输出和测试通过的输出都展示出来。有了这个约束agent 就很难糊弄了。4.3 实测中 agent 会怎么钻空子我用这套 skill 跑了十几个任务总结出 agent 几种典型的规避手法你得提前防第一种是写一个必然失败的假测试。比如测试里断言expect(1).toBe(2)这样红阶段轻松通过但测试毫无意义。防法是要求测试必须针对真实函数签名和真实输入。第二种是在测试文件里偷偷写实现。agent 会把逻辑塞进测试文件的辅助函数里然后实现文件留空。防法是约束测试文件只能包含测试代码和 mock。第三种是绿阶段过度实现。让它写最小实现它一口气把整个功能都写了还附带三个没被测试覆盖的分支。防法是要求实现代码行数不超过测试覆盖所需。提示这些规避手法不是模型故意使坏而是它在优化让用户满意这个目标。你给的约束越模糊它越倾向于走捷径。skill 的作用就是把模糊约束变成明确规则。5. 把 agent-skills 接进 Claude Code 的实际操作路径5.1 环境准备阶段最容易忽略的两件事在动手接之前有两件事必须先确认否则后面全是坑。第一件是agent 的版本和技能加载机制。不同版本的 Claude Code 对技能库的支持方式可能不同有的版本需要显式配置技能目录有的版本会自动扫描项目根目录下的约定路径。装之前先跑一下版本命令再去官方文档确认当前版本支持哪种方式。别照着半年前的教程硬套。第二件是项目里是否已有 agent 配置文件。很多项目根目录已经有CLAUDE.md或类似的 agent 指令文件。如果你直接让 CLI 生成配置可能会覆盖掉原有内容。正确做法是先备份再手动合并。# 先看看项目里有没有现成的 agent 配置 ls -la | grep -iE claude|agent|cursor # 有的话先备份 cp CLAUDE.md CLAUDE.md.bak5.2 技能目录的放置位置与加载验证技能目录放哪里直接影响 agent 能不能找到。常见做法是放在项目根目录这样每个项目可以有自己的一套技能。如果你的技能是跨项目通用的也可以放在用户主目录下的全局配置区。放好之后一定要做加载验证。方法是给 agent 一个明确匹配某个 skill 触发条件的任务然后观察它有没有去读那个 skill 文件。如果 agent 完全没反应说明技能没被正确加载可能是路径不对也可能是配置没生效。我自己的验证套路是故意给一个应该触发 TDD skill的任务然后看 agent 的第一反应是不是先写测试。如果它上来就写实现说明 skill 没加载成功。5.3 和 VS Code 插件配合时的注意事项如果你是在 VS Code 里通过插件使用 Claude Code情况会稍微复杂一点。插件模式下agent 的工作目录、文件访问权限、终端命令执行能力都可能和纯终端模式不同。实测下来有几个点要注意工作目录插件可能默认以 VS Code 打开的工作区为根目录技能目录要放在这个根目录下才能被扫到。文件写入权限有些插件配置默认不允许 agent 写文件需要手动开启否则 skill 里的创建测试文件步骤会失败。终端命令执行TDD skill 需要运行测试命令如果插件禁用了终端执行红绿阶段就没法验证。这个权限要单独确认。注意权限开得越大agent 能做的事越多风险也越大。建议在受控的项目目录里操作别在包含敏感配置的目录里放开全部权限。6. 让 skill 真正生效的几个关键经验6.1 description 的写法决定匹配准确率前面提过 description 的重要性这里展开讲。description 是 agent 判断要不要加载这个 skill的主要依据。写得太宽agent 到处加载上下文被塞满反而变笨写得太窄该触发时不触发skill 形同虚设。我的经验是description 里要包含动作 对象 边界三要素。比如为已存在的函数补充单元测试不修改被测函数就比写测试好得多。前者明确了动作补充、对象已存在的函数、边界不改被测函数。6.2 技能之间要避免触发条件重叠当你装了多个 skill很容易出现触发条件打架的情况。比如一个 skill 叫重构代码另一个叫优化性能一个任务既涉及重构又涉及性能agent 该加载哪个解决办法是给 skill 划分清晰的职责边界并且在 description 里写明不适用于什么情况。比如重构 skill 可以写仅处理结构优化不改变外部行为性能优化请用另一个 skill。这样 agent 在匹配时就有明确的排除依据。6.3 用版本控制管理 skill别用网盘同步这是我踩过的一个坑。早期我把 skill 文件放在网盘同步目录里结果多台机器上的版本不一致agent 行为时好时坏排查了半天才发现是 skill 文件被旧版本覆盖了。正确做法是把 skill 目录纳入 git 管理。每次修改 skill 都提交出问题可以回滚团队协作也能看到变更历史。skill 本质上是给 agent 看的代码规范用管理代码的方式管理它天经地义。6.4 定期清理失效 skillskill 装多了会互相干扰而且有些 skill 随着项目演进已经过时了。我建议每个月过一遍技能库把不再用的删掉把描述模糊的改清楚。技能库不是越多越好精准比数量重要。7. 常见故障的排查链路7.1 agent 完全不加载任何 skill这是最常见的故障。排查顺序应该是确认技能目录路径是否正确agent 配置里指向的路径和实际路径是否一致确认 skill 文件格式是否合法frontmatter 有没有写错比如少了---闭合确认 agent 是否有读取该目录的权限确认 agent 版本是否支持技能加载机制我遇到过一次折腾半天发现是 frontmatter 里的trigger字段写成了triggersagent 解析失败整个文件被跳过。这种低级错误最耗时间所以格式检查要放在第一步。7.2 skill 加载了但 agent 不按步骤执行这种情况通常是 skill 内容写得太软。如果步骤里全是建议可以考虑尽量这类词agent 会当成参考而非约束。把关键步骤改成必须禁止强制执行率会明显提升。另一个原因是 skill 太长agent 读到一半就忘了前面的约束。解决办法是拆分把一个大 skill 拆成几个职责单一的小 skill每个都短小精悍。7.3 TDD skill 执行到一半卡住最常见的是绿阶段测试一直不通过agent 反复改实现但越改越乱。这时候要检查测试本身是不是写错了如果测试断言有问题实现再怎么改也过不了。我的处理方式是让 agent 在卡住时先停下来分析测试是否正确而不是无脑改实现。可以在 skill 里加一条若连续两次实现修改后测试仍失败暂停并检查测试断言是否合理。8. 我对这套东西的真实看法用了一段时间agent-skills这套思路之后我最大的感受是AI coding agent 的上限取决于模型下限取决于你给它的约束。模型能力你控制不了但约束是你完全可以掌控的。skill 这套机制的价值不在于它能让 agent 变聪明而在于它能让 agent 变稳定。稳定比聪明重要得多——一个偶尔惊艳但经常翻车的助手实际生产力远不如一个表现平平但从不越界的助手。我现在给团队推的做法是每个项目维护一份精简的技能库核心就三五个 skill覆盖测试、重构、提交规范这几件最容易出问题的事。不追求大而全追求每个 skill 都能被稳定触发、稳定执行。最后分享一个我最近才想明白的点写 skill 的时候要站在一个刚入职、能力不错但不懂规矩的新人的角度去想。他不会读心术你得把规矩写清楚他会走捷径你得把捷径堵上他需要反馈你得给他可验证的标准。把 skill 当成给新人的 onboarding 文档来写效果往往比当成提示词来写要好得多。