1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个项目名我的直觉是这不是一个普通工具库而是一套给 AI coding agent 用的技能包。关键词里同时出现了skills CLI、Claude Code、test-driven-development基本可以确定它的定位——把可复用的工程能力封装成 agent 能直接调用的技能单元让 AI 在写代码时不只是会补全而是会按流程干活。过去一年我一直在折腾各类 AI coding agent 的落地从最早的代码补全插件到后来能直接读写文件、跑终端命令的 agent 形态。最大的感受是模型能力再强如果没有一套结构化的技能约束它在真实项目里依然会乱来——该写测试的时候直接改业务代码该先读文档的时候凭记忆瞎编 API。agent-skills这类项目要解决的就是这个问题把资深工程师的工作习惯沉淀成 agent 可加载的技能让 AI 的行为可预测、可复现、可审查。这篇文章适合三类人看一是已经在用 Claude Code 或类似 agent 工具、但觉得输出质量不稳定的开发者二是想给自己团队搭一套 AI 辅助开发规范的技术负责人三是单纯好奇skills CLI 到底怎么玩的动手派。我会从技能包的设计逻辑讲起一路讲到怎么在本地跑通、怎么和 test-driven-development 这类工作流结合以及我在实测中踩过的那些坑。需要先说明一点下面涉及的具体命令和配置一部分来自我对这类工具常见设计的推断一部分来自实际折腾同类 agent 工具的经验。如果你手上的版本和我描述的有出入以官方文档为准但思路是通用的。2. agent-skills 到底解决了什么问题2.1 裸模型和有技能的 agent差在哪先做个类比。你招了一个刚毕业的应届生他算法题刷得很溜但你让他独立做一个模块他会怎么写大概率是打开编辑器凭感觉把功能堆出来跑一下能跑通就提交。他不会主动写单元测试不会先看项目里的代码规范不会考虑边界条件。这不是他笨是他没有工程习惯。裸的 AI coding agent 就是这个应届生。它的知识量可能比任何资深工程师都大但它不知道你这个项目的规矩。你让它加一个函数它可能直接改了三四个文件顺手把别人的代码格式也动了还自信满满地告诉你已完成。agent-skills的思路是给这个应届生配一本《员工手册》而且这本手册是可以按需加载的。手册里写的不是你要努力而是具体的操作流程接到实现某功能的任务时第一步先写失败的测试第二步写最小实现让测试通过第三步重构。这就是 test-driven-development 技能的内核。2.2 技能skill和提示词prompt的本质区别很多人会问这不就是写一段 system prompt 吗我直接塞进对话里不就行了区别在于三个字可组合。一段长 prompt 是扁平的所有规则堆在一起模型注意力会被稀释。而 skill 是模块化的每个 skill 有明确的触发条件、输入输出、依赖关系。当任务涉及写测试时agent 加载 TDD skill涉及改数据库时加载 migration skill。它们互不干扰可以叠加。第二个区别是可版本化。prompt 写在代码里改一次要重新部署。skill 是独立文件可以像代码一样做 code review、打 tag、回滚。团队里谁改了哪个 skillgit log 一清二楚。第三个区别是可测试。这是我觉得最关键的。一个 skill 定义好了之后你可以拿一批标准任务去跑看 agent 加载这个 skill 前后的输出差异。prompt 很难这么测因为它和上下文耦合太深。2.3 skills CLI 在整条链路里的位置skills CLI是这套体系的入口工具。它的职责大概包括初始化技能目录结构、从远程仓库拉取技能包、本地校验技能定义是否合法、把技能注册到 agent 的加载路径里。我把它理解成npm之于 Node 项目的关系。你不会手动去管理每个依赖的文件而是通过 CLI 声明我要哪些技能剩下的交给工具。这样做的好处是技能可以共享——社区里有人写好了一个React 组件测试技能你一条命令就能装进来用。提示技能包的来源一定要可控。从不可信来源拉取的 skill 本质上是一段会被 agent 执行的指令风险等同于装了一个来路不明的脚本。生产环境建议只从内部仓库或经过审计的源加载。3. 技能包的文件结构与加载机制3.1 一个 skill 通常长什么样虽然agent-skills的具体格式我没有完整的一手资料但这类工具的设计高度趋同。一个 skill 一般是一个目录里面至少包含一个描述文件常见的是 markdown 或 yaml声明这个技能的元信息name技能标识比如tdd-workflowdescription一句话说明它干什么agent 靠这个判断要不要加载trigger触发条件可以是关键词、任务类型或者显式调用body技能正文也就是真正注入给模型的指令内容resources附带的模板、脚本、示例文件我实测下来description和trigger这两个字段的写法直接决定技能好不好用。写得太宽泛agent 会在不该用的时候乱加载写得太窄该用的时候又匹配不上。这跟写正则是一个道理边界要卡准。3.2 技能是怎么被加载进上下文的这里有个很多人忽略的细节技能不是一次性全部塞进上下文的。那样做的话装十个技能就把窗口占满了模型反而变笨。合理的机制是按需检索。agent 拿到用户任务后先用一个轻量的匹配步骤可能是关键词匹配也可能是让模型自己判断从技能库里挑出相关的几个再把它们的正文注入上下文。这个过程有点像 RAG只不过检索的对象不是文档而是操作指令。理解这一点很重要因为它解释了为什么技能要写得自包含。你不能假设 agent 加载了 A 技能就一定也加载了 B 技能每个技能都得把自己需要的前置条件说清楚。3.3 目录组织与命名约定我在自己的项目里是这么组织的供参考.agent-skills/ tdd-workflow/ SKILL.md templates/ test-template.js code-review/ SKILL.md checklist.md db-migration/ SKILL.md顶层目录用.agent-skills这种点开头的命名避免和业务代码混在一起。每个技能一个子目录目录名就是技能名用连字符分隔单词。技能正文统一叫SKILL.md这样工具扫描的时候规则简单不容易出错。注意技能名不要用中文或空格。虽然有些工具支持但一旦涉及跨平台或者命令行调用编码问题会让你怀疑人生。老老实实用小写英文加连字符。4. 把 test-driven-development 做成一个技能4.1 为什么 TDD 特别适合做成技能在所有工程实践里TDD 是最适合被技能化的之一。原因很简单它的流程是固定的、可判定的、有明确成功标准的。红-绿-重构三步走。每一步的产出物都能被验证测试先失败红然后通过绿然后在不破坏测试的前提下改结构重构。这种确定性让 agent 有章可循也让你能客观评估它有没有真的执行。相比之下写出高质量代码这种要求就没法技能化因为标准太模糊。所以选技能的时候优先选那些流程明确、结果可验证的实践。4.2 技能正文该怎么写我写 TDD 技能正文时核心是给 agent 立规矩而不是给它讲道理。模型不需要你解释为什么 TDD 好它需要的是明确的动作序列。大致结构是这样## 执行流程 1. 阅读任务描述识别出需要实现的函数或模块的公开接口 2. 在测试文件中编写一个会失败的测试用例覆盖最核心的正常路径 3. 运行测试确认它失败且失败原因是功能未实现而非语法错误 4. 编写最小实现让测试通过不要提前优化 5. 再次运行测试确认通过 6. 补充边界条件测试重复 2-5 7. 所有测试通过后检查实现是否有重复代码进行重构 8. 重构后必须重新运行全部测试 ## 禁止事项 - 禁止在测试未通过前编写额外功能 - 禁止修改已有测试来让实现通过 - 禁止跳过确认测试失败这一步注意第 3 步和第 8 步。这两步是很多人包括 AI最容易偷懒的地方。不确认测试真的失败过你根本不知道这个测试有没有在测东西重构后不重跑你不知道重构有没有破坏行为。把这两条写进技能agent 的执行质量会明显不一样。4.3 让技能可验证加一个自检清单光有流程还不够我在技能末尾加了一段自检清单要求 agent 在结束前逐条确认检查项通过标准测试是否先失败过有失败运行的记录或输出实现是否最小没有测试未覆盖的额外功能边界条件是否覆盖至少包含空值、极值、异常输入重构后测试是否全绿完整测试套件运行通过是否修改过测试测试文件的改动仅限新增这张表的价值在于它把做得好不好变成了能不能勾选。agent 在生成最终回复前会对照它你 review 的时候也可以对照它。双方有了共同的验收标准扯皮就少了。5. 在本地跑通 skills CLI 的完整过程5.1 环境准备里最容易翻车的两件事第一件是运行时版本。这类 CLI 工具通常依赖 Node.js 或 Python而且对版本有要求。我遇到过装完跑不起来排查半天发现是 Node 版本低了两个大版本。建议先确认版本再动手。第二件是权限。skills CLI 要往项目目录写文件、要读取 agent 的配置路径如果权限不对它会静默失败或者报一个和真实原因八竿子打不着的错。在 Linux 和 macOS 上注意别用 root 跑也别在系统目录里初始化。# 确认运行时版本 node --version # 建议 18 以上 # 在项目根目录初始化技能目录 npx skills init # 查看当前已注册的技能 npx skills list # 从源安装一个技能 npx skills add tdd-workflow上面这些命令是我按常见 CLI 设计推断的写法实际命令名可能不同但操作逻辑一致初始化、查看、安装。5.2 初始化之后目录里多了什么跑完 init一般会生成一个配置文件和技能目录。配置文件里记录了技能库的路径、远程源地址、加载策略等。技能目录默认是空的等你 add 之后才会有内容。我建议初始化完先别急着装技能先手动建一个最简单的技能跑一遍加载流程确认整条链路是通的。这就像搭新环境先跑个 hello world能省掉后面很多到底是技能写错了还是环境没配好的纠结。5.3 验证技能真的被加载了怎么确认 agent 用上了你的技能我的办法是故意在技能里加一条奇怪的规则比如所有函数名必须以do开头然后给 agent 一个简单任务看它有没有遵守。如果遵守了说明技能加载成功如果没遵守问题就出在加载环节而不是技能内容本身。这个技巧我用了很多次比看日志快得多。日志可能告诉你加载了 3 个技能但不告诉你模型有没有真的读进去。6. 和 Claude Code 这类 agent 配合时的实操细节6.1 技能注入的时机很关键Claude Code 这类工具的工作模式是对话 工具调用。技能注入的时机有两种一种是在会话开始时全部注入一种是每轮根据任务动态注入。我实测下来动态注入效果更好但前提是你的技能描述写得够准。如果技能描述模糊动态匹配会漏掉该用的技能反而不如全量注入稳。所以这里有个权衡技能少的时候全量注入省事技能多了必须做动态匹配。6.2 终端命令执行和技能的关系Claude Code 能直接执行终端命令这是它比纯补全工具强的地方。但这也意味着技能里可以写运行测试命令这种动作。我在 TDD 技能里就明确要求 agent 执行测试命令并读取输出而不是假设测试通过了。这里有个坑agent 执行命令的输出可能很长如果全塞进上下文会爆窗口。好的做法是在技能里指定只读取输出的最后 N 行或者只关注退出码和失败信息。这个细节不写清楚agent 要么被长输出淹没要么干脆不读输出直接编。6.3 模型选择对技能效果的影响同一个技能换不同模型跑效果差异可能很大。我的观察是流程类技能比如 TDD对模型能力要求相对低因为步骤明确而判断类技能比如 code review对模型要求高因为它需要理解上下文。所以如果你用的是能力稍弱的模型建议先从流程类技能入手把确定性高的部分交给 agent判断类的活还是自己来。等模型能力上来了再逐步放开。7. 我踩过的坑和对应的解法7.1 技能写太细agent 反而不会变通刚开始我恨不得把每个细节都写进技能结果 agent 变得极其死板。遇到技能没覆盖的情况它不会自己想办法而是硬套技能里的流程产出很别扭。后来我调整了思路技能只规定不可妥协的约束和关键节点中间的具体做法留给模型发挥。比如 TDD 技能里我坚持必须先写失败测试但测试怎么写、用什么断言库我不限制。这样既保证了流程正确又保留了灵活性。7.2 技能之间打架装了两个技能一个说提交前必须跑全量测试另一个说小改动只跑相关测试。agent 遇到冲突时行为不可预测有时选 A 有时选 B。解法是给技能加优先级或者在技能里写明适用边界。我现在会在技能描述里加一句当与其他技能冲突时以本技能为准或者本技能仅适用于 X 场景。明确边界比事后调试便宜得多。7.3 技能更新后旧会话不生效技能文件改了但正在进行的会话还是用旧版本。这是因为技能在会话开始时就被加载进上下文了中途改文件不会自动重载。我的做法是改完技能后新开一个会话验证。如果非要中途生效得手动触发重新加载如果工具支持的话。这个坑不致命但会让你误以为技能没写对白白排查半天。7.4 把技能当成了万能药有段时间我什么流程都想做成技能结果技能库膨胀到几十个加载变慢匹配也变乱。后来我定了个规矩只有重复出现三次以上的流程才值得做成技能。一次性的任务直接对话解决就行。技能库和代码库一样需要克制。加技能容易维护技能难。8. 关于技能复用和团队协作的几点体会技能真正的价值在团队场景里才体现得出来。一个人用省的是自己的时间一个团队用统一的是所有人的产出标准。我的做法是把技能库当成代码库来管走 PR 流程每个技能要有作者、有变更记录、有适用场景说明。新人入职先读技能库比读一堆文档快得多因为技能是可执行的知识。另外技能库要定期清理。过时的技能比没有技能更糟因为它会误导 agent。我一般每个季度过一遍把半年没被加载过的技能归档掉。最后分享一个我最近在试的思路把项目里反复出现的 code review 意见沉淀成技能。比如这个项目禁止在循环里做数据库查询写成一条 review 技能agent 在生成代码时就会主动避开。这比事后 review 抓出来再改效率高太多了。技能库慢慢就变成了团队工程规范的活文档而且是能被机器执行的那种。