1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新同事来培养的技能体系。项目正文和关键词都是空的但热搜词已经把方向交代得很清楚了——agent-skills、AI coding agents、skills CLI、Claude Code、test-driven-development。这几个词串起来讲的其实是一件事怎么给 AI 编程代理装上一套可复用、可版本管理、可组合的技能包让它在真实项目里干活而不是只会聊天。我接触 Claude Code 这类终端里的 AI coding agent 有一段时间了最大的感受是模型能力本身已经不是瓶颈瓶颈在于上下文工程和工作流编排。你让一个 agent 从零开始理解你的代码库、你的测试规范、你的提交习惯每次都要重新解释一遍效率极低。agent-skills这类项目要解决的就是把这个解释成本沉淀成结构化的技能文件让 agent 一进项目就知道该按什么套路干活。这篇文章适合三类人看一是刚开始用 Claude Code、还在纠结怎么让它听话的开发者二是团队里想把 AI 编码流程标准化的技术负责人三是想理解 AI coding agent 底层工作方式的工程师。我会从技能包的本质讲起拆解 skills CLI 的设计逻辑重点讲 test-driven-development 这类技能怎么落地最后分享我在实际项目里踩过的坑。全程不吹概念只讲能复现的东西。需要先说明一点agent-skills的具体实现细节我没有完整源码可查下面涉及目录结构、CLI 命令、技能文件格式的部分是基于 Claude Code 生态和同类 agent 框架的常见实践做的合理推演我会明确标注哪些是通用做法、哪些是推测。你照着思路走具体命令以你本地版本为准。2. AI coding agent 的技能到底是什么东西2.1 技能不是提示词是带触发条件的操作手册很多人第一次听说给 agent 加技能脑子里浮现的是一段写得很长的 system prompt。这是误解。提示词是你是什么角色技能是遇到什么情况该做什么动作。前者是静态的人设后者是动态的行为规则。打个比方提示词像是给新员工发的员工手册告诉他公司是干什么的技能像是贴在工位旁边的操作 SOP写着当客户投诉物流延迟时先查订单号再核对发货记录最后按模板回复。员工手册他可能翻一遍就忘了但 SOP 是遇到具体场景才会被调用的。在 Claude Code 这类 agent 里技能通常表现为一个带元信息的 Markdown 文件头部有name、description、when_to_use之类的字段正文是具体的操作步骤。agent 在规划任务时会先扫描所有可用技能的描述判断当前任务该调用哪个然后把技能正文加载进上下文。这个机制叫渐进式披露——不是一次性把所有技能塞进上下文那样会爆 token而是按需加载。提示技能描述字段写得越具体agent 的匹配准确率越高。写帮助处理测试远不如写当需要为新功能编写单元测试、或修复失败的测试用例时使用来得有效。2.2 为什么要有 skills CLI 而不是手动复制文件手动把技能文件拷到~/.claude/skills/或者项目里的.claude/skills/目录确实能用。但一旦你有十几个项目、几十个技能手动管理就是灾难版本对不上、更新要一个个改、团队协作时每个人的本地状态不一致。skills CLI的价值就在这里。它把技能当成 npm 包一样管理——有仓库、有版本、有依赖、有安装和卸载命令。你可以理解成技能界的包管理器。常见的能力包括skills install name从远程仓库拉取技能到本地skills list列出当前已安装的技能skills update批量更新到最新版本skills remove name卸载这套设计借鉴的是 Homebrew 和 npm 的思路。好处是技能可以独立迭代你不需要为了用一个新技能去升级整个 agent 版本。坏处是引入了额外的依赖管理复杂度后面我会讲怎么规避。2.3 技能和 MCP、子代理的区别Claude Code 生态里有三个容易混淆的概念技能Skills、MCP 服务器、子代理Subagents。我用一张表说清楚。概念本质解决什么问题典型场景技能 Skills结构化的操作指令文件让 agent 按固定套路完成某类任务写测试、做代码审查、生成提交信息MCP 服务器外部工具/数据源的接口让 agent 能访问外部系统查数据库、调 API、读 Figma 设计稿子代理 Subagents独立的 agent 实例把复杂任务拆给专门的 agent一个负责写代码一个负责审查技能是知识MCP 是手脚子代理是分身。agent-skills聚焦的是第一层——把团队的最佳实践固化成 agent 能理解的知识。这三者不冲突实际项目里往往是组合使用主 agent 调用技能知道该怎么做通过 MCP 拿到需要的数据必要时派子代理去执行。3. 一个技能文件长什么样结构拆解3.1 头部元信息决定技能何时被激活技能文件的核心是头部的 YAML frontmatter。以 test-driven-development 技能为例一个合理的结构大概是这样--- name: test-driven-development description: 当需要为新功能编写测试、或修复失败的测试时使用。遵循红-绿-重构循环。 when_to_use: 用户要求添加测试、修复测试失败、或实现新功能需要测试覆盖时 version: 1.2.0 tags: [testing, tdd, quality] ---这里每个字段都有讲究。name是唯一标识不能和别的技能重名。description是给 agent 看的广告词它决定了 agent 在任务规划阶段会不会选中这个技能。when_to_use是更明确的触发条件有些实现会把它和 description 合并。version用于更新管理。tags方便分类检索。我踩过的一个坑description 写得太宽泛比如帮助改进代码质量结果 agent 在任何涉及代码的任务里都想调用它反而干扰了正常流程。后来改成当代码审查发现重复逻辑、或需要提取公共函数时使用匹配就精准多了。3.2 正文把老师傅的经验写成步骤头部之后是正文这才是技能的肉。好的技能正文不是泛泛而谈而是把资深工程师脑子里的隐性知识显性化。以 TDD 技能为例正文应该包含核心原则先写测试再写实现最后重构。测试必须失败过才算有效。具体步骤写一个失败的测试 → 运行确认失败 → 写最小实现让测试通过 → 运行确认通过 → 重构 → 再运行。判断标准什么样的测试算好测试独立、可重复、快速、断言明确。常见错误一次写太多测试、测试依赖外部状态、断言太弱。示例代码给一段真实的红-绿-重构演示。关键在于可执行性。如果技能正文只是说要写好测试agent 读完还是不知道怎么做。但如果写清楚每个测试函数只断言一个行为测试名用should_xxx_when_yyy格式agent 就能直接照做。3.3 技能的组合与依赖单个技能能力有限真正的威力在于组合。比如一个实现新功能的完整流程可能串起多个技能requirement-analysis先把需求拆成可验证的条目test-driven-development为每个条目写测试code-implementation写实现让测试通过code-review自查代码质量commit-message生成规范的提交信息有些 skills CLI 支持在技能头部声明dependencies安装一个技能时自动拉取它依赖的其他技能。这个设计很聪明但也容易出问题——依赖冲突、循环依赖。我的建议是保持技能粒度小、依赖浅宁可手动组合也不要搞出复杂的依赖树。4. test-driven-development 技能为什么值得单独拎出来讲4.1 TDD 是约束 agent 行为最有效的抓手AI coding agent 最大的问题是太能干——它会一次性写一大堆代码看起来都对但你根本不知道哪里有问题。TDD 恰好是治这个毛病的良药因为它强制了一个先证明需求、再实现的顺序。当 agent 遵循 TDD 时它的行为被约束成先写一个会失败的测试证明它理解了需求再写实现证明它能满足需求。这个过程中测试就是验收标准。如果 agent 理解错了需求测试就会写错你能在它写实现之前就发现。我在实际项目里对比过不启用 TDD 技能时agent 经常一口气改五个文件跑起来报错一堆排查要半天启用 TDD 技能后它一次只动一个测试和一个实现每步都能验证出问题定位极快。效率反而更高。4.2 红-绿-重构在 agent 场景下的具体落地传统 TDD 的红-绿-重构在 agent 场景下需要做一些调整。我总结的落地流程是这样的红阶段让 agent 先写测试。关键指令是只写测试不要写实现写完运行确认它失败。这一步必须真的运行测试看到失败输出。有些 agent 会偷懒写完测试不运行就往下走这时候要在技能里明确要求必须展示失败的命令输出。绿阶段让 agent 写最小实现。关键词是最小——只让当前测试通过不要顺手把别的功能也实现了。这一步最容易失控agent 会忍不住顺便优化一下。技能里要写死只修改让测试通过所必需的代码。重构阶段测试通过后再优化结构。这一步 agent 往往做得不错因为它有了测试作为安全网。但要提醒它重构后必须重新运行全部测试。注意agent 执行 TDD 时测试运行命令必须提前配置好。如果项目用 pytest技能里要写明pytest tests/ -v如果用 jest写明npm test。命令不对整个流程就断了。4.3 测试质量怎么保证agent 写的测试有个通病断言太弱。比如测试一个加法函数它可能只断言结果不为 None而不是结果等于 5。这种测试跑起来是绿的但毫无价值。解决办法是在 TDD 技能里加入测试质量检查清单每个测试是否只验证一个行为断言是否精确到具体值而不是非空不报错测试之间是否相互独立不依赖执行顺序是否覆盖了边界条件空输入、极值、异常测试名是否描述了预期行为我还会让 agent 在写完测试后自问一句如果我把实现改错这个测试会失败吗如果答案是不会说明测试太弱要重写。这个自检动作写进技能后测试质量明显提升。5. 把 agent-skills 接进 Claude Code 的实操路径5.1 环境准备先确认 agent 能跑起来在折腾技能之前得先保证 Claude Code 本身能正常工作。这一步看似基础但很多人卡在这里。核心检查项Node.js 版本是否满足要求一般需要 18 以上Claude Code 是否已正确安装并能启动项目目录是否有正确的权限网络环境是否能访问所需的模型服务我见过最常见的失败是 Node 版本太老导致 CLI 启动就报错。建议先用node -v确认版本不满足就升级。另外如果你在受限的网络环境里模型服务的连通性要提前验证否则后面所有步骤都是白搭。5.2 技能目录的两种放置方式技能文件放哪里决定了它的作用范围。常见两种全局技能放在用户主目录下的配置文件夹里比如~/.claude/skills/。所有项目都能用适合通用技能TDD、代码审查、提交信息生成。项目技能放在项目根目录的.claude/skills/里。只对当前项目生效适合项目特有的规范比如本项目的 API 必须走统一网关。我的建议是通用技能装全局项目规范放项目里。这样换项目时通用能力还在项目特有的约束又不会污染其他项目。如果团队协作项目技能应该提交到版本库让每个人拉下来就有一致的 agent 行为。5.3 用 skills CLI 管理技能的完整流程假设你已经装好了 skills CLI一个典型的工作流是这样的# 查看可用技能 skills list --available # 安装 TDD 技能到全局 skills install test-driven-development --global # 安装项目专用技能到当前项目 skills install project-api-conventions --local # 查看已安装 skills list # 更新所有技能 skills update --all # 卸载不再需要的 skills remove some-old-skill这里有个经验安装后一定要验证技能被正确加载。方法是启动 Claude Code问它你现在有哪些可用技能看它列出来的清单里有没有你刚装的。如果没出现多半是目录放错了或者文件格式有问题。5.4 验证技能是否真的生效装完不等于生效。我常用的验证方法是设计一个触发场景看 agent 会不会主动调用技能。比如验证 TDD 技能给 agent 一个明确的任务为这个函数添加测试观察它的行为。如果它先写测试、运行、看到失败、再写实现说明技能生效了。如果它直接写实现说明技能没被加载或者触发条件没匹配上。排查思路先确认文件在正确目录再检查 frontmatter 格式YAML 缩进很容易错最后看 description 是否足够具体。这三步能解决 90% 的技能不生效问题。6. 我在实际使用中踩过的坑6.1 技能太多反而拖慢 agent刚开始我很兴奋装了二十多个技能。结果发现 agent 变迟钝了——每次任务规划阶段它要扫描所有技能的描述判断该用哪个这个过程消耗了大量 token 和时间。更糟的是技能之间描述重叠agent 经常选错。后来我做了减法只保留高频使用的五六个技能其余按需临时安装。效果立竿见影。技能不是越多越好而是越精准越好。每个技能都应该有明确的、不重叠的适用场景。6.2 技能描述里的陷阱词有个技能我写的是当代码有性能问题时使用。结果 agent 在任何涉及循环、数据库查询的地方都想调用它哪怕那些代码根本没有性能问题。问题出在性能问题这个词太主观agent 无法判断。改成当函数的时间复杂度超过 O(n²)、或存在 N1 查询模式时使用就精准多了。技能描述要用可观测、可判断的条件而不是模糊的形容词。6.3 技能和项目实际规范脱节最尴尬的一次我装了一个通用的提交信息规范技能要求用 Conventional Commits 格式。但我们团队实际用的是另一种格式。结果 agent 生成的提交信息全都不符合团队规范还得手动改。教训是通用技能装之前先确认它和你的实际工作流是否兼容。不兼容就 fork 一份改成自己的或者干脆写项目专用技能。盲目用别人的技能不如花十分钟写一个贴合自己团队的。6.4 技能更新带来的惊喜skills CLI 支持一键更新很方便但也危险。有次更新后某个技能的触发条件变了导致 agent 的行为和之前完全不同我排查了半天才发现是技能版本的问题。现在的做法是生产项目里锁定技能版本更新前先在测试项目里验证。技能文件也应该纳入版本控制这样出问题能快速回滚。7. 技能体系的进阶玩法7.1 把团队规范写成技能一个团队里资深工程师的经验是最宝贵的资产但也是最难传承的。技能体系提供了一个绝佳的载体把我们团队怎么做代码审查我们的错误处理约定我们的日志规范写成技能文件新人和 agent 都能受益。我帮一个团队做过这件事把他们散落在 wiki、聊天记录、口口相传里的规范整理成十几个技能文件。结果是新人上手时间缩短了一半agent 生成的代码也更符合团队风格。这件事的投入产出比非常高。7.2 技能的可测试性技能本身也可以测试。方法是设计一组输入-期望行为的用例每次修改技能后跑一遍看 agent 的行为是否符合预期。比如 TDD 技能用例可以是给定一个空函数agent 应该先写测试。这种测试虽然不能完全自动化但可以半自动化——让 agent 自己扮演被测对象人工检查输出。7.3 技能与 CI 的结合进阶玩法是把技能检查接入 CI。比如在 PR 流程里用一个 agent 加载代码审查技能自动检查提交的代码是否符合规范把结果作为评论贴到 PR 上。这样技能就从个人助手升级成了团队守门人。这个玩法我还在摸索目前的难点是 agent 审查的稳定性——同样的代码不同时候可能给出不同结论。解决办法是让审查技能输出结构化的检查项而不是自由文本这样结果更可控。8. 关于技能体系我现在的真实看法用了一段时间 agent-skills 这套东西我的判断是它代表了 AI 辅助开发的一个正确方向但还远没到成熟阶段。方向正确在于它把怎么用 AI这件事从玄学变成了工程。以前大家比的是谁的提示词写得好现在比的是谁的技能体系设计得合理。后者是可积累、可复用、可传承的前者是碰运气。不成熟在于技能的标准还没统一。不同 agent 框架的技能格式不一样skills CLI 也各有各的实现。你今天为 Claude Code 写的技能明天换个 agent 可能就用不了。这种碎片化会持续一段时间。但我觉得这不影响现在就开始用。哪怕标准会变把团队经验结构化的这个过程本身就有价值。而且技能文件本质是 Markdown就算工具换了内容还在迁移成本不高。最后分享一个我自己的习惯每当我发现自己在重复给 agent 解释同一件事我就会停下来把它写成一个技能。这个习惯坚持了几个月我的技能库慢慢变成了一个团队知识库而且是被 agent 真正使用的知识库不是躺在 wiki 里没人看的文档。这可能是 agent-skills 这类项目最被低估的价值——它逼着我们把隐性知识显性化而这件事无论有没有 AI都值得做。