1. 从agent-skills这个标题里能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当新同事来管理的工程化方案。关键词里同时出现了skills CLI、test-driven-development、Claude Code这三者放在一起指向一个很明确的问题域——怎么让 AI 编码代理稳定地、可复现地、按团队规范去干活而不是每次靠运气。大多数人用 AI 编码工具的方式是打开对话框把需求描述一遍等它吐代码跑一下报错了再贴回去来回几轮最后勉强能跑。这个过程里真正决定成败的不是模型有多强而是你有没有把怎么做才对这件事显式地交给它。agent-skills想解决的正是这个把技能从模糊的提示词里抽出来变成一个个可复用、可版本管理、可被 CLI 调用的独立单元。它适合谁三类人最该关注。第一类是已经在用 Claude Code 或类似 AI coding agent、但产出质量忽高忽低的开发者第二类是想把 AI 代理接入团队工作流、需要统一规范的 Tech Lead第三类是对skills CLI这种技能即命令模式好奇、想自己搭一套的折腾党。如果你只是偶尔让 AI 补个正则那这套东西对你可能偏重但只要你开始让 AI 参与真实项目它的价值会立刻显现。我先把结论摆在这agent-skills的核心不是让 AI 更聪明而是让 AI 的行为更可控。理解这一点后面所有的设计取舍就都顺了。2. 为什么技能要独立于提示词存在2.1 提示词的天花板在哪里提示词工程流行了两年多大家慢慢发现一个尴尬的事实提示词是易失的。你精心写的一段指令换个会话就没了换个模型版本效果可能打折团队里每个人写的风格还不一样。更麻烦的是提示词很难测试——你没法给一段自然语言写单元测试只能靠感觉这次输出还行。这就是agent-skills这类方案出现的根本动机。它把技能从对话上下文里剥离出来变成一个有名字、有输入输出约定、有版本、能被程序调用的实体。一旦技能变成实体它就能被测试、被复用、被审查、被迭代。这跟当年把散落在脚本里的逻辑抽成函数、抽成库是同一个思路的延续。2.2 技能、提示词、工具三者的边界很多人会把这三个概念混在一起我用一个类比说清楚工具Tool像是手——读写文件、执行命令、调用 API负责能做事。提示词Prompt像是临时的口头交代——这次你告诉它怎么做下次可能就忘了。技能Skill像是岗位 SOP——写下来、存起来、谁来做都按这个来还能定期修订。agent-skills里的技能本质上是封装了提示词 工具调用序列 验收标准的一个可执行单元。它比提示词重比完整的 agent 框架轻。这个定位很关键太重就没人愿意写太轻又解决不了复用问题。2.3 一个技能应该长什么样基于常见实践一个可用的技能通常包含这几块组成作用缺失后果技能名与描述让 agent 知道什么时候该用它agent 不知道何时触发输入约定明确需要哪些参数、上下文每次调用都要重新解释执行步骤具体的操作序列或提示模板行为不可复现验收标准怎么判断这次做对了无法自动判断成败示例一两个正例反例边界情况容易翻车注意最后两项——验收标准和示例这是区分玩具技能和生产技能的分水岭。没有验收标准技能就没法进入自动化流程没有示例agent 在边界情况上就会自由发挥。3. skills CLI 的设计逻辑与实操路径3.1 为什么是 CLI 而不是 GUIskills CLI选择命令行形态这个决定背后有很实际的考量。AI 编码代理本身就是在终端里工作的它执行命令、读文件、跑测试。如果技能管理是个 GUI那 agent 就没法自己调用自己的技能库——这等于把最需要自动化的环节留给了人工。CLI 的另一个好处是可组合。你可以把技能调用嵌进 shell 脚本、CI 流程、git hook 里。比如提交前自动跑一遍代码规范检查技能或者 PR 创建时触发变更影响分析技能。这些在 GUI 里很难做在 CLI 里就是一行命令的事。3.2 技能目录的组织方式一个能长期维护的技能库目录结构不能乱。我见过比较合理的组织方式是这样的skills/ code-review/ skill.md # 技能定义与说明 examples/ # 正反例 tests/ # 验收用例 test-driven-dev/ skill.md examples/ tests/ refactor/ skill.md每个技能一个目录skill.md是入口examples和tests是配套。这种结构的好处是技能可以独立演进——改一个技能不会影响其他技能也方便按目录做权限和审查。提示技能目录一定要纳入版本控制。技能是团队资产它的变更历史比代码更需要被追踪因为技能的行为变化往往比代码更隐蔽。3.3 从零跑通第一个技能假设你要写一个提交前检查技能实操路径大致是这样定义触发条件在skill.md里写清楚当用户准备提交代码、或显式调用该技能时触发。声明输入需要哪些信息——变更的文件列表、项目的 lint 配置、测试命令。写执行步骤先跑 lint再跑相关测试最后汇总结果。定验收标准lint 无 error、测试全绿才算通过。加示例一个通过的例子一个lint 报错被拦截的例子。跑通之后你会发现这个技能的价值不在于它多复杂而在于它把提交前该做什么这件事从人的记忆里搬到了系统里。新人入职不用问我们提交前要跑什么agent 自己就知道。3.4 技能之间的调用与编排单个技能解决单点问题但真实工作流往往是多个技能串联。比如实现一个新功能可能涉及需求拆解技能 → 测试编写技能 → 实现技能 → 代码审查技能。skills CLI如果能支持技能间的调用就能把这条链路固化下来。这里有个坑要提醒技能编排不要做太深。三层以上的嵌套调用调试起来会非常痛苦因为出错时你很难定位是哪一层的哪个技能的问题。我的经验是编排深度控制在两层以内超过就拆成独立的顶层流程。4. 把 test-driven-development 塞进 agent 工作流4.1 为什么 TDD 特别适合 AI 代理TDD 和 AI 编码代理是天生一对原因很直接测试给了 agent 一个明确的、可自动验证的目标。人类写代码时TDD 的收益有时被我心里清楚要什么抵消了但 agent 没有心里清楚这回事它需要一个客观信号告诉它你做对了。agent-skills把test-driven-development作为关键词之一说明它把 TDD 当成一等公民。这个选择很聪明——一旦 agent 的工作流是先写测试再写实现跑测试直到绿它的输出质量会稳定得多因为每一步都有反馈闭环。4.2 红-绿-重构在 agent 场景下的变形经典 TDD 是红-绿-重构三步。放到 agent 场景我建议这样调整红让 agent 先写一个会失败的测试。这一步的关键是测试必须真的能跑起来并失败而不是写个空壳。很多 agent 会偷懒写个永远通过的测试必须用验收标准卡住。绿让 agent 写最小实现让测试通过。强调最小防止它一次性写一大堆没被测试覆盖的代码。重构测试保持绿的前提下优化结构。这一步最容易失控建议加一个重构后必须重跑全部相关测试的硬性要求。4.3 测试质量怎么把关agent 写的测试有个通病测了等于没测。比如断言写得太松或者只测了 happy path。要解决这个可以在技能里加一条验收标准测试必须能在实现被故意改坏时失败。这个检查可以自动化——改坏一行实现跑测试如果还绿说明测试无效。这个技巧我用了很久非常有效。它把测试有没有用这个主观判断变成了一个可执行的验证步骤。4.4 一个 TDD 技能的完整示例下面是一个简化的 TDD 技能定义展示结构# Skill: tdd-implement ## 触发条件 用户要求实现一个新函数/模块且项目已有测试框架。 ## 输入 - 需求描述 - 目标文件路径 - 测试命令 ## 步骤 1. 根据需求写一个失败的测试运行确认失败 2. 写最小实现运行确认通过 3. 在测试保持通过的前提下重构 4. 运行完整测试套件确认无回归 ## 验收标准 - 新测试在实现前失败、实现后通过 - 故意改坏实现时新测试会失败 - 完整测试套件全绿 ## 示例 正例一个字符串处理函数的 TDD 过程 反例测试断言过松导致改坏实现仍通过这个结构看起来简单但它把 TDD 的每个环节都变成了可检查的项。agent 照着做出错的概率会大幅下降。5. 接入 Claude Code 时的配置与踩坑5.1 环境准备里最容易被忽略的一步把agent-skills和 Claude Code 结合使用时很多人卡在第一步技能库的路径没被 agent 正确识别。Claude Code 这类工具通常有个工作目录概念技能库必须放在它能访问到的位置或者在配置里显式声明路径。我踩过的坑是技能写在项目外的目录本地测试没问题一进 CI 就找不到。后来统一改成技能库随项目走放在项目内的固定目录问题就没了。这个决定牺牲了一点跨项目复用的便利但换来的是可移植性值得。5.2 权限与执行边界AI 编码代理能执行终端命令这是它强大的地方也是风险所在。接入技能时必须想清楚哪些技能允许执行什么级别的命令。我的做法是给技能分级级别允许操作典型技能只读读文件、跑测试代码审查、影响分析受限写改指定目录文件实现、重构完全执行任意命令仅限人工确认后大部分技能应该停在受限写这一级。只有极少数需要装依赖、跑迁移的技能才需要更高权限而且这些应该强制人工确认。5.3 模型选择与技能行为的差异同一个技能换个底层模型行为可能差很多。有的模型倾向于多做事会顺手改一堆没要求改的文件有的模型倾向于少做事测试没覆盖的地方就不碰。这不是技能本身的问题是模型特性。实操建议技能定义里明确写不要做什么比只写要做什么更有效。比如只修改目标文件不要动其他文件、不要引入新依赖除非明确要求。这些负向约束能显著减少意外。5.4 常见报错与排查顺序接入过程中常见的几类问题按排查顺序列一下技能不触发先查技能描述里的触发条件是否够明确再看 agent 是否真的读到了技能库。技能触发了但行为不对检查输入约定多半是上下文没传全。验收标准不生效确认验收步骤是否真的被执行有些 agent 会跳过检查环节。CI 里失败本地成功九成是路径或环境变量问题把技能库和配置都纳入版本控制能解决大半。注意排查时优先看 agent 的完整执行日志而不是只看最终结果。行为不对的原因往往藏在中间步骤里。6. 让技能库真正被团队用起来的几个经验6.1 技能不是越多越好刚开始搭技能库时很容易陷入什么都想封装成技能的冲动。结果是技能一大堆没人记得住也没人用。我的经验是从最高频、最容易出错的三个场景开始。通常是代码审查、测试编写、提交前检查。这三个跑顺了团队自然会提出下一个需求。6.2 技能要有负责人技能和代码一样会腐化。项目结构变了、规范改了技能如果不跟着更新就会变成误导 agent 的负资产。所以每个技能最好有个明确的负责人定期 review。没有负责人的技能宁可先删掉也别留着害人。6.3 用真实任务验证技能技能写完不算完必须拿真实任务跑一遍。我习惯的做法是找一个最近刚做完的需求用技能重做一遍对比结果。如果技能产出的质量不如人工说明技能定义有问题如果更好或持平才算可用。这个验证过程比任何单元测试都真实。6.4 记录技能的失败案例技能库最宝贵的部分往往不是成功案例而是失败案例。哪些情况下技能会翻车、翻车时是什么表现、怎么补救——这些信息对后来者价值极高。我建议在技能目录里专门放一个failures.md记录踩过的坑。这比写一堆最佳实践有用得多。7. 我对 agent-skills 这类方案的整体判断用了一段时间这类技能化方案后我最大的体会是AI 编码代理的瓶颈正在从模型能力转移到工程约束。模型已经足够聪明能写出不错的代码真正决定产出质量的是你有没有给它清晰的边界、可验证的目标、可复用的流程。agent-skills的价值就在于它把工程约束这件事做成了可管理的实体。它不追求让 AI 更聪明而是让 AI 的行为更可预测。这个方向我认为是对的因为可预测性才是把 AI 代理真正纳入生产流程的前提。如果你现在还在靠每次重新描述需求来用 AI 编码我建议你从一个小技能开始试试。不用一上来就搭完整体系先把你最常重复的那段交代写成技能跑几次感受一下差别。大概率你会回不去了——因为一旦体验过agent 自己知道该怎么做的顺畅就很难再忍受每次从零解释的繁琐。最后分享一个小技巧技能定义里的示例部分反例比正例更重要。正例告诉 agent应该长什么样反例告诉它什么情况算错。而 agent 翻车绝大多数时候是栽在反例覆盖的那些边界情况上。