1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套给 AI coding agent 用的能力包。事实也确实如此——它把一批可复用的技能skills组织成标准目录让 Claude Code 这类命令行 AI 编程代理能够按需加载、按需执行。关键词里出现的skills CLI、test-driven-development、AI coding agents基本勾勒出了它的定位用命令行管理技能用技能驱动代理用测试驱动开发约束代理的行为。如果你正在用 Claude Code或者刚在 VS Code、Ubuntu、Mac 上把它装好却发现自己只会让它帮我写个函数那这个仓库值得花一个下午研究。它解决的核心痛点是代理的通用能力很强但缺少领域化的、可版本管理的、可组合的操作手册。你每次都要重复交代先写测试、再写实现、最后跑一遍而 skills 把这些约定固化成了文件。这篇文章我会按它是什么 → 目录怎么组织 → CLI 怎么用 → 怎么和 TDD 结合 → 怎么在真实项目里落地 → 常见坑的顺序拆开讲。适合两类人一是已经把 Claude Code 跑起来、想进阶的开发者二是团队里想统一 AI 编码规范、但不知道怎么落地的技术负责人。全文基于我对这类工具链的常见实践理解来补全细节具体命令以你本地实际版本为准。2. agent-skills 到底解决了什么问题2.1 通用代理的失忆症与漂移用过 Claude Code 的人都有体会单轮对话里它很聪明但一旦任务跨多个文件、跨多个步骤它就开始漂移。你让它重构一个模块它可能先改了测试、再改实现、最后忘了跑 lint。这不是模型不行而是缺少一个稳定的行为锚点。传统的做法是把这些约定写进CLAUDE.md或者系统提示词里。问题是提示词越写越长模型对长上下文的注意力会稀释而且所有项目共用一份没法按任务类型切换。agent-skills 的思路是把这些约定拆成独立的技能单元每个技能是一个目录里面有说明、有脚本、有模板。代理在执行任务时只加载当前需要的那几个技能上下文干净行为聚焦。打个比方CLAUDE.md像是贴在工位上的员工守则而 skills 像是工具箱里的一把把专用工具——拧螺丝就拿螺丝刀别把整套工具箱都倒桌上。2.2 技能skill和提示词prompt的本质区别很多人把 skill 当成高级提示词这是误解。两者的差别在于可执行性和可验证性维度普通提示词agent-skills 中的技能载体一段文本一个目录含说明、脚本、模板触发方式手动粘贴CLI 安装/加载代理按需调用可验证靠人看输出可挂测试、可跑脚本、可断言版本管理散落在聊天记录Git 仓库可 diff、可回滚组合性复制粘贴拼接技能之间可依赖、可编排关键在最后两行。技能是代码资产能进 Git、能 review、能 CI。这意味着团队可以把我们怎么写测试我们怎么处理数据库迁移这类隐性知识变成显性的、可执行的规范。2.3 为什么是 CLI 而不是插件市场关键词里有skills CLI这很关键。为什么不做成图形化的插件市场我的理解是AI coding agent 的主战场在终端。Claude Code 本身就是终端工具开发者的工作流也在终端。CLI 的好处是可脚本化skills install xxx能写进 CI、写进 dotfiles可组合管道、环境变量、退出码都是 Unix 原语无状态不依赖某个 IDE 的插件体系VS Code、终端、远程服务器通用你在 Ubuntu 服务器上跑 Claude Code和在本机 Mac 上用 VS Code 插件用的是同一套 skills行为一致。这对团队协作很重要——不会出现我这边能跑你那边不行。3. 技能目录的组织方式与加载机制3.1 一个技能目录里通常有什么虽然仓库的具体文件我没法逐一看但按这类工具的通用约定一个 skill 目录一般包含skills/ test-driven-development/ SKILL.md # 技能说明何时用、怎么用、注意事项 scripts/ # 可执行脚本比如跑测试、生成骨架 templates/ # 代码模板比如测试文件骨架 examples/ # 正例反例给代理参考SKILL.md是核心。它通常包含几块触发条件什么任务该用这个技能、执行步骤有序的操作清单、验证方式怎么确认做对了、边界什么情况下不该用。这四块缺一不可尤其是边界——没有边界的技能代理会滥用。scripts/和templates/是让技能可执行的关键。比如 TDD 技能里可能有个脚本自动生成测试文件骨架并跑一次预期失败这样代理就不用凭感觉写测试了。3.2 代理是怎么看到这些技能的这里有个容易踩的坑技能不是自动全部加载的。如果所有技能都塞进上下文等于没拆。常见的加载机制有两种一种是显式加载。你在对话里说用 TDD 技能来做这个功能代理才去读对应的SKILL.md。这种方式可控但依赖你记得有哪些技能。另一种是索引 按需读取。代理先看一个总索引列出所有技能的名字和一句话描述判断当前任务需要哪个再去读详细内容。这更接近人的工作方式但对索引的质量要求高——描述写得太模糊代理就选错技能。提示如果你发现代理该用技能时不用八成是索引描述没写好。把每个技能的一句话描述写成当你要做 X 时用我比写成我是一个关于 X 的技能有效得多。3.3 技能的依赖与冲突处理技能之间会有依赖。比如重构技能可能依赖测试技能——没有测试覆盖重构就是裸奔。好的技能设计会显式声明依赖代理加载时会一并拉取。冲突则更微妙。假设你有两个技能都规定提交前要跑格式化但一个用 Prettier、一个用 Black代理就懵了。解决办法是在项目级配置里指定优先级或者干脆把冲突的技能合并。我的经验是技能数量控制在 10 个以内超过就容易互相打架维护成本陡增。4. skills CLI 的实操安装、列出、调用4.1 环境准备与安装假设你已经在 Ubuntu 或 Mac 上装好了 Claude Codeclaude命令能跑起来接下来装 skills CLI。这类工具通常是 Node 生态的所以先确认 Node 版本node -v # 建议 18 以上 npm -v然后全局安装具体包名以官方为准这里演示通用流程npm install -g agent-skills-cli skills --version如果是在公司内网npm 源可能不通需要配镜像。这一步在 Ubuntu 服务器上尤其常见别等到装到一半报错才想起来。4.2 把技能装进项目CLI 的核心命令一般围绕安装到当前项目设计cd your-project skills init # 初始化生成 skills 配置目录 skills add test-driven-development skills list # 查看已安装技能skills init会在项目里创建一个配置目录可能是.skills/或类似里面记录装了哪些技能、版本号是多少。这个目录要进 Git这样团队成员 clone 下来跑一次skills sync就能对齐环境。skills add做的事本质是把远程仓库里的技能目录拉到本地并更新索引。这里有个细节技能版本要锁定。如果技能仓库更新了你的项目行为可能突然变化。所以配置文件里应该记录 commit hash 或版本号而不是永远拉最新。4.3 在 Claude Code 里触发技能装好之后怎么让 Claude Code 用上通常有两种方式一是在对话里点名用 test-driven-development 技能给 UserService 加一个 findById 方法二是配置自动触发。在项目的 Claude Code 配置里声明涉及测试的任务默认加载 TDD 技能。这样你不用说代理自己就会去读。我个人的习惯是混合用日常小任务手动点名保证可控重复性高的任务比如每次加 API 端点配自动触发省心。4.4 一个完整的调用示例假设要给一个 Express 项目加删除用户接口用 TDD 技能走一遍# 1. 确认技能已装 skills list | grep test-driven # 2. 在 Claude Code 里发起任务 claude 用 test-driven-development 技能实现 DELETE /users/:id代理的预期行为是先读SKILL.md按里面的步骤——写失败测试 → 跑测试确认失败 → 写最小实现 → 跑测试确认通过 → 重构。每一步它都会调用技能里的脚本而不是自己瞎编命令。这个流程的价值在于可复现。换个人、换台机器只要技能一样代理的行为就一样。这就是把个人经验变成团队资产。5. 把 TDD 技能用透从写测试到重构的闭环5.1 为什么 TDD 特别适合做成技能TDD 的流程是高度结构化的红 → 绿 → 重构。这种有明确阶段、有明确验证的流程正是技能最擅长的场景。相比之下帮我设计架构这种开放任务做成技能反而束手束脚。关键词里专门点了test-driven-development说明这是 agent-skills 的招牌技能之一。它的价值在于用流程约束代理的冲动。没有 TDD 技能时你让代理加功能它往往一口气把实现和测试都写了测试还是照着实现倒推的——这种测试毫无意义只能证明代码和它自己一致。5.2 红绿重构在代理场景下的具体落地红阶段代理先写测试然后跑一次必须看到失败。这一步不能省。如果测试一跑就过说明要么测试写错了要么功能已经存在。技能里的脚本应该强制检查这次运行是否失败失败才继续。绿阶段写最小实现让测试通过。注意最小两个字。代理天然倾向于写得完整但 TDD 要求你只写让当前测试通过的那点代码。技能说明里要明确写不要提前实现未被测试覆盖的逻辑。重构阶段测试全绿之后清理代码。这一步代理容易偷懒觉得能跑就行。技能里可以挂一个 lint 或复杂度检查脚本强制它过一遍。5.3 测试质量怎么保证代理写的测试常见毛病有三个断言太弱只断言不报错、覆盖假象测了 getter 没测逻辑、耦合实现改个内部变量名测试就挂。针对这三点TDD 技能里可以加检查项断言必须包含具体的期望值不能只有expect(x).toBeDefined()每个测试要有明确的这个测试在验证什么行为的注释禁止测试里直接访问私有成员这些规则写进SKILL.md代理每次写测试都会对照。比你在 code review 时反复说测试写扎实点高效得多。5.4 一个反例技能用错地方的后果我见过有人把 TDD 技能用在探索性原型上结果寸步难行。原型阶段需求都没定写测试就是浪费。这时候应该用快速原型类的技能或者干脆不用技能让代理自由发挥。这印证了前面说的技能必须有边界。TDD 技能的SKILL.md里应该明确写不适用于需求未定的探索阶段。没有这句话代理会在错误的场景里机械执行反而拖慢你。6. 在真实项目里落地 agent-skills 的几个关键决策6.1 自建技能还是用现成的现成技能比如官方或社区提供的 TDD、重构、文档生成适合起步但团队特有的规范必须自建。比如你们公司要求所有数据库操作必须走 Repository 层这条规则社区技能里不会有。自建技能的成本没想象中高。一个最小技能就是一个SKILL.md加几个脚本。关键是从真实痛点出发先记录你最近三次 code review 里反复提的问题把它们写成技能。这样出来的技能一定有用不会变成摆设。6.2 技能粒度怎么把握太粗一个技能管所有后端开发等于没拆太细一个技能只管写一个 if 语句维护不过来。我的经验法则是一个技能对应一个可独立验证的工作单元。比如加一个 API 端点写一个数据迁移修一个 bug 并补回归测试都是合适的粒度。判断标准很简单如果这个技能的SKILL.md超过两屏还说不完就该拆如果两个技能总是同时被加载就该合。6.3 和 CI 怎么配合技能在本地约束代理行为CI 在远端兜底。两者要打通技能里跑的测试命令应该和 CI 里跑的是同一套。否则本地绿了、CI 红了代理的验证就失去意义。具体做法是在技能脚本里调用项目的标准测试命令比如npm test而不是自己拼一个。这样 CI 配置改了技能自动跟着变。6.4 团队协作中的技能评审技能进 Git 之后就该像代码一样 review。评审重点看三样触发条件是否清晰会不会误触发、步骤是否可执行有没有含糊的适当处理、验证是否客观能不能自动判断对错。我建议给技能仓库配一个简单的 CI每次 PR 改动技能就跑一遍用这个技能完成一个样例任务看代理行为是否符合预期。这听起来重但比技能悄悄失效、团队却不知道要强。7. 踩过的坑与排查思路7.1 技能装了但代理看不见最常见的现象skills list显示已安装但 Claude Code 就是不用。排查顺序确认技能目录在项目根目录下且路径被配置引用检查索引文件是否更新有些 CLI 需要手动skills sync看代理的上下文里有没有技能索引——如果对话太长索引可能被挤出去了第三步最隐蔽。长对话里早期的上下文会被截断技能索引如果放在最前面就可能丢失。解决办法是把索引放在系统提示或项目配置里而不是靠对话历史携带。7.2 技能脚本在 Mac 能跑、Ubuntu 报错跨平台问题几乎必然遇到。常见原因脚本里用了 macOS 特有的命令比如sed -i 的写法在 Linux 上不同、路径分隔符、换行符CRLF vs LF。对策是技能脚本尽量用 Node 或 Python 写而不是 shell。跨平台语言能省掉大量这类破事。如果非用 shell就在SKILL.md里注明依赖并在 CI 里跑一遍 Linux 环境验证。7.3 代理过度使用某个技能比如你装了 TDD 技能结果代理连改个错别字都要先写测试。这是触发条件写太宽了。修正方法是在SKILL.md的触发条件里加否定条件当改动不涉及逻辑如文案、注释、格式时不使用本技能。7.4 技能更新导致行为突变前面提过版本锁定这里展开说。技能仓库更新后如果你没锁版本下次skills sync就会拉到新版本代理行为可能变化。在团队环境里这种悄悄变化很危险。正确做法配置文件里记录精确版本升级走显式的 PR 流程升级后跑一遍回归任务。把技能当依赖管理而不是当永远最新的文档。7.5 排查用的通用清单遇到技能不生效类问题我一般按这个顺序过一遍检查项命令/动作常见问题技能是否安装skills list装到了全局而非项目索引是否最新skills sync忘了同步路径是否正确看配置文件相对路径写错脚本能否独立跑手动执行脚本缺依赖、权限不足代理是否读到看对话上下文上下文被截断触发条件是否匹配读SKILL.md条件写太窄或太宽这张表基本能覆盖八成问题。剩下两成多半是技能本身设计有缺陷得回去改SKILL.md。8. 我对这套工具链的一点个人判断用了一段时间之后我最大的感受是agent-skills 的价值不在让代理更聪明而在让代理更可控。模型能力已经够强了真正的瓶颈是你怎么让它稳定地按你的方式干活。技能就是那个把你的方式固化下来的载体。另一个体会是别一上来就建一堆技能。先从一两个真实痛点开始用顺了再扩。我见过团队一口气写了二十个技能结果没人维护半年后全过期了代理加载了反而帮倒忙。技能是资产也是负债数量要克制。最后分享一个小技巧把技能当成给新同事的入职文档来写。如果你写的SKILL.md能让一个刚入职的人照着做完任务那代理大概率也能做对。反过来如果人看了都迷糊代理只会更迷糊。这个标准很好用能帮你判断技能写得够不够清楚。