1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当工程对象来管理的技能体系。关键词里同时出现了skills CLI、Claude Code、test-driven-development这三者放在一起指向一个很具体的场景——用命令行工具把可复用的技能skill注入到 AI 编码代理的工作流里并且用测试驱动开发的方式约束它的行为。先把概念对齐避免后面越看越糊。所谓AI coding agent指的是能自己读文件、改代码、跑命令、看报错再迭代的那类工具Claude Code 是其中比较有代表性的一种。而skill在这里不是提示词模板这么简单它更像一份带触发条件、带执行步骤、带验收标准的操作手册agent 在遇到匹配场景时会自动加载并遵循。skills CLI则是管理这些技能的命令行入口负责安装、列出、启用、禁用、更新。为什么这个组合值得单独写一篇因为大多数人用 AI 编码工具还停留在对话式提问阶段问一句、答一句、复制粘贴、手动验证。这种方式在单文件小改动上够用一旦进入多文件重构、跨模块联调、需要反复回归的场景就会暴露出三个问题——上下文丢失、行为不可复现、质量靠运气。agent-skills想解决的正是这三件事把怎么做沉淀成技能把做对了没有交给测试把怎么调用交给 CLI。这篇文章适合谁看如果你已经在用 Claude Code 或类似的编码代理但总觉得它时灵时不灵那这篇能帮你把不确定性压下去如果你还没上手只是想搞清楚agent-skills到底解决什么问题那也能从原理和场景层面看明白。我会尽量把每一步的为什么讲透而不是只丢一堆命令让你照抄。2. skills CLI 到底在管什么技能的生命周期拆解2.1 技能不是提示词它是一份带契约的说明书很多人第一次接触 skill 会误以为就是把一段 prompt 存成文件。实际不是。一个合格的 skill 至少包含四部分触发描述什么情况下该用、前置条件需要哪些文件、环境、依赖、执行步骤具体做什么按什么顺序、验收标准怎么判断做完了、做对了。这四部分缺一不可尤其是验收标准——没有它agent 会自我感觉良好地宣布完成而你打开代码一看全是坑。我自己的经验是把 skill 当成给一个新入职同事写的 SOP 来写效果最好。你不会跟新同事说帮我优化一下这段代码你会说这段代码目前的问题是 N1 查询请改成批量查询改完后用现有的test_user_list用例验证确保返回条数和字段不变。skill 就应该是这个粒度。2.2 CLI 的三个核心动作装、列、跑skills CLI的价值在于把技能从散落在各处的 markdown变成可管理的资产。它通常提供三类动作安装/注册把某个技能目录或远程技能包注册到本地技能库让 agent 能发现它。列举/检索列出当前可用的技能按标签、场景、语言过滤避免我明明写过却找不到。启用/禁用与执行针对当前任务启用特定技能或者直接让 CLI 触发某个技能跑一遍。这里有个容易被忽略的细节技能的发现机制。agent 不会自动读你所有的 markdown它需要一个索引。CLI 生成的索引文件通常是 JSON 或 YAML决定了 agent 在什么上下文下能看到哪些技能。索引写得太宽泛agent 会乱用技能写得太窄又永远触发不了。我的做法是给每个技能写 3 到 5 个触发短语覆盖同义表达比如重构拆分函数降低复杂度都指向同一个技能。2.3 为什么要有版本和依赖管理技能会演进。今天你写的React 组件拆分技能明天项目从 class 组件迁到 hooks技能内容就得改。如果没有版本概念你改完之后旧任务复现不出来排查成本极高。所以成熟的 skills CLI 会记录技能的版本、依赖的其他技能、以及适用的项目类型。提示给技能加版本号不是为了好看是为了在出问题时能回滚。我踩过一次坑改了一个数据库迁移技能后新任务全挂最后靠版本回滚才定位到是技能里一条 SQL 写错了。3. 把 test-driven-development 焊进 agent 的工作流3.1 为什么 TDD 和 agent 是天然一对AI 编码代理最大的风险不是写不出代码而是写出了看起来对但实际错的代码。它很擅长生成语法正确、风格统一、甚至注释齐全的代码但逻辑是否满足需求它自己判断不了。这时候test-driven-development就成了唯一的客观标尺。TDD 的经典循环是红-绿-重构先写一个会失败的测试红再写最少量的代码让它通过绿最后在测试保护下重构。把这个循环交给 agent等于给它装了一个对错判定器。agent 每改一次代码就跑一次测试失败了就根据报错继续改直到全绿。这个过程不需要你盯着你只需要保证测试本身是对的。3.2 让 agent 先写测试还是先写实现这是个有争议的点。我的实践结论是测试由人来定契约实现由 agent 来填。具体说你先写好测试的骨架——输入是什么、期望输出是什么、边界条件有哪些——然后让 agent 去实现。如果让 agent 连测试一起写它很容易写出迎合自己实现的测试比如把断言写得很松或者干脆测了个无关紧要的东西。在agent-skills的语境下这意味着要有一个专门的写测试技能和一个实现功能技能两者分开。写测试的技能里要明确要求覆盖正常路径、边界值、异常输入三类用例且断言必须具体到值不能只断言不报错。3.3 测试跑不动时的排查顺序agent 跑测试失败是常态关键是排查链路要清晰。我总结的顺序是先看是测试本身错了还是实现错了。把测试单独跑一遍确认它在旧代码上是通过的。看报错类型。语法错误、导入错误、断言失败三类问题的处理方式完全不同。看是不是环境问题。依赖没装、路径不对、端口占用这些和代码逻辑无关。最后才怀疑实现。让 agent 输出它改动的 diff逐行对照测试期望。这个顺序能避免一个常见陷阱agent 一看到测试失败就去改实现结果改了半天发现是测试文件里少了个 import。4. 在 Claude Code 里落地 agent-skills 的完整路径4.1 环境准备阶段最容易忽略的两件事安装 Claude Code 本身不复杂但有两个细节经常被跳过。第一是工作目录的边界。agent 默认能访问的目录范围决定了它的视野如果项目是多仓库结构你要么把它放在合适的根目录要么显式配置可访问路径否则它会找不到依赖文件。第二是权限模式。agent 执行终端命令、写文件这些动作是否每次都需要你确认直接影响效率。我的建议是在可信项目里开启较宽松的权限在陌生仓库里保持逐条确认。配置 VS Code 插件时重点看三个配置项模型选择、上下文范围、以及是否启用技能索引。技能索引这一项如果没开你装了再多 skill 也不会被加载。4.2 技能目录的组织方式一个能长期维护的技能库目录结构应该按领域 动作两层来分而不是按时间或作者。比如skills/ testing/ write-unit-test/ fix-failing-test/ refactor/ extract-function/ reduce-complexity/ database/ write-migration/这样分的好处是当你要找和测试相关的技能时一眼就能定位。每个技能目录下至少有一个SKILL.md描述触发条件和步骤和一个可选的examples/目录放几个真实用例帮 agent 理解预期。4.3 从零跑通第一个技能不要一上来就写十个技能。先写一个最小可用的跑通整条链路再复制模式。我的第一个技能通常是修复失败的测试因为它触发条件明确有测试失败、验收标准明确测试通过、风险低不改业务逻辑。具体步骤在技能目录下创建SKILL.md写清楚触发条件当测试运行失败且报错指向断言不匹配时使用。写执行步骤先读失败测试的断言再读被测函数对比期望与实际定位差异点做最小改动。写验收标准目标测试通过且同文件其他测试不被破坏。用 CLI 注册这个技能确认它出现在列表里。故意制造一个失败的测试让 agent 处理观察它是否按技能步骤走。跑通之后你会发现agent 的行为从随机应变变成了按流程执行稳定性提升非常明显。5. 技能设计中的取舍什么时候该拆什么时候该合5.1 技能粒度太细的代价新手容易走极端把每个小动作都拆成一个技能结果技能库膨胀到几十个agent 在索引里挑花眼反而不知道该用哪个。我见过一个项目光格式化代码就有三个技能触发条件还互相重叠最后 agent 每次都要问用户你想用哪个。判断粒度是否合适的标准是这个技能能否独立完成一个有意义的验收。如果它做完之后你没法判断对错说明它太细了应该和上下游合并。5.2 技能之间如何协作复杂任务往往需要多个技能串联。比如新增一个 API 接口可能涉及写测试技能 → 写实现技能 → 写文档技能 → 跑回归技能。这时候有两种组织方式一种是在一个复合技能里按顺序调用子技能另一种是让 agent 自己根据任务拆解。我的偏好是前者因为可控。复合技能里明确写清楚每一步的输入输出以及失败时怎么回退。这样即使中间某步挂了你也能知道卡在哪。5.3 用表格对比不同组织策略策略适用场景优点风险单一细粒度技能动作明确、独立性强复用性高库膨胀、触发冲突复合技能串联多步骤固定流程可控、可回退灵活性差agent 自主拆解探索性任务适应性强不可复现实际项目里通常是混合使用核心流程用复合技能固化边缘探索交给 agent 自主。6. 实测中那些文档不会告诉你的坑6.1 技能描述里的隐性假设写技能时你会不自觉地假设一些前提比如项目用 npm测试框架是 jest代码在 src 目录下。这些假设在你自己的项目里成立换个项目就崩。解决办法是在技能开头显式声明前置条件并且让 CLI 在加载时做一次校验不满足就拒绝加载而不是让 agent 跑到一半才发现。6.2 agent 会假装执行了技能这是最隐蔽的坑。有时候 agent 会声称我已按照技能步骤完成但实际上它跳过了某几步或者只做了表面功夫。防范方法是给关键步骤加可验证的产物比如必须生成一个测试报告文件必须在日志里打印改动前后的行数。没有产物就无法证明它真的做了。6.3 上下文窗口被技能描述挤爆技能描述写得太长会占用宝贵的上下文空间导致 agent 看不到真正的代码。我的经验是单个技能的描述控制在 500 字以内详细内容放到examples/里按需加载。CLI 支持懒加载的话一定要开启。6.4 模型切换后技能行为漂移不同模型对同一份技能描述的理解会有差异。你在某个模型上调好的技能换一个模型可能就不好使了。这不是技能写错了而是模型的指令遵循能力不同。应对办法是给技能写模型无关的表述避免依赖特定模型的特殊能力并且在切换模型后做一次回归测试。7. 把技能库当成长期资产来经营7.1 定期清理和归档技能库和代码库一样会腐化。三个月没用过的技能要么删掉要么归档到deprecated/目录。判断标准很简单如果它连续多个迭代都没被触发说明要么触发条件写错了要么这个场景已经不存在了。7.2 用真实任务反哺技能最好的技能来源不是凭空设计而是从真实任务里提炼。每次你手动解决了一个重复性问题就顺手把它写成技能。这样积累下来的技能库每一个都经过实战检验比拍脑袋写的靠谱得多。7.3 团队协作时的技能共享如果多人共用一套技能库需要约定命名规范和评审流程。我的做法是新技能先放在proposed/目录用一段时间验证有效后再移到正式目录。同时给每个技能标注维护者出问题能找到人。8. 关于 agent-skills 我个人的几点体会用下来最深的感受是agent-skills这类工具真正改变的不是AI 能不能写代码而是AI 写代码这件事能不能被管理。没有技能体系的时候你用 agent 像开盲盒每次结果都不一样有了技能体系它变成了一个可预期、可复现、可回滚的工程流程。另一个体会是测试驱动开发在这个体系里不是可选项是基础设施。没有测试技能就没有验收标准agent 就没有反馈信号整个闭环就断了。所以如果你打算认真用 agent-skills先把项目的测试跑通这一步省不了。最后分享一个小技巧给每个技能写一句失败时的兜底动作。比如如果三次尝试后测试仍失败停止改动并输出当前 diff 和报错。这一句话能避免 agent 陷入无限循环也能让你在它卡住时快速接手。这个细节文档里通常不写但实际用起来能省很多时间。