1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 的能力拆成可复用模块的工程化尝试。关键词里同时出现了skills CLI、Claude Code、test-driven-development这三者放在一起基本勾勒出了它的定位——给命令行里的 AI 编码代理装上一套技能包让它在具体任务里按预设的流程干活而不是每次靠人现编提示词。这件事解决的是一个很现实的痛点。用过 Claude Code 这类终端代理的人都知道它默认很强但强得发散你让它写个功能它可能一口气把测试、实现、文档全糊在一起中间不给你任何检查点你让它改个 bug它可能顺手重构了三个不相关的文件。问题不在于模型能力不够而在于缺少一套稳定的行为约束。agent-skills想做的就是把这些约束沉淀成一个个独立的 skill按需加载、按需触发。它适合谁三类人最该关注一是已经在用 Claude Code 或类似终端代理、但觉得输出不稳定的开发者二是想把团队内部的编码规范、测试流程固化进 AI 工作流的 Tech Lead三是单纯好奇AI agent 的 skill 机制到底怎么落地的技术爱好者。哪怕你只是刚装好 Claude Code读完这篇也能明白为什么光有模型不够还得有 skill 这一层。需要先说明一点agent-skills这个项目本身在公开信息里比较精简下面的内容我会结合 Claude Code 的 skill 机制、skills CLI 的常见设计模式以及 TDD 在 agent 场景下的落地经验来展开。凡是超出原始信息的推断我都会明确标注是基于常见实践的补充你可以对照自己的实际版本做验证。2. skill 机制到底解决了 agent 的哪个老大难2.1 没有 skill 的时候agent 是怎么跑偏的先讲个我自己的真实场景。有段时间我用 Claude Code 做一个 Node 项目的小功能给一个已有的 API 加参数校验。我的提示词写得很清楚——只改 handler别动路由加完写个测试。结果它做了什么它先读了 handler然后觉得路由层也可以更清晰顺手把路由拆了接着发现测试框架是 Jest又顺便升级了 Jest 配置最后给我的 diff 有 200 多行其中真正相关的不到 30 行。这不是模型笨而是agent 的工作模式决定的。终端代理的本质是一个读文件—思考—执行命令—再读文件的循环每一轮它都会基于当前上下文重新判断下一步做什么。如果没有外部约束它的判断标准就是让代码整体更好而不是只完成用户要的那一件事。这个偏差在单轮对话里不明显但在多轮自主执行里会被不断放大。skill 机制的核心价值就在这里它把这一类任务应该怎么做从模型的即时判断变成了预先写好的、可复用的行为契约。当你触发某个 skillagent 拿到的不是一句模糊的帮我写测试而是一整套明确的步骤、检查点和边界。2.2 skill 和普通提示词的本质区别很多人会问那我直接把要求写进 CLAUDE.md 或者系统提示词不就行了区别在于三个字——可组合。普通提示词是全局生效的你写进去的每一条都会影响所有任务。但实际工作中写测试的规范、重构的规范、写文档的规范彼此之间可能是冲突的比如测试要求不要改生产代码重构要求大胆改结构。全塞进一个提示词里模型会精神分裂。skill 的设计是按需加载平时不占用上下文只有当任务匹配到某个 skill 的触发条件时它的内容才被注入。这带来两个好处一是上下文干净模型不会被无关规则干扰二是每个 skill 可以写得很极端因为它只在自己适用的场景里生效。维度全局提示词skill 机制生效范围所有任务仅匹配的任务上下文占用常驻按需注入可组合性差容易冲突好彼此隔离维护方式改一处影响全局独立增删改适合内容通用偏好、项目背景具体工作流、领域流程这张表是我自己在用了一段时间后总结的不一定适用于所有实现但基本反映了 skill 相对提示词的优势所在。2.3 skills CLI 在整条链路里扮演什么角色关键词里有skills CLI这通常意味着项目提供了一套命令行工具来管理 skill 的生命周期。基于常见的 CLI 设计模式它大概率覆盖这几件事列出可用 skill、安装/卸载 skill、查看某个 skill 的详情、以及把 skill 注册到 agent 的配置里。为什么要有 CLI 而不是手动拷文件因为 skill 一旦多了手动管理会失控。你想想如果团队里有 20 个 skill分散在不同人的机器上版本还不一致那我这边跑得好好的你那边不行就会成为日常。CLI 的价值是把 skill 变成可版本化、可分发、可审计的资产——就像 npm 之于 JS 包或者 brew 之于 macOS 软件。提示如果你打算在团队里推广 skill第一件事不是写 skill而是先把 CLI 的安装和更新流程跑通。否则后面每个人手里的 skill 版本对不上排查问题会非常痛苦。3. 把 TDD 塞进 agent 工作流为什么是这套 skill 的重头戏3.1 TDD 天然适合约束 agenttest-driven-development出现在关键词里我认为不是偶然。TDD 的红—绿—重构三步循环本质上就是一套强制的检查点机制而这恰恰是 agent 最缺的东西。普通开发里TDD 的价值是让你先想清楚要什么再动手。放到 agent 场景它的价值被放大了因为 agent 会自主执行多步如果没有检查点它可能一路跑偏到底。而 TDD 的每一步都要求先有失败的测试这就等于给 agent 设了一个硬性门槛——测试没红不许写实现。我实测下来给 agent 加上 TDD skill 之后最明显的变化是 diff 变小了。因为它必须先写测试、跑测试、看到失败这个过程本身就会让它聚焦在这一个行为上而不是整个模块。以前那种顺手重构的情况出现频率大幅下降。3.2 一个 TDD skill 应该包含哪些硬性步骤基于常见实践一个能真正约束住 agent 的 TDD skill内容不该只是请遵循 TDD这种废话而应该把每一步拆到可执行。我整理了一个参考结构确认测试框架和运行命令先读 package.json / pyproject.toml确定用 Jest、Vitest 还是 pytest以及单测的运行命令是什么。这一步不能省否则 agent 会瞎猜命令。写一个失败的测试只测一个行为测试名要描述清楚预期。写完立刻运行确认它是红的。确认失败原因是功能没实现而不是语法错误或导入路径错。这一步很多人会忽略但它是区分真红和假红的关键。写最小实现让测试变绿强调最小不允许顺手加没被测试覆盖的逻辑。跑全量测试确认没有破坏其他用例。重构可选只有在测试全绿的前提下才允许且重构后必须重跑测试。这套步骤看起来啰嗦但正是这种啰嗦才能把 agent 的自由发挥压到最低。3.3 为什么确认失败原因这一步最容易被跳过我要单独把第 3 步拎出来讲因为它是我踩过的最大的坑。有一次我让 agent 按 TDD 写一个日期格式化函数。它写完测试运行报错然后直接进入实现阶段。看起来流程没问题。但后来我发现那个测试之所以失败是因为它 import 了一个根本不存在的模块路径而不是因为函数没实现。也就是说测试从一开始就是坏的后面的变绿毫无意义——它只是把 import 路径改对了函数逻辑压根没验证。这个坑的隐蔽性在于从日志上看测试确实经历了红→绿流程完全符合 TDD。但红的原因错了整个循环就失效了。所以我在自己的 TDD skill 里加了一条硬规则运行失败测试后必须明确说明失败的具体原因且原因必须是断言不通过而不是任何其他类型的错误。这一条加上之后假绿的情况基本消失了。4. 在 Claude Code 里落地 agent-skills 的完整路径4.1 环境准备先把 Claude Code 本身跑顺不管 skill 多好前提是 Claude Code 能正常工作。这一步看似基础但新手卡在这里的比例很高。我按平台分开说。macOS 和 Ubuntu 上的安装通常是通过 npm 全局安装对应的 CLI 包装完之后在终端里能直接调用命令。装完第一件事是验证版本确认不是某个过老的版本。如果你在 Ubuntu 上遇到权限问题大概率是 npm 全局目录的权限没配好这时候不要用 sudo 硬装而是去修 npm 的 prefix 配置否则后面会出现命令找不到的诡异问题。VS Code 里的配置核心是让编辑器里的终端能继承正确的环境变量。很多人遇到的情况是系统终端里 Claude Code 好好的但 VS Code 集成终端里就是找不到命令。原因通常是 VS Code 启动时没有加载 shell 的完整 profile。解决办法要么是从已经配好的终端里启动 VS Code要么去检查 shell 的配置文件有没有被正确 source。注意如果你所在的环境提示该工具在当前地区不可用这属于服务可用性范畴本文不展开讨论请以官方文档的说明为准。我们能做的是把本地环境和 skill 机制本身搞明白。4.2 把 skill 注册进 agent 的三种常见方式skill 写好了怎么让 agent 知道它基于常见实现一般有三种路径项目级配置在项目根目录放一个约定好的配置目录比如.claude/skills/之类agent 启动时自动扫描。这种方式适合这个 skill 只服务这个项目的场景。用户级配置放在用户主目录下对所有项目生效。适合通用型 skill比如 TDD、代码审查。CLI 动态注册通过 skills CLI 安装到某个位置再由 agent 读取。适合需要版本管理和团队分发的场景。我个人的选择是通用流程放用户级项目特有的放项目级需要团队统一的走 CLI。这样既不会让项目配置臃肿又能保证团队协作时的一致性。4.3 触发 skill 的时机自动匹配还是手动指定这是落地时绕不开的一个设计问题。自动匹配的体验好——你只要说帮我加个功能agent 自己判断该用 TDD skill。但自动匹配有风险判断错了skill 就白加载了甚至可能干扰任务。手动指定更可控——你明确说用 TDD skill 来做这件事。缺点是每次都要记得指定。我的做法是混合把最常用、最不容易误判的 skill 设为自动触发比如 TDD因为写测试这个意图很明确把那些边界模糊的 skill 设为手动。这样既省事又不会因为误触发而添乱。触发方式优点风险适合的 skill自动匹配省心无需记忆可能误触发意图明确的流程类手动指定完全可控需要记得用边界模糊的领域类混合兼顾两者配置稍复杂大多数实际场景5. 自己写一个 skill 时哪些细节决定成败5.1 skill 的粒度太粗没用太细累赘写 skill 最容易犯的错是粒度失控。有人写一个前端开发 skill里面塞了组件规范、状态管理、样式约定、测试要求……结果这个 skill 又变成了一个全局提示词失去了按需加载的意义。我的经验是一个 skill 只对应一类可清晰命名的任务。写单元测试是一个 skill重构函数是另一个生成 API 文档是第三个。判断粒度是否合适有个简单标准——如果这个 skill 的触发条件能用一句话说清楚且不会和别的 skill 重叠那粒度就对了。反过来粒度太细也不行。如果每个小动作都要单独一个 skill管理成本会超过收益。我一般控制在一个 skill 覆盖一个完整的小工作流这个层级。5.2 skill 内容里必须写死的三样东西基于我写和用 skill 的经验有三样东西如果不写死agent 就一定会自由发挥具体的命令不要写运行测试要写运行npm test -- --watchfalse。agent 不会猜你的项目用什么命令。明确的边界不要写修改相关代码要写只允许修改src/handlers/下的文件禁止改动路由和配置。边界越具体跑偏越少。完成标准不要写确保功能正常要写所有测试通过且新增测试覆盖了 X 行为。没有完成标准agent 不知道什么时候该停。这三样东西本质上是在把人的判断翻译成机器可执行的规则。翻译得越彻底skill 越可靠。5.3 一个反面案例我写废掉的第一个 skill说个我自己的糗事。我写的第一个 skill 是代码审查内容大概是请仔细审查代码找出潜在问题给出改进建议。写完我还挺得意觉得简洁优雅。结果用起来一塌糊涂。agent 每次审查的维度都不一样这次关注性能下次关注命名再下次关注错误处理。有时候它还会给出这段代码可以更简洁这种没法执行的建议。问题就出在——我把审查这个模糊的词直接丢给了 agent而没有定义审查什么。后来我重写了这个 skill把它拆成固定的检查清单空指针处理、边界条件、错误传播、日志级别、命名一致性……每一条都要求给出问题位置 具体原因 修改建议。改完之后审查结果立刻稳定了而且可执行性大幅提升。这个教训让我明白skill 的价值不在于写得多漂亮而在于把模糊的意图变成确定的动作。6. 实测中那些文档不会告诉你的坑6.1 skill 之间的隐式冲突前面说 skill 彼此隔离但实际用起来冲突还是会发生只是更隐蔽。比如你有一个最小改动skill 和一个重构skill如果任务同时触发了两个agent 就会陷入两难一个让它别动一个让它大动。这种冲突不会报错只会让输出变得精神分裂。我的应对办法是在 skill 里显式声明它的优先级和互斥关系。比如在重构 skill 里写一句本 skill 与最小改动原则冲突时以本 skill 为准但仅限明确要求重构的场景。这种声明看起来多余但能省掉很多莫名其妙的输出。6.2 上下文被 skill 挤爆skill 是按需注入的但注入的内容也占上下文。如果你一次触发了三四个 skill每个都几百行那留给实际代码的上下文就所剩无几了。表现就是 agent 开始忘事——前面读过的文件后面又读一遍或者干脆忽略了某些约束。我的做法是控制单次任务的 skill 数量一般不超过两个。如果确实需要多个流程就分阶段做做完一个再触发下一个。另外skill 内容本身也要精简能一句话说清的别写三段。6.3 版本漂移导致的玄学问题团队协作里最烦的就是这个。同一个 skillA 的机器上跑得好B 的机器上就出问题。排查半天发现是两人的 skill 版本不一样。这种问题靠口头同步是解决不了的必须靠 CLI 做版本管理。我的建议是skill 也要进版本控制并且和项目代码一样有明确的版本号。每次更新 skill都要在团队里同步一次最好写个简单的 changelog。听起来很重但比起事后排查玄学问题的时间这点投入完全值得。6.4 别指望 skill 能兜住所有情况最后说个心态问题。skill 不是银弹它只能约束它覆盖到的场景。遇到 skill 没覆盖的边界情况agent 还是会自由发挥。所以正确的期待是skill 把 80% 的常见情况稳定住剩下的 20% 靠人盯着。如果你指望装了几个 skill 就能完全放手那大概率会失望。我现在的做法是常用流程全部 skill 化但每个任务结束后还是会扫一眼 diff。这个扫一眼的成本很低但能拦住大部分意外。7. 关于这套东西后续还能怎么玩写到这里我想分享一个自己正在尝试的方向把 skill 和项目的 CI 打通。思路是agent 在本地按 skill 完成工作后push 之前先跑一遍 CI 里的检查如果 CI 挂了就把失败信息喂回给 agent让它按对应的 skill 再修一轮。这样等于给 skill 加了一层外部验证比单纯依赖 agent 自己跑测试更可靠。另一个方向是skill 的渐进式加载。现在很多实现是一次性把整个 skill 注入但 skill 里其实有些内容是只在特定步骤才需要的。如果能做到按步骤加载上下文占用还能再降一截。这个目前还在摸索等有稳定结论了再单独写一篇。如果你也在用 Claude Code 这类终端代理我的建议是从一个最小的 skill 开始——就写你最常做的那件事把它拆到可执行跑通再考虑扩展。别一上来就搞一套全家桶那样大概率会烂尾。skill 这东西少而精比多而杂有用得多。