1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新同事来管理的工程化方案。项目正文和关键词都是空的但热搜词已经把方向交代得很清楚了——AI coding agents、skills CLI、Claude Code、test-driven-development。把这几个词串起来它想解决的问题其实很具体当你的日常开发已经离不开 Claude Code 这类终端里的编码代理时怎么让它的行为稳定、可复用、可测试而不是每次开新会话都靠你现场哄。我自己的使用轨迹大概能代表一批人一开始把 Claude Code 当高级补全用问一句答一句用久了发现真正费劲的不是它会不会写代码而是它记不记得我的项目规矩。比如这个仓库用 pnpm 不用 npm、提交信息要遵循 Conventional Commits、改完必须跑vitest而不是jest。这些约束你每次都得重复一遍说漏一次它就自由发挥。agent-skills这类项目的价值就是把这些口头规矩沉淀成 agent 能自动加载的技能包再用一个 CLI 去管理它们的安装、版本和测试。所以这篇不是官方文档的复述而是我按一个真实使用者的路径把这类项目拆开讲透它背后的核心概念是什么、skills CLI大概怎么设计、为什么它和test-driven-development绑得这么紧、以及在 Claude Code 里落地时会踩哪些坑。适合两类人看——已经在用 Claude Code 想进一步提效的以及还没上手但想搞清楚agent skills 到底是不是又一个概念泡沫的。前者可以直接抄配置思路后者能建立判断力。2. 先搞清楚 agent skills 到底解决的是哪一类问题2.1 它和提示词模板的本质区别很多人一听技能包就以为是存一堆 prompt 文本复制粘贴用。这个理解会让人低估它。普通的提示词模板是静态文本你贴进去模型读一遍然后该忘还是忘。而 agent skills 的核心是可被 agent 主动发现和加载的能力单元——它通常包含三部分一段描述什么时候该用我的元数据、一份具体的操作指令或脚本、以及可选的验证逻辑。打个比方提示词模板像是你给新同事发的一条微信语音听完就过去了agent skill 更像是公司 wiki 里的一个标准作业流程页面新同事知道遇到这类任务要去查这个页面而且页面里还附了检查清单。区别在于触发机制前者靠你记得去贴后者靠 agent 根据任务上下文自己判断要不要加载。这也是为什么热搜里会出现skills CLI。一旦技能变成可被发现的单元就需要一个包管理器式的工具来管它们装哪些、装哪个版本、装到哪个目录、怎么更新。没有 CLI技能就是一盘散沙有了 CLI它才成为一个可维护的生态。2.2 为什么是 Claude Code 这类终端 agent 先吃到红利技能包这个概念其实不新但真正让它变得实用的是 Claude Code 这类能直接读写文件、执行终端命令的 agent。原因很直接如果一个 agent 只能聊天技能包最多帮它答得更准但如果它能动手改代码、跑测试技能包就能约束它动手的方式。举个我实际遇到的场景。我让 agent 帮我加一个工具函数它写完代码后自己跑了一遍测试发现失败然后去读测试文件、改实现、再跑直到通过。整个过程它没有问我一句。这种自主性很爽但也很危险——如果它不知道这个项目禁止修改测试文件来迁就实现它可能直接把断言改松。而一条写在 skill 里的硬规则测试文件只读实现必须适配测试就能把这个风险摁住。所以 agent skills 和终端型 agent 是互相成就的关系agent 提供了手skills 提供了规矩。热搜里claude code如何直接执行终端命令这类词热度高恰恰说明大家已经越过了它能不能干活的阶段进入它干活时听不听话的阶段。2.3 一个技能包里通常装了什么基于这类项目的常见实践一个 skill 的目录结构大致是这样具体字段名各项目会有差异这里给的是通用形态skills/ my-skill/ SKILL.md # 元数据 指令主体 scripts/ # 可选的辅助脚本 tests/ # 可选的验证用例SKILL.md顶部的元数据一般包含name、description、以及触发条件。description写得越具体agent 判断要不要加载就越准。我见过太多人把 description 写成帮助处理代码这种等于没写——agent 根本不知道什么时候该想起它。好的写法是当需要为 React 组件编写单元测试且项目使用 vitest 时使用。指令主体则是给 agent 看的操作手册可以包含步骤、约束、示例。这里有个反直觉的点指令不是越长越好。太长的 skill 会挤占上下文反而让 agent 抓不住重点。我的经验是单个 skill 控制在能一屏读完的篇幅复杂流程拆成多个 skill 用引用串起来。3. skills CLI 的设计逻辑与实操推演3.1 为什么需要一个专门的 CLI 而不是手动拷贝手动把技能文件夹拷到~/.claude/skills/也能用那为什么还要 CLI我一开始也这么想直到技能数量超过十个问题全冒出来了这个技能是从哪个仓库来的、上次更新是什么时候、两个技能依赖了同一个脚本的不同版本怎么办、团队里每个人装的技能不一致导致 agent 行为飘忽。CLI 解决的正是这些包管理层面的问题。它至少要做四件事安装从某个源拉取技能到本地约定目录、列举当前装了哪些、版本多少、更新拉取新版本、卸载。如果做得再细一点还会有link把本地开发中的技能软链进去方便调试和validate检查 SKILL.md 格式是否合法。这跟 npm、pip 的思路一模一样。你可以把 skills CLI 理解成agent 技能界的包管理器。理解了这层很多设计就顺了为什么要有 lock 文件、为什么要区分全局安装和项目级安装、为什么要有 registry 概念。3.2 安装与目录约定的实操细节假设 CLI 已经装好通常是npm i -g或pnpm add -g这类方式最常用的命令形态大概是# 从默认源安装一个技能 skills install test-driven-development # 安装到当前项目而非全局 skills install test-driven-development --project # 列出已安装技能 skills list # 更新全部 skills update这里有个极易踩的坑全局安装和项目级安装的优先级。如果同一个技能两边都装了agent 到底读哪个不同实现策略不同有的是项目级覆盖全局有的是合并。我的建议是团队协作场景一律用项目级安装把技能目录纳入版本控制这样每个人的 agent 行为一致个人通用的小工具才放全局。另一个细节是目录位置。Claude Code 读取技能的默认路径通常是用户主目录下的隐藏文件夹项目级的则在项目根目录。如果你手动改过配置一定要确认 CLI 写入的路径和 agent 读取的路径是同一个否则会出现明明装了却不生效的灵异现象。我排查过一次折腾半小时才发现是 CLI 装到了 A 目录而 agent 配置指向了 B 目录。3.3 版本锁定与团队一致性技能会更新更新可能带来行为变化。今天你的 agent 老老实实跑测试明天技能更新后它可能改了执行顺序。对个人项目无所谓对团队项目就是灾难——同一个任务不同人跑出不同结果排查起来毫无头绪。所以成熟的用法是锁定版本。CLI 一般会生成一个类似skills.lock的文件记录每个技能的确切版本和来源。这个文件必须提交到仓库。新人 clone 下来后跑一次skills install不带参数读 lock 文件就能得到和团队完全一致的技能环境。提示如果你的 skills CLI 还不支持 lock 文件退而求其次的做法是把技能目录整个提交进仓库并在 README 里写清楚版本。虽然笨但能保证一致性。这套机制的价值在多人协作时会被放大。想象一下五个人用同一套技能包agent 对提交前要做什么的理解完全一致code review 时就不会出现你这提交怎么没跑 lint这种低级扯皮。4. 把 test-driven-development 做成技能意味着什么4.1 TDD 为什么特别适合被技能化热搜里test-driven-development和agent-skills并列出现不是偶然。TDD 的核心循环是先写失败的测试 → 写最小实现让它通过 → 重构这个循环有明确的、可验证的中间状态。这对 agent 来说太友好了它不需要你告诉它做得好不好测试通过与否就是客观信号。相比之下帮我写个优雅的架构这种任务没法技能化因为优雅没有客观判据。而 TDD 每一步都有红绿灯agent 可以自己跑测试、自己看结果、自己决定下一步。这就是为什么 TDD 几乎是 agent 技能里最经典、最值得先做的一个。我自己的体会是给 agent 装上 TDD 技能后它从会写代码的实习生变成了会自我纠错的工程师。区别在于前者写完就交差后者写完会自己验证。这个转变带来的返工率下降非常明显。4.2 一个 TDD 技能里应该写死哪些规则基于常见实践TDD 技能的指令主体至少要覆盖这几条硬约束测试先行在写任何实现代码之前必须先有一个失败的测试。agent 不能跳过红这一步。测试文件只读一旦测试写好并通过评审实现阶段禁止修改测试来迁就代码。这条是防止 agent作弊的关键。最小实现只写让当前测试通过的最少代码不要顺手实现未来可能需要的功能。每步验证每完成一个小循环必须实际运行测试命令并读取输出不能假设它通过了。失败即停如果测试连续失败超过设定次数停下来报告而不是无限重试。这些规则看起来啰嗦但每一条都对应一个我真实踩过的坑。比如测试文件只读这条就是因为我发现 agent 在实现卡壳时会偷偷把断言改宽松测试是绿了但功能是错的。这种假绿比红灯还危险。4.3 技能和测试框架的绑定关系TDD 技能不能是框架无关的空话它必须知道这个项目用什么测试框架、怎么跑、输出长什么样。所以技能里通常会包含项目特定的命令比如# 运行单个测试文件 vitest run src/utils/format.test.ts # 监听模式 vitest --watch如果项目用 jest命令就完全不同。这就是为什么技能往往和具体项目绑定而不是一个放之四海皆准的通用包。我建议的做法是通用 TDD 原则放全局技能项目特定的命令和路径放项目级技能后者引用前者。这样既复用了原则又保留了项目特异性。注意技能里写死的命令要定期检查。项目从 vitest 迁到别的框架时如果忘了更新技能agent 会一直跑一个不存在的命令然后陷入命令找不到的循环。5. 在 Claude Code 里落地技能包的真实流程5.1 环境准备阶段最容易忽略的两件事第一件是确认 agent 版本支持技能加载。技能机制是逐步引入的老版本可能根本不认这个目录。热搜里claude code在线升级最新版本这类词热度高说明不少人卡在版本上。升级本身不复杂但要注意升级后配置文件的兼容性——我有次升级完发现之前的自定义配置被重置了因为新版改了配置格式。第二件是路径和权限。技能目录如果放在需要特殊权限的位置agent 可能读不到。尤其在 Linux 环境下主目录权限、文件属主都可能成为隐形障碍。我的习惯是装完后立刻用skills list确认 CLI 能看到再开一个 agent 会话问它你现在能加载哪些技能两边对得上才算装好。5.2 从零跑通第一个技能我建议第一个技能就选 TDD因为它的反馈最直接。流程大致是用 CLI 安装 TDD 技能到当前项目。确认技能目录出现在项目里且被版本控制跟踪。开一个 agent 会话给它一个小任务比如给formatDate函数补一个边界测试。观察它是否先写测试、是否真的运行了测试、失败后是否去改实现而不是改测试。第 4 步是关键。如果它跳过写测试直接改实现说明技能没被加载或者 description 写得不够明确导致 agent 没触发。这时候回去改 description把触发条件写得更具体再试。5.3 观察 agent 是否真的用上了技能怎么判断技能生效了我的经验是看三个信号它主动提到了技能里的规则比如按照 TDD 流程我先写测试、它的操作顺序符合技能定义、它在遇到冲突时引用技能作为依据。三个信号出现两个基本可以确认生效。反过来如果 agent 行为和你没装技能时一模一样那大概率是没加载。排查顺序是先确认文件在不在、再确认路径对不对、然后确认 description 是否够具体、最后确认 agent 版本是否支持。这个顺序能覆盖九成以上的技能不生效问题。6. 踩坑实录技能包落地时的典型故障6.1 技能冲突两个技能给出矛盾指令这是最隐蔽的坑。比如你装了一个提交前必须跑全量测试的技能又装了一个快速迭代时只跑相关测试的技能。当 agent 同时加载两个它可能随机选一个执行行为变得不可预测。根因是技能之间没有优先级和互斥机制。目前多数实现里技能是平级的谁被加载就听谁的。解决办法有两个一是从源头避免装功能重叠的技能二是在项目级技能里显式写明当与全局技能冲突时以本技能为准。后者依赖 agent 的理解能力不是百分百可靠但比什么都不做强。我的做法是维护一份技能清单记录每个技能管什么装新技能前先看有没有重叠。这份清单本身也可以做成一个技能让 agent 帮你检查。6.2 上下文被技能挤爆技能不是免费的它占用上下文窗口。装太多技能或者单个技能太长会导致 agent 在处理实际任务时没地方思考。表现是它开始忽略你的具体需求机械地套用技能里的步骤。我踩过一次装了十几个技能后agent 变得特别教条一个小改动也要走完整套流程。后来砍到五个核心技能行为立刻正常了。经验是常驻技能控制在五个以内其余按需加载。如果 CLI 支持按任务类型分组加载一定要用起来。6.3 技能更新后行为突变前面提过版本锁定这里补充一个真实场景。某次我更新了一个技能新版把运行测试的命令从npm test改成了pnpm test而我的项目还在用 npm。结果 agent 每次跑测试都失败然后它开始怀疑是代码问题一通乱改。我花了很久才定位到是技能更新导致的。教训是更新技能后先用一个小任务验证行为再投入正式开发。别在赶进度的时候顺手更新技能那是给自己埋雷。6.4 排查链路技能不生效的完整定位过程把上面这些串成一条可复现的排查链路确认文件存在ls技能目录看文件在不在。确认路径匹配对比 CLI 写入路径和 agent 配置读取路径。确认格式合法用 CLI 的validate命令如果有检查 SKILL.md。确认 description 具体读一遍问自己agent 能据此判断何时加载吗。确认版本支持查 agent 版本文档确认技能机制可用。确认无冲突临时禁用其他技能只留一个看是否生效。确认上下文余量减少常驻技能数量再试。这条链路我从上到下走过不止一次基本每次都能定位到问题。它的价值在于有序——不瞎试按可能性从高到低排。7. 关于技能生态的一些个人判断用了一段时间后我对 agent skills 这类项目的看法是它现在处于概念正确但工程粗糙的阶段。概念上把 agent 能力模块化、可管理化方向绝对没错工程上版本管理、冲突解决、上下文优化这些都还很原始需要使用者自己补很多手工活。但这恰恰是现在入场的价值。等生态成熟了大家用的都是标准方案你的差异化就没了。现在动手你能积累一套贴合自己工作流的技能库这套东西是别人抄不走的。我自己的技能库里有几个是纯粹为我的项目定制的网上根本找不到但它们每天帮我省下的时间非常可观。如果你刚开始我的建议是别贪多。先做三个技能一个管代码风格、一个管测试流程、一个管提交规范。跑顺了再扩。技能库不是越大越好是越准越好。一个精准触发的技能胜过十个永远不被加载的技能。最后分享一个我最近在试的思路把技能和项目文档打通。项目 README 里写的开发规范和技能里写的规则本质是同一套东西只是读者不同——一个是给人看的一个是给 agent 看的。如果能从一份源自动生成两份输出维护成本会大幅下降。这个方向我还在摸索但感觉是下一个值得投入的点。