1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新同事来管理的工程化方案。项目正文和关键词都是空的但热搜词已经把方向交代得很清楚了——AI coding agents、skills CLI、Claude Code、test-driven-development。把这几个词串起来它想解决的问题其实很具体当 Claude Code 这类终端里的编码代理成为日常开发的一部分之后怎么让它的行为可复用、可版本化、可测试而不是每次开新会话都靠人肉复述一遍规矩。我用了大半年 Claude Code最深的体会是它强不强七成取决于你喂给它的上下文质量三成才是模型本身。很多人抱怨它老是改坏我的代码它不按我的风格写本质上是没给它一套稳定的技能约束。agent-skills这类项目的价值就在这儿——它把怎么让 agent 干活这件事从口头约定变成了仓库里的文件。这篇文章我会按一个真实使用者的视角来拆先讲清楚 agent skills 到底是个什么东西、为什么值得单独建一个仓库再讲 skills CLI 的安装和目录约定然后是重头戏——怎么用 test-driven-development 的思路去写和验证一个 skill最后聊 Claude Code 的接入配置、模型切换、以及我在实际踩坑中总结的那些文档里不会写的细节。适合已经在用或准备上手 Claude Code 的开发者也适合任何想把 AI 编码代理纳入团队工作流的人。2. agent skills 到底是什么把口头规矩变成可执行文件2.1 一个生活化的类比新同事的入职手册你可以把 Claude Code 想象成一个能力很强、但完全不了解你项目的新同事。他编程功底没问题但他不知道你们的提交信息格式是什么、测试跑在哪个目录、哪些文件是自动生成的不能手改、遇到不确定的需求应该先问还是先猜。如果你每次都用一段长 prompt 把这些讲一遍那就是口头带教——累、容易漏、没法复用。agent-skills的思路是给这位新同事发一本入职手册手册里的每一条都是独立的、可单独翻阅的技能卡。需要写测试时翻到测试那页需要发版时翻到发版那页。这就是 skill 的本质一段结构化的、描述在什么场景下该怎么做的指令集合以文件形式存在仓库里。2.2 skill 和普通 prompt 的三个关键区别很多人会问这不就是 prompt 吗区别在于三点这三点决定了它能不能工程化。第一是触发条件。普通 prompt 是你主动贴进去的skill 是带何时使用描述的。Claude Code 在接到任务时会去匹配当前场景和哪个 skill 相关相关才加载。这就避免了把一堆无关指令塞进上下文、稀释注意力的问题。第二是可版本化。skill 是仓库里的文件能进 git、能 review、能回滚。团队里谁改了 skill 的哪一条diff 里看得清清楚楚。prompt 贴在聊天框里改了什么没人知道。第三是可测试。这是test-driven-development这个关键词最值钱的地方。一个 skill 写得好不好不该靠感觉它变聪明了而应该有一组固定的输入输出用例去验证。你改了 skill 的描述跑一遍测试看 agent 的行为有没有回归。2.3 为什么值得单独建一个仓库把 skills 放在项目仓库里行不行行但有几个现实问题。一是多个项目要共享同一套 skill 时复制粘贴会失控二是 skill 的迭代节奏和业务代码不一样混在一起提交历史很乱三是团队里做 AI 工程化的人可能不直接改业务代码。单独建agent-skills仓库本质上是把AI 协作规范当成一个独立的基础设施来维护。它有自己的 README、自己的测试、自己的发布节奏。这个思路和当年把 lint 规则、CI 配置抽出来单独管理是一脉相承的。提示不要一上来就追求 skill 数量。我见过有人一口气写了三十个 skill结果 agent 每次加载时匹配混乱反而变笨了。从三到五个高频场景开始跑顺了再扩。3. skills CLI 的安装与目录约定先把地基打对3.1 安装前的环境确认skills CLI是管理这些技能文件的命令行工具。在动手之前先确认你的环境。Claude Code 本身对 Node 版本有要求我实测下来 Node 18 以上比较稳20 LTS 是最省心的选择。用node -v看一眼低于 18 就先升级。如果你在 Ubuntu 上系统自带的 Node 往往版本偏旧建议用 nvm 管理。macOS 上用 Homebrew 装也行但要注意 PATH 有没有配对。Windows 用户我建议直接在 WSL 里操作原生环境的路径分隔符和权限问题会平白多出一堆麻烦。node -v npm -v # 确认版本后全局安装 skills CLI npm install -g agent-skills/cli # 验证 skills --version装完之后如果提示command not found九成是 npm 全局 bin 目录没进 PATH。用npm config get prefix看路径把它加到 shell 配置里再source一下。3.2 目录结构约定大于配置skills CLI 初始化之后会生成一套约定目录。我把它简化成一张表方便你对照理解每一层是干嘛的路径作用我的使用习惯skills/存放所有 skill 定义按领域分子目录如testing/、release/skills/*/SKILL.md单个 skill 的主文件一个 skill 一个目录主文件必叫这个名字tests/skill 的行为测试用例每个 skill 配一个同名测试文件skills.config.json全局配置与元信息记录版本、启用状态、依赖关系这里有个容易踩的坑skill 的目录名和SKILL.md里声明的 name 字段最好保持一致。我早期图省事目录叫tdd文件里 name 写test-driven-development结果 CLI 在解析依赖时对不上号排查了半天。约定大于配置别在这种地方耍小聪明。3.3 SKILL.md 的最小结构一个能跑起来的 skill最少要有三段元信息、触发描述、执行指令。元信息用 YAML front matter 写在文件顶部触发描述告诉 agent什么时候用我执行指令是具体的步骤。--- name: test-driven-development description: 当需要为新功能或 bug 修复编写测试时使用遵循红-绿-重构循环 version: 1.0.0 --- ## 何时使用 当用户要求实现新功能、修复 bug或明确提到写测试时。 ## 执行步骤 1. 先写一个会失败的测试确认它确实失败 2. 写最小实现让测试通过 3. 在测试保护下重构 4. 每次只推进一个断言注意description这一栏的写法。它不是给人看的简介而是给 agent 做语义匹配用的。写得越具体、越贴近真实触发场景匹配越准。写用于测试相关任务就太泛了写当需要为新功能或 bug 修复编写测试时使用就精准得多。4. 用 test-driven-development 的思路写 skill这是全篇最值钱的部分4.1 为什么 skill 也需要测试这是agent-skills这个项目最反直觉、也最有价值的一点。大多数人写 prompt 或 skill 是写完就用感觉不对再改这是纯手工调参。但 skill 一旦被团队共享、被多个项目引用它就成了有接口的软件组件——既然是软件组件就该有测试。TDD 的核心思想是先写会失败的测试再写实现。套到 skill 上就是先定义这个 skill 应该让 agent 表现出什么行为写成可验证的用例再去写 skill 内容直到用例通过。这样你改 skill 的时候能立刻知道有没有把原来的行为改坏。4.2 一个 skill 测试用例长什么样skill 的测试和普通单元测试不太一样它测的是给定一个场景agent 是否按预期行动。所以用例通常包含三部分输入场景、期望行为、判定标准。{ skill: test-driven-development, cases: [ { input: 帮我实现一个计算斐波那契数列的函数, expect: [ 先创建测试文件, 测试先运行并失败, 再写实现 ], reject: [ 直接给出完整实现, 跳过测试步骤 ] } ] }expect是必须出现的行为reject是绝对不能出现的行为。判定标准要写得可观察——先创建测试文件是能看出来的写得好是看不出来的。这一点非常关键模糊的判定标准等于没有测试。4.3 红-绿-重构在 skill 开发中的具体落地我把这套流程拆成四步你可以直接照着做。第一步红写一个当前 skill 会失败的用例。比如你发现 agent 老是不写测试就直接实现那就写一个用例期望它先创建测试文件。跑一遍看它失败——这一步确认你的测试真的能捕捉到问题。第二步绿改 skill 内容让它通过。在SKILL.md的执行步骤里把先写测试放到第一条并且明确写在写任何实现代码之前。措辞要强硬agent 对必须在……之前这类词更敏感。第三步重构在不改变行为的前提下精简措辞。第一版 skill 往往写得啰嗦把重复的、agent 已经默认会做的删掉。删完再跑一遍测试确认行为没变。第四步回归每次改 skill 都跑全量测试。这是 TDD 的纪律。我吃过亏——改了一个测试相关的 skill结果把发版 skill 的行为带偏了因为两个 skill 共享了一段描述。全量跑一遍就能立刻发现。4.4 判定标准怎么写才不虚这是实操中最难的部分。我总结了一个原则判定标准要能被一个只看输出、不看过程的旁观者验证。换句话说如果两个人看同一段 agent 输出对是否满足标准会有分歧那这个标准就是废的。反面例子代码质量高。正面例子测试文件在实现文件之前被创建。反面例子遵循最佳实践。正面例子每个函数都有对应的测试用例且测试先于实现运行。再补一个技巧把判定标准写成可 grep 的模式。比如期望 agent 输出里包含describe(和it(那测试脚本就能自动检查。能自动化的判定就别靠人眼。注意不要为了测试通过而把 skill 写得过度死板。skill 是给 agent 的指导不是给机器的硬编码。留出合理的判断空间否则 agent 会变得机械、不会变通。5. Claude Code 接入与配置让 skill 真正跑起来5.1 Claude Code 的安装与首次配置Claude Code 是终端里的编码代理安装方式按平台略有差异。macOS 和 Ubuntu 上都可以通过 npm 全局安装装完在项目目录里启动即可。npm install -g anthropic-ai/claude-code cd your-project claude首次启动会引导你完成账号相关配置。这里有个常见疑问注册账号和不注册有什么区别简单说注册后能用官方提供的模型服务配额和功能更完整不注册的情况下部分能力会受限。如果你所在地区提示服务不可用那是区域支持的问题需要按官方文档确认支持范围这里不展开。VS Code 用户可以直接装 Claude Code 的官方插件在编辑器里就能唤起。配置的核心是让插件能找到你的项目根目录这样它才能读到agent-skills里的技能文件。5.2 让 Claude Code 识别你的 skillsClaude Code 默认会读取项目里的约定目录。如果你把agent-skills作为独立仓库维护有两种接入方式一是作为 git submodule 挂到项目里二是在项目根目录建一个软链接指向 skills 目录。# 方式一submodule git submodule add your-agent-skills-repo .agent-skills # 方式二软链接本地开发常用 ln -s ~/repos/agent-skills/skills ./skills我个人的偏好是 submodule因为版本锁定清晰团队里每个人拉到的 skill 版本一致。软链接适合本地快速试验但别提交到仓库里否则别人 clone 下来会得到一个断链。5.3 模型切换与第三方接入的注意事项热搜词里提到用cc switch之类的工具接入其他模型。这类工具的原理是切换 Claude Code 背后的模型端点。我的建议是先用官方默认配置把流程跑通再考虑切换。因为不同模型对 skill 描述的敏感度不一样你为一套模型调好的 skill换模型后可能需要重新校准。切换模型后务必重跑你的 skill 测试。我实测过同一个 skill 在 A 模型上能稳定触发先写测试换到 B 模型后触发率明显下降因为 B 对指令的遵循方式不同。这时候要么调整 skill 措辞要么在配置里显式声明该 skill 依赖的模型特性。5.4 让 agent 直接执行终端命令的边界Claude Code 能直接跑终端命令这是它比纯聊天工具强的地方但也是风险点。我的做法是在 skill 里明确列出允许执行的命令白名单以及需要人工确认的操作。比如测试 skill 里可以允许npm test、pytest这类只读或可回滚的命令自动执行但涉及rm、git push --force、数据库迁移这类操作必须在 skill 里写明执行前需向用户确认。这不是不信任 agent而是把风险控制在可预期范围内。6. 我在实际使用中踩过的坑与总结的技巧6.1 skill 描述写太长的反效果刚开始我恨不得把一个 skill 写成一篇论文把所有边界情况都列进去。结果发现 agent 反而抓不住重点因为上下文里塞了太多信息关键指令被淹没了。后来我把每个 skill 控制在一屏以内核心步骤不超过五条细节放到单独的参考文件里需要时再让 agent 去读。这个主文件精简、细节外置的模式实测下来触发准确率高很多。6.2 触发词和实际场景对不上的问题有个测试 skill 我写的触发描述是当用户要求写测试时使用。但实际中用户很少直接说写测试更多是说帮我实现这个功能记得覆盖边界情况。触发词和真实表达对不上skill 就永远不被加载。解决办法是收集真实的用户表达把常见的同义说法都写进 description 里。我现在的习惯是每周回顾一次对话记录把新的表达方式补进去。6.3 多 skill 冲突时的优先级处理当两个 skill 的触发条件重叠时agent 可能同时加载两个指令打架。比如快速原型skill 说先跑通再说TDDskill 说必须先写测试这俩放一起 agent 就懵了。我的处理方式是在skills.config.json里显式声明优先级或者干脆把互斥的 skill 做成二选一的开关同一时间只启用一个。6.4 版本升级后 skill 失效的排查Claude Code 在线升级到新版本后偶尔会出现 skill 行为变化。我的排查顺序是先跑 skill 测试确认是不是真的回归了再看官方更新日志有没有提到上下文加载逻辑的变化最后才是改 skill。先定位再动手别一上来就改 skill很多时候是工具侧的变化改 skill 反而把好的部分改坏了。6.5 团队协作中的 skill review 习惯最后分享一个团队层面的经验。我们把 skill 的改动纳入 code review但 review 的重点不是措辞好不好而是测试用例覆盖了没有判定标准是否可观察。一个新 skill 合入前必须带上至少三个测试用例。这个纪律执行下来团队里 skill 的质量稳定了很多也不会出现某个人改了一句话所有人的 agent 行为都变了却没人知道的情况。这套东西说到底是把怎么和 AI 协作从个人经验变成团队资产。agent-skills这个仓库名起得很准——它管的不是模型是技能不是一次性的 prompt是能沉淀、能测试、能传承的工程实践。你要是刚开始上手别贪多挑一个你最痛的场景写一个 skill配一个测试跑通它。这一个跑通了剩下的都是复制。