★ FEATURED ARTICLE 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 每次启动都能加载同一套行为准则。适合谁看三类人。第一类是把 Claude Code 当日常主力工具、但总觉得输出质量忽高忽低的开发者第二类是团队里想统一 AI 编码规范、又不想天天口头强调的技术负责人第三类是对skills CLI这种技能即配置思路好奇、想自己搭一套的折腾党。下面我按自己的理解把这套东西拆开讲透。2. agent-skills 到底在解决什么痛点2.1 提示词工程的一次性困境大部分人用 Claude Code 的方式是这样的打开终端敲一句帮我给这个模块加个测试看结果不满意就再补一句用 pytest 写别用 unittest。下次换个项目同样的要求还得再敲一遍。这就是典型的一次性提示词——它只对当前这次对话有效关掉终端就没了。agent-skills的核心思路是把这些反复出现的指令从对话内容变成项目资产。你写一次test-driven-development技能之后所有会话都能复用。这跟当年从手动敲命令进化到写 Makefile是同一个逻辑把隐性知识显性化、把重复劳动自动化。2.2 Agent 的行为漂移问题我实测过一个现象同一个 Claude Code 会话前半小时它老老实实先写测试再改实现聊到后面它就开始偷懒直接改代码不写测试了。这不是模型坏了是上下文里早期的约束被后续对话稀释了。技能文件的价值在于它可以在每次任务开始时被重新注入相当于给 agent 一个每次开工前先读一遍操作手册的机制。这比在对话里反复强调记得写测试要可靠得多因为它不依赖模型的记忆而是依赖文件系统的持久化。2.3 团队协作里的隐性规范一个五人团队每个人用 Claude Code 的习惯都不一样。A 喜欢让它先写文档B 喜欢让它直接改代码C 坚持要跑 lint。结果就是同一个仓库里AI 生成的代码风格五花八门。把技能文件提交到仓库等于把我们团队怎么用 AI这件事写进了代码库。新人 clone 下来agent 自动按团队规范工作不需要口头培训。这是agent-skills在团队场景下最被低估的价值。3. skills CLI 的加载机制与目录约定3.1 技能文件长什么样虽然项目正文是空的但根据skills CLI这个关键词和 Claude Code 的生态惯例技能通常是一个带 frontmatter 的 Markdown 文件。结构大致是这样--- name: test-driven-development description: 强制先写失败测试再写实现最后重构 trigger: 当用户要求新增功能或修复 bug 时 --- ## 工作流程 1. 先阅读相关代码理解现有测试结构 2. 写一个会失败的测试运行确认它确实失败 3. 写最小实现让测试通过 4. 重构保持测试绿灯 5. 运行完整测试套件确认没有回归name是技能标识description是给 agent 看的这个技能干什么trigger是触发条件。正文部分才是真正的行为指令。这种设计的巧妙之处在于元数据和行为分离agent 可以先扫描所有技能的 description决定加载哪个再读正文执行。3.2 目录结构的选择常见的约定是项目根目录下放一个.agent/skills/或者.claude/skills/每个技能一个子目录或一个.md文件。我倾向于用子目录因为技能往往需要附带模板文件、示例代码.agent/ skills/ test-driven-development/ SKILL.md templates/ test_template.py code-review/ SKILL.md checklist.md这样组织的好处是技能不只是一段文字还能带上可复用的模板。比如 TDD 技能里可以放一个测试文件模板agent 写测试时直接套用省得每次从零开始。3.3 CLI 的加载时机skills CLI这类工具通常提供几个命令list列出所有可用技能show name查看某个技能详情run name手动触发。但更关键的是自动加载——当 agent 启动或接到任务时CLI 会根据 trigger 匹配把相关技能注入上下文。这里有个容易踩的坑技能加载顺序会影响行为。如果code-review和test-driven-development同时被加载谁先谁后可能导致 agent 先审查还是先写测试。我的经验是把流程类技能TDD排在检查类技能review前面因为流程决定做什么检查决定做得对不对。4. 用 TDD 技能驯服 Claude Code 的实操4.1 为什么选 TDD 作为第一个技能热搜词里test-driven-development单独列出来说明这是社区公认最值得沉淀的技能。原因很简单TDD 是少数能自我验证的工作流。你让 agent 写文档它写得对不对你很难判断你让它写测试测试跑不跑得过是客观的。这给了 agent 一个明确的反馈信号。而且 TDD 天然适合 agent红-绿-重构三步每步都有明确的输入输出。agent 不需要理解业务只需要让测试从红变绿。这比让它自由发挥要可控得多。4.2 完整的技能文件写法我基于常见实践整理了一份可以直接抄的 TDD 技能文件--- name: test-driven-development description: 任何代码改动都必须先有失败的测试 trigger: 新增功能、修复 bug、重构 priority: high --- ## 铁律 没有失败的测试不许写实现代码。 ## 步骤 ### 第一步红 - 阅读需求找到最相关的现有测试文件 - 写一个测试描述期望行为 - 运行测试确认它失败且失败原因是功能未实现而非语法错误 - 如果测试直接通过说明测试写错了重写 ### 第二步绿 - 写最少的代码让测试通过 - 不要提前优化不要加测试没要求的功能 - 运行测试确认通过 ### 第三步重构 - 在测试保护下清理代码 - 每次重构后重跑测试 - 确认所有测试仍然通过 ## 禁止事项 - 禁止一次写多个测试再一起实现 - 禁止跳过确认测试失败这一步 - 禁止在测试里 mock 掉被测对象本身这份文件的关键在于把确认测试失败单独列成一步。我踩过的坑就是agent 写完测试直接跑看到绿色就以为成功了其实是因为测试根本没断言到点子上。强制它确认失败原因是功能未实现能过滤掉大量假测试。4.3 在 Claude Code 里挂载技能假设你已经装好了 Claude Code在项目根目录创建.agent/skills/test-driven-development/SKILL.md然后有两种挂载方式。第一种是手动引用在对话开头说请加载 test-driven-development 技能然后帮我实现用户登录。agent 会去读那个文件按里面的流程走。第二种是自动加载如果你的skills CLI支持 hook可以配置在每次会话启动时自动扫描.agent/skills/并注入所有priority: high的技能。这样你什么都不用说agent 默认就按 TDD 工作。提示自动加载技能太多会挤占上下文窗口。建议只把 2-3 个核心技能设为自动加载其余按需手动触发。4.4 实测效果与边界我在一个 Python 项目上实测了这套流程。没挂技能时让 Claude Code给这个函数加个边界检查它直接改了实现没写测试。挂了 TDD 技能后同样的指令它先去找tests/目录写了一个test_boundary_check跑了一遍确认失败然后才改实现。但要注意边界TDD 技能对探索性任务不适用。比如你让它调研一下这个库怎么用它不该先写测试。所以技能文件里的trigger要写清楚别让它无差别触发。我的做法是加一条如果任务是调研或问答跳过本技能。5. 技能组合与优先级设计5.1 单技能不够用组合才是常态真实开发里一个任务往往需要多个技能协作。比如修复登录 bug这件事理想流程是先test-driven-development写复现测试再debugging定位根因最后code-review自查。如果这三个技能各自为政agent 可能只加载一个就开干。解决办法是在技能文件里声明依赖关系--- name: bug-fix description: 修复 bug 的标准流程 trigger: 用户报告 bug composes: - test-driven-development - debugging - code-review ---composes字段告诉 CLI加载这个技能时把依赖的技能也一起加载并按声明顺序执行。这样 agent 拿到的是一套完整流程而不是零散指令。5.2 优先级冲突怎么处理技能之间会打架。比如code-review要求改动前先审查现有代码test-driven-development要求先写测试。如果两个都设成 high priorityagent 可能先审查再写测试也可能反过来。我的处理原则是流程技能优先于检查技能。因为流程决定做什么检查决定做得对不对顺序错了会浪费一轮。具体做法是给技能加priority数值数字小的先执行技能类型建议优先级理由流程类TDD、debug10-20决定任务主线检查类review、lint50-60在主线完成后执行辅助类doc、commit80-90收尾工作这个数值不是绝对的但有个原则越靠近任务开始的技能优先级越高。5.3 技能版本管理技能文件提交到仓库后就会面临版本问题。团队里有人改了 TDD 技能其他人的 agent 行为就变了。这时候需要像管理代码一样管理技能用 git 分支、写 changelog、重要改动走 PR review。我见过一个团队的做法挺聪明他们把技能文件放在独立的agent-skills仓库主项目通过 submodule 引用。这样技能可以跨项目复用改一次所有项目生效。代价是 submodule 的更新需要手动同步适合技能已经稳定的团队。6. 踩过的坑与排查链路6.1 技能加载了但 agent 不遵守这是最常见的问题。你明明挂了 TDD 技能agent 还是直接改代码。排查链路是这样的第一步确认技能真的被加载了。用skills list看当前会话加载了哪些技能。如果列表里没有说明路径配错了或者 CLI 没扫描到。第二步确认 trigger 匹配。有些 CLI 只在任务描述命中 trigger 关键词时才加载技能。如果你的 trigger 写的是新增功能但你说的是加个方法可能就不匹配。把 trigger 写宽泛一点或者用正则。第三步确认技能内容没被截断。技能文件太长时CLI 可能只注入前 N 行。我遇到过 SKILL.md 写了 500 行结果 agent 只看到前 100 行后面的禁止事项根本没读到。解决办法是把核心约束放在文件开头。第四步确认模型没选择性忽略。说实话再好的技能文件也不能保证 100% 遵守。模型有时候就是会偷懒。这时候需要在关键节点人工介入比如它跳过确认测试失败时你直接说回去补上这一步。6.2 技能之间互相覆盖有一次我同时挂了test-driven-development和quick-prototype两个技能。前者要求先写测试后者要求快速出原型测试后补。结果 agent 行为极其混乱一会儿写测试一会儿跳过。根因是两个技能的指令直接冲突而 CLI 没有冲突检测机制。修复方法是给技能加互斥声明--- name: quick-prototype excludes: - test-driven-development ---加载quick-prototype时自动卸载 TDD。这个字段不是所有 CLI 都支持如果不支持就只能靠人工在对话里明确这次用原型模式不要 TDD。6.3 技能文件里的隐性假设我写过一个code-review技能里面写检查所有新增函数是否有 docstring。结果在一个没有 docstring 习惯的老项目里agent 疯狂给每个函数补文档制造了大量无意义 diff。问题出在技能文件假设了项目有 docstring 规范但实际没有。修复方法是把绝对指令改成条件指令如果项目现有代码普遍有 docstring则新增函数也要有否则保持一致不主动添加。这个坑的教训是技能文件要写适配规则而不是绝对规则。agent 面对的是各种风格的项目硬性规定往往适得其反。6.4 排查用的日志技巧当技能行为不符合预期时让 agent 自己报告它加载了什么技能、按什么顺序执行。可以在技能文件末尾加一段## 自检 执行任务前先输出 - 当前加载的技能列表 - 本次任务将遵循的步骤 - 如果有技能冲突指出冲突点这段自检输出会成为排查的第一手资料。我靠这个发现过好几次技能没加载和优先级排错的问题。7. 把技能体系扩展到团队与多项目7.1 从个人技能到团队规范个人用技能怎么舒服怎么来。团队用技能就得考虑共识。我的建议是分两层基础层是所有人都必须遵守的比如提交前跑测试个人层是各人偏好比如注释用中文还是英文。基础层技能放主仓库走 PR review个人层技能放本地.agent/skills/local/加进.gitignore。CLI 加载时先加载基础层再加载个人层个人层可以覆盖基础层的非强制项。7.2 跨项目复用的目录策略如果你有多个项目技能文件重复维护会很痛苦。三种策略全局技能目录放在用户主目录下所有项目共享。适合个人通用技能比如提交信息规范。Git submodule技能独立仓库项目引用。适合团队统一规范改一次全生效。包管理分发把技能打包成 npm 包或 pip 包项目安装依赖。适合技能已经成熟、需要版本锁定的场景。我目前用的是混合方案通用技能走全局目录团队规范走 submodule实验性技能放项目本地。这样既有复用又能灵活试错。7.3 技能的效果度量怎么知道技能有没有用我跟踪两个指标返工率和测试覆盖率变化。挂了 TDD 技能后如果 agent 生成的代码返工率下降、测试覆盖率上升说明技能有效。如果没变化要么技能没加载要么技能写得不对。具体做法是每周抽 10 个 AI 生成的任务统计其中有多少需要人工修正。这个数字比任何主观感受都可靠。我自己的数据是没挂技能时返工率大概 40%挂了 TDD review 组合后降到 15% 左右。当然这个数字因项目而异但趋势是明确的。7.4 技能不是越多越好最后说个反直觉的结论技能数量超过一定阈值后效果会下降。原因是上下文窗口有限技能文件占用的 token 越多留给实际代码的越少。而且技能太多时agent 在该用哪个上会犹豫反而降低效率。我的经验值是自动加载的技能不超过 3 个总技能库不超过 15 个。超过这个数就该考虑合并或淘汰了。定期 review 技能库把半年没用过的删掉跟清理依赖是一个道理。这套agent-skills的思路本质上是在 AI 编码时代重建工程规范这件事。以前规范靠文档和 code review 传递现在多了一个载体——技能文件。它能不能成为主流还不好说但至少给了我们一个把怎么用 AI这件事沉淀下来的具体抓手。我自己的体会是写技能文件的过程其实也是逼自己把模糊的开发习惯想清楚的过程这个收益本身就值回票价了。
阅读完成 · 觉得有帮助？
