1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新同事来培养的技能体系。标题里的agent指向的是执行主体——AI 编码代理skills指向的是能力单元——它需要掌握哪些可复用、可组合、可验证的本事。两者拼在一起本质上回答了一个问题当我们把一个 AI 代理放进真实工程环境时它到底需要哪些职业技能这些技能又该怎么组织、怎么训练、怎么验收这个判断不是凭空来的。结合相关热搜词里高频出现的AI coding agents、skills CLI、Claude Code、test-driven-development可以勾勒出这个项目的核心轮廓它大概率围绕 Claude Code 这类终端里的 AI 编码代理展开用一套 CLI 工具来管理技能这种可插拔单元并且把测试驱动开发TDD作为技能落地和验证的主线方法。换句话说它想解决的不是怎么让 AI 写出一段代码而是怎么让 AI 稳定地、可复现地、按工程规范地完成一整类任务。为什么这件事值得单独拿出来讲因为绝大多数人用 AI 编码代理的现状是每次开新会话都要重新解释项目结构、重新强调代码风格、重新叮嘱先写测试再写实现。这种重复劳动不仅低效更致命的是不可复现——同一个任务今天跑通了明天换个会话可能就翻车。agent-skills这类项目的价值就在于把口头叮嘱沉淀成结构化技能让代理的行为从看运气变成有章法。这篇文章适合三类人看一是已经在用 Claude Code 或类似终端代理、但总觉得它不够听话的开发者二是想给团队搭建一套 AI 协作规范的技术负责人三是对 AI coding agent 底层工作机制好奇、想自己动手做技能封装的人。我会从技能的本质、CLI 的组织方式、TDD 如何成为技能验证的骨架、以及实际落地时的坑这几个角度把这件事讲透。2. 技能不是提示词拆解 agent-skills 的核心抽象2.1 为什么提示词这个心智模型会害了你很多人第一次接触 AI 编码代理脑子里装的还是提示词工程那套东西写一段足够详细的话模型就能照做。这个模型在单轮问答里勉强能用但放到代理场景里就会迅速崩塌。原因很简单——代理是多轮、有状态、会调用工具的。它要读文件、跑命令、看报错、改代码、再跑测试中间任何一步的上下文丢失或指令漂移都会让最终结果偏离预期。提示词是一次性的技能是可复用的。提示词藏在你的聊天记录里技能躺在仓库里可以被版本控制。提示词靠你每次手动粘贴技能靠 CLI 一条命令加载。这个差别看起来只是工程化程度的不同实际上是可靠性量级的不同。我自己的经验是一个没有技能封装的代理完成中等复杂度任务的首次成功率大概在三成到五成之间而把关键约束沉淀成技能之后这个数字能稳定到七八成以上剩下的偏差也大多集中在需求本身模糊的地方而不是代理忘了规矩。2.2 一个技能应该包含哪些要素把技能当成一个可交付的工程单元来看它至少要有四个部分缺一不可。触发条件什么情况下该用这个技能。比如当任务涉及新增一个 API 端点时、当需要修改数据库 schema 时。触发条件写得越精确代理越不容易在不该用的时候乱用。执行步骤具体怎么做。这里的关键是步骤要可执行、可验证而不是请仔细考虑这种废话。好的步骤像菜谱先做什么、再做什么、每步的产出是什么。约束与禁忌哪些事绝对不能做。比如不要直接改生产配置、不要跳过测试直接提交、不要引入新的第三方依赖而不说明理由。这些约束是技能的灵魂因为它们把团队的工程纪律编码了进去。验收标准怎么判断这个技能执行成功了。这一条最容易被忽略但恰恰是 TDD 能发挥作用的地方——验收标准最好就是一组能跑通的测试。我用一个表格把提示词和技能的差异摆出来会更直观维度提示词技能存储位置聊天记录、笔记仓库、版本控制复用方式手动复制粘贴CLI 加载、自动触发可验证性靠人肉检查靠测试、靠验收标准团队共享口口相传拉取仓库即可演进方式每次重写提交、评审、迭代2.3 skills CLI 在整条链路里扮演什么角色skills CLI这个词出现在热搜里说明这个项目大概率提供了一个命令行工具来管理技能。它的职责我想不外乎这几件事列出当前可用的技能、把某个技能加载进当前会话、校验技能定义是否合法、以及可能的话根据当前任务自动推荐或激活相关技能。为什么要有 CLI 而不是纯靠文件因为代理的工作环境是终端。你在终端里敲claude启动代理那么管理技能最自然的方式也是在终端里敲命令。CLI 还带来一个隐性好处可脚本化。你可以把加载某组技能写进项目的启动脚本让每个新会话都自动带上正确的技能集彻底消灭忘了叮嘱这个问题。提示如果你打算自己实现类似的技能管理建议把技能定义做成纯文本比如 Markdown 加 frontmatter而不是塞进数据库或二进制格式。纯文本的好处是可 diff、可评审、可被代理直接读取这三点在协作场景里价值极高。3. 用 TDD 给技能装上验收开关3.1 为什么偏偏是测试驱动开发热搜词里test-driven-development和agent-skills并列出现这不是巧合。TDD 的核心循环是红-绿-重构先写一个会失败的测试再写刚好让它通过的实现最后在测试保护下重构。这个循环对 AI 代理来说简直是量身定做因为它把模糊的自然语言需求翻译成了明确的、机器可判定的成功条件。代理最怕的是什么是我觉得我做完了但实际没做完。人类工程师有直觉能感觉到这里好像还差点意思代理没有这种直觉它需要一个客观信号告诉它停你成了或者不行继续改。测试就是这个信号。当技能里写明验收标准是npm test全绿代理就有了明确的终止条件不会无限自我怀疑也不会过早收工。3.2 把 TDD 循环写进技能定义一个 TDD 风格的技能它的执行步骤应该严格遵循红-绿-重构。我把它拆成代理能直接照做的形式读需求写失败测试根据任务描述先写出能表达预期行为的测试用例运行它确认它失败红。这一步的产出是一个失败的测试和失败原因。写最小实现只写让测试通过所需的最少代码不提前优化不加没被测试覆盖的功能绿。在测试保护下重构清理重复、改善命名、抽取函数每改一步就跑一次测试确保始终是绿的。补充边界测试针对空输入、超长输入、并发、异常路径补充测试重复上述循环。这套步骤之所以有效是因为它把质量从一个主观判断变成了一个过程约束。代理不需要理解什么是好代码它只需要遵守这个循环好代码就是循环的自然产物。3.3 验收标准怎么写才不会被代理钻空子这里有个坑我踩过如果你把验收标准写成测试通过即可代理可能会写出空洞的测试——比如断言expect(true).toBe(true)然后宣布任务完成。测试是绿的但什么都没验证。防钻空子的办法有几个。第一在技能里明确要求测试必须覆盖至少一个失败路径和一个成功路径。第二要求测试断言具体的值而不是只断言不抛异常。第三也是最狠的一招让代理先写测试人工或另一个代理评审测试通过后再让它写实现。这样测试的质量就被锁死了实现阶段没有作弊空间。验收标准写法代理可能的钻空子方式加固方法测试通过写空断言要求覆盖成功失败路径功能正常无法判定代理自说自话改成可执行的测试命令代码整洁主观无法验证引入 lint 规则机器判定性能达标不测就宣称达标给出基准测试和阈值4. 在 Claude Code 里落地这套技能体系的实操路径4.1 环境准备阶段最容易忽略的两件事热搜里关于 Claude Code 安装、配置的词条一大堆说明很多人卡在环境这一步。我不重复官方文档的步骤只讲两个最容易被忽略、但会直接影响技能体系能否跑起来的点。第一件是工作目录的约定。代理的技能加载、文件读写、命令执行都相对于某个工作目录。如果你在错误的目录启动代理它可能读不到技能定义或者把文件写到不该写的地方。我的习惯是每个项目根目录放一个明确的技能目录比如.agent/skills/启动代理前先cd到项目根确认pwd正确。这个动作看起来多余但能省掉大量为什么技能没生效的排查时间。第二件是权限边界。代理要执行终端命令、要读写文件这些能力必须被明确约束。哪些目录可写、哪些命令可跑、要不要每次确认这些配置直接决定了技能体系是提效工具还是事故来源。我的建议是初期把权限收得紧一点每次危险操作都要求确认等技能稳定运行一段时间、你对其行为有把握了再逐步放开。4.2 从零写第一个技能以新增 API 端点为例假设你的项目是个 Web 服务你想让代理能规范地新增 API 端点。这个技能可以这样组织触发条件任务描述里出现新增接口、添加端点、实现某个路由等意图。执行步骤阅读现有的路由文件和控制器理解项目的分层约定。先写集成测试覆盖成功响应、参数校验失败、资源不存在三种情况。运行测试确认失败。实现路由、控制器、必要的服务层逻辑。运行测试直到全绿。更新 API 文档如果项目有文档约定。约束不引入新的 Web 框架不修改已有的公共接口签名错误响应格式必须与现有接口一致。验收标准新增的集成测试全绿且现有测试套件无回归。把这个技能写成 Markdown 文件放进技能目录用 CLI 加载代理在遇到相关任务时就会自动遵循这套流程。我实测下来最大的收益不是代码写得更快而是代码风格和错误处理的一致性——以前每个端点都长得不太一样现在它们像同一个人写的。4.3 技能的组合与优先级别让代理选择困难当技能多起来之后一个新问题会出现多个技能同时匹配当前任务代理该听谁的比如新增 API 端点和修改数据库 schema可能同时触发而它们的约束有冲突。解决办法是给技能定义优先级和依赖关系。优先级高的技能约束优先满足有依赖的技能按依赖顺序执行。比如修改 schema应该先于新增端点执行因为端点可能依赖新的数据字段。这些关系最好在技能定义里显式声明而不是指望代理自己推理——代理的推理能力在复杂场景下并不可靠。注意技能数量不是越多越好。我见过有人一口气写了三十个技能结果代理在加载和匹配上花的时间比干活还多而且技能之间的冲突排查成本急剧上升。建议从三到五个核心技能起步跑顺了再逐步增加。5. 那些文档不会告诉你的坑5.1 技能定义写得太聪明反而坏事新手写技能时容易犯一个错把技能写成一篇散文充满请仔细分析、请综合考虑这类模糊指令。这种技能看起来很有智慧实际上给了代理太大的自由裁量空间导致行为不可预测。正确的做法是把技能写得笨一点步骤明确、约束具体、验收可执行。宁可写得像流水线作业指导书也不要写得像哲学论文。代理不需要你教它思考它需要你告诉它做什么、按什么顺序、做到什么程度算完。5.2 测试环境与真实环境的偏差会骗过验收TDD 的验收依赖测试但测试本身可能和真实环境有偏差。比如测试用的是内存数据库真实环境用的是持久化数据库那么测试全绿并不等于功能可用。这个坑在技能体系里会被放大因为代理会完全信任测试结果测试绿了它就认为任务完成了。缓解办法是在技能里加入环境一致性检查步骤或者在验收标准里区分单元测试通过和集成测试通过两个层级。对于关键技能最好要求代理在接近真实的环境里跑一遍端到端验证。5.3 技能会腐烂需要定期维护代码会腐烂技能也会。项目结构变了、依赖升级了、团队约定改了但技能定义还停留在旧版本代理就会按过时的规矩办事产出过时的代码。这种问题很隐蔽因为代理不会报错它只是忠实地执行了错误的技能。我的做法是把技能纳入代码评审流程任何影响工程约定的变更都要同步检查相关技能是否需要更新。技能目录也应该有 owner有人负责它的健康度。这件事听起来像额外的负担但比起代理悄悄按老规矩写代码、几个月后才发现的代价这点投入完全值得。5.4 别指望技能能替代人的判断最后说一个心态问题。技能体系能大幅提升代理的稳定性和可复现性但它替代不了人的判断。需求是否合理、架构是否恰当、这个功能该不该做这些问题的答案不在技能里在人脑子里。技能解决的是怎么做的一致性问题不是做什么的决策问题。把这两件事混为一谈要么会让代理承担它承担不了的决策责任要么会让人放弃本该由自己做的判断。6. 我对这套体系的实际体会用了一段时间之后我最大的感受是agent-skills这类项目的真正价值不在于让 AI 写代码更快而在于把团队的工程经验变成了可执行的资产。以前那些老员工才知道的规矩——错误怎么处理、测试怎么写、提交前要检查什么——现在被编码进技能里新来的代理以及新来的人都能直接继承。另一个体会是写技能的过程本身就是一次团队规范的梳理。很多约定平时没人说得清一旦要写成代理能执行的步骤模糊地带就暴露出来了。所以哪怕你暂时不用 AI 代理把团队的工程约定整理成这种结构化形式也是有价值的。至于工具选型我的建议是先用起来再优化。不要一上来就追求完美的技能体系先写两三个最痛点的技能跑通闭环感受一下代理在技能约束下的行为变化再决定要不要扩大投入。这套东西的收益是复利式的前期慢后期越用越顺。