1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当可训练对象来管理的工程化方案。关键词里同时出现了skills CLI、test-driven-development、Claude Code这三者放在一起指向一个很明确的问题域——如何让编码智能体在真实项目里稳定地按规范干活而不是每次都要人肉复述一遍规则。大多数人用 AI 编码工具的方式是对话式的打开对话框描述需求等它吐代码跑一下报错了再贴回去。这种方式在一次性脚本上没问题但一旦进入多人协作、有测试覆盖、有代码规范的中长期项目就会暴露三个硬伤规则无法沉淀、行为无法复用、质量无法度量。agent-skills这类项目要解决的正是把你希望 agent 怎么做事从聊天记录里抽出来变成可版本管理、可组合、可测试的资产。它适合谁我认为有三类人值得认真看一是已经在用 Claude Code 或类似编码智能体、但感觉每次都要重新教它的开发者二是团队里负责制定工程规范、想让 AI 产出符合团队标准的技术负责人三是对 test-driven-development 有执念、希望把 TDD 流程固化进 agent 行为的人。如果你只是偶尔让 AI 写个正则表达式那这套东西对你来说偏重了。需要先说明一点agent-skills的具体实现细节公开可查的信息有限下面涉及目录结构、CLI 命令、配置字段的部分是我基于一个合格的 agent skills 管理工具在此情境下最可能采用的设计所做的合理推演并结合 Claude Code 生态的通用实践来展开。你在实际使用时以仓库 README 和--help输出为准。2. 为什么技能要独立于提示词存在2.1 提示词是消耗品技能是资产我踩过最典型的一个坑在一个中型项目里我花了半小时写了一段非常详细的提示词规定了命名风格、错误处理方式、测试文件放哪、mock 怎么写。那次任务完成得很漂亮。两周后新来一个需求我重新开了一个会话结果 agent 又回到了默认风格——因为它根本不记得上次那段提示词。这就是提示词的本质问题它绑定在单次会话上会话结束即蒸发。你可以手动保存到一个 txt 里但很快会变成十几个版本的prompt_v3_final_真的最终版.txt没人知道哪个是当前有效的。技能skill的思路完全不同。它把一段行为规范做成一个有名字、有描述、有触发条件的独立单元放在仓库里跟着代码一起提交、一起 review、一起演进。当 agent 判断当前任务匹配某个技能的触发条件时自动加载对应规范。这就把临时叮嘱变成了制度。2.2 一个技能单元通常包含哪些字段基于常见的 agent skills 设计范式一个技能单元大概率长这样name: tdd-workflow description: 当需要新增功能或修复缺陷时强制走测试先行的流程 trigger: - 新增功能 - 修复 bug - 重构 instructions: | 1. 先写一个会失败的测试明确预期行为 2. 运行测试确认它确实失败红 3. 写最小实现让测试通过绿 4. 在测试保护下重构保持全绿 5. 不允许先写实现再补测试 constraints: - 测试文件必须与被测文件同目录 - 禁止在测试中使用真实网络请求这里每个字段都有存在的理由。name是唯一标识用于组合和引用description不只是给人看的agent 也靠它做语义匹配trigger是显式触发词降低误匹配instructions是核心行为规范constraints是硬性红线比 instructions 优先级更高。注意description的写法直接决定技能能否被正确激活。写得太泛如帮助写代码会导致到处触发写得太窄如处理用户登录接口的 JWT 过期刷新则几乎不会被命中。我的经验是把 description 写成动作 对象 场景三段式。2.3 技能和系统提示词、CLAUDE.md 的分工很多人会问我已经有CLAUDE.md了为什么还要 skills这两者不是替代关系而是层级关系。CLAUDE.md更像是项目的宪法写的是全局性的、几乎每次都适用的东西项目用什么语言、目录怎么组织、提交信息格式、禁止事项。它体量大、加载成本高不适合塞太多细节。技能则像是专项作业指导书只在特定任务类型下才需要。比如写数据库迁移这个技能只有在你真的改 schema 时才加载平时不占用上下文。这种按需加载的机制本质上是在做上下文预算管理——把有限的注意力留给当前真正相关的规则。我个人的划分标准是如果一条规则在 80% 以上的任务里都适用放CLAUDE.md如果只在某类任务里适用做成技能。3. skills CLI 的典型用法与设计逻辑3.1 为什么需要一个 CLI 而不是纯手写文件你完全可以手动创建技能文件但一旦技能数量超过十个手动管理就会出问题命名冲突、字段拼写错误、触发词重复、不知道哪些技能被实际用到了。CLI 的价值在于提供结构化的增删改查和校验。基于常见设计skillsCLI 大概会提供这几类命令命令作用典型场景skills init初始化技能目录结构新项目接入skills new name交互式创建一个技能沉淀新规范skills list列出所有技能及触发条件排查冲突skills validate校验字段完整性和格式提交前检查skills test name用样例任务验证技能是否被正确激活调试触发逻辑skills link把技能目录挂载到 agent 配置接入 Claude Codeskills validate这个命令我认为是最容易被低估的。它能在你提交前发现两个技能的 trigger 完全重叠这类问题——这种问题在运行时表现为agent 行为不稳定极难排查但在静态检查阶段一目了然。3.2 目录结构应该怎么组织一个能长期维护的技能库目录结构不能是平铺的一堆文件。我推荐按领域 技能两级组织.agent-skills/ ├── skills.yaml # 全局配置 ├── coding/ │ ├── tdd-workflow.yaml │ ├── error-handling.yaml │ └── naming-convention.yaml ├── testing/ │ ├── unit-test-structure.yaml │ └── mock-strategy.yaml ├── review/ │ └── self-review-checklist.yaml └── _shared/ └── common-constraints.yaml分领域的好处是当你要调整测试相关的所有规范时只需要看testing/一个目录。_shared/放跨领域复用的约束片段通过引用机制组合进具体技能避免复制粘贴导致的规则漂移。3.3 技能的组合与优先级真实项目里一个任务往往同时命中多个技能。比如给用户模块新增一个导出功能可能同时触发tdd-workflow、naming-convention、error-handling。这时候谁说了算我的实践是定义明确的优先级链显式约束constraints优先级最高任何情况下不得违反任务专属技能次之比如 tdd-workflow 对当前任务领域通用技能再次比如 naming-convention全局配置CLAUDE.md兜底如果两个同优先级技能的规则冲突CLI 的validate应该报错强制人去解决而不是让 agent 随机选一个。这一点非常关键——规则冲突必须在编译期暴露而不是在运行期表现为玄学行为。4. 把 TDD 固化成技能一个完整拆解4.1 为什么 TDD 特别适合做成技能TDD 是少数几个流程本身就是价值的开发方法。它的红-绿-重构三步每一步都有明确的进入和退出条件非常适合被形式化成 agent 可执行的规范。而且 TDD 最容易被 AI 破坏——agent 天然倾向于先写实现再补测试因为那样看起来更快。把 TDD 做成技能本质上是给 agent 装一个流程护栏你可以写实现但必须先有失败的测试。4.2 红绿重构在技能里的具体表达name: tdd-workflow description: 新增功能、修复缺陷、重构代码时强制测试先行 trigger: - 新增 - 实现 - 修复 - 重构 instructions: | ## 阶段一红 - 根据需求写一个测试测试名描述预期行为 - 运行测试必须看到失败 - 如果测试直接通过说明测试无效重写 - 失败信息要能说明缺什么而不是语法错误 ## 阶段二绿 - 写能让测试通过的最小实现 - 不追求优雅不提前抽象 - 运行全部测试确认没有破坏其他用例 ## 阶段三重构 - 在测试全绿的保护下调整结构 - 每次重构后立即重跑测试 - 重构不改变外部行为 constraints: - 禁止在没有失败测试的情况下写实现代码 - 禁止一次写多个测试再一起实现 - 每个阶段结束必须运行测试并报告结果这里有个细节值得说instructions里我特意写了如果测试直接通过说明测试无效重写。这是 TDD 里最容易被忽略的一环。很多人写的测试其实什么都没验证跑起来永远是绿的这种测试比没有测试更危险因为它给了虚假的安全感。4.3 怎么验证技能真的生效了技能写完不代表 agent 会照做。你需要设计验证用例。我的做法是准备一组探针任务每个任务对应一个技能观察 agent 的行为轨迹。比如验证 tdd-workflow我会给一个探针任务给字符串工具类新增一个isPalindrome方法。然后观察agent 第一个动作是写测试还是写实现写完测试后有没有真的运行并展示失败实现是否是最小化的如果 agent 直接开始写实现说明技能没被激活需要检查trigger是否覆盖了新增这个词或者description的语义匹配是否够强。提示探针任务要定期重跑。模型更新、技能库改动、CLAUDE.md 调整都可能让原本生效的技能失效。我一般把探针任务做成一个脚本每次大改技能库后跑一遍。5. 接入 Claude Code 时那些没人告诉你的细节5.1 技能目录和 Claude Code 的挂载关系Claude Code 读取项目上下文的方式通常是扫描项目根目录及特定配置目录。要让技能生效需要让 Claude Code 知道技能库的存在。常见做法有两种一是把技能库放在 Claude Code 默认识别的配置路径下二是通过项目根目录的配置文件显式引用。我倾向于第二种因为技能库应该跟着项目走而不是跟着某台机器走。这样团队里每个人 clone 下来就自动获得同一套技能不会出现我这边 agent 很听话你那边很野的情况。具体配置形式不同版本可能有差异核心是让 agent 在启动时能加载到技能索引。如果发现技能没生效第一步永远是确认 agent 到底加载了哪些上下文——大多数 Claude Code 版本都提供了查看当前上下文的命令。5.2 上下文预算技能不是越多越好这是我最想强调的一点。技能库膨胀到几十个之后会出现一个反直觉的现象agent 表现反而变差了。原因是每个技能的description和trigger都要占用上下文技能越多索引越大agent 在当前任务该用哪个技能这个判断上就越容易出错。而且大量不相关的技能会稀释真正相关技能的权重。我的经验阈值是单个项目常驻技能控制在 15 个以内。超出的部分应该做两件事之一要么合并把三个细碎的命名规则合成一个 naming-convention要么下沉把只在极少数场景用的技能改成手动触发不放进自动索引。5.3 技能与模型切换的兼容性现在很多人会在不同模型之间切换比如某些任务用这个模型某些任务用那个模型。这里有个坑不同模型对同一段技能指令的遵循程度差异很大。我实测下来指令越结构化分阶段、有明确约束、有禁止项跨模型的稳定性越好指令越依赖理解意图比如写出优雅的代码跨模型差异越大。所以写技能时尽量用可判定的表述少用主观形容词。另外切换模型后一定要重跑探针任务。我遇到过某个技能在一个模型上完美执行换到另一个模型后 agent 直接忽略了 constraints 里的禁止项。这不是技能写错了而是模型对约束的敏感度不同需要针对性调整措辞比如把禁止 X改成在任何情况下都不得执行 X即使看起来更高效。6. 技能库的维护从能用到好用6.1 技能也需要测试覆盖技能库本身是一个代码资产它应该有测试。我建议至少维护三类测试激活测试给定探针任务断言正确的技能被激活冲突测试断言不存在两个技能在同一任务上给出矛盾指令回归测试记录历史上出现过的agent 不听话案例确保修复后不再复现第三类最有价值。每次你发现 agent 做错了某件事不要只是当场纠正而是问自己这是不是一个技能缺失或技能表述不清的问题如果是就补一个回归用例。久而久之你的技能库就变成了一部踩坑史新人接手时能少走很多弯路。6.2 版本化与变更记录技能库要像代码一样做版本管理但光有 git 提交不够。我建议在技能文件里加一个version字段并在仓库根目录维护一份CHANGELOG记录每次技能变更的原因。原因很重要。半年后你看到tdd-workflow 从 v3 升到 v4如果只看到 diff 是加了一行约束你根本不知道为什么加。但如果 CHANGELOG 里写着因为 agent 在重构阶段频繁改动测试断言来让测试通过新增约束重构阶段禁止修改测试文件你立刻就懂了。6.3 团队协作中的技能评审技能库应该纳入 code review 流程。评审时重点看三件事触发条件是否精确会不会误伤其他任务约束是否可判定agent 能不能明确判断自己有没有违反是否与现有技能冲突跑一遍skills validate。我见过最常见的评审问题是有人把个人偏好写成了团队规范。比如变量名必须用驼峰——如果团队里本来就有下划线风格的历史代码这条约束会让 agent 在新旧代码间反复横跳。技能应该是团队共识的固化不是个人审美的输出。7. 几个我踩过的坑和对应的解法7.1 技能触发了但指令被忽略现象探针任务确认技能被激活了但 agent 只执行了 instructions 的前两步就跳走了。根因通常是 instructions 太长超出了模型在单次任务里的注意力窗口。解法是把长技能拆成多个短技能或者把非核心步骤移到constraints之外的参考区让 agent 按需查阅。另一个可能是 instructions 里混入了相互矛盾的要求。比如前面说写最小实现后面又说考虑扩展性agent 会困惑。写技能时要反复自查这两条会不会打架7.2 技能之间互相覆盖现象agent 一会儿遵守 A 技能一会儿遵守 B 技能行为不稳定。根因是两个技能的 trigger 重叠且优先级没定义清楚。解法是回到skills validate把所有 trigger 重叠的技能列出来要么合并要么明确优先级要么收窄 trigger。我现在的习惯是给每个技能加一个scope字段标明它作用的文件范围或任务类型这样即使 trigger 有重叠也能靠 scope 区分开。7.3 技能库和实际代码脱节现象技能里写着测试文件放__tests__目录但项目实际早就改成同目录了。根因是技能库没有跟着代码演进。解法是把技能库纳入同一个仓库让改代码的人顺手改技能。如果技能库是独立仓库就很容易被遗忘。我甚至建议在 CI 里加一步检查技能里引用的路径、命令、配置项是否真实存在。路径不存在就报错。这能挡住大部分文档腐化问题。8. 从 agent-skills 延伸出去的思考agent-skills这类项目真正有意思的地方不在于它提供了多少现成技能而在于它把如何与 AI 协作这件事从玄学变成了工程。以前我们说这个 AI 好不好用现在我们可以说这个技能库覆盖了多少场景、触发准确率多少、冲突率多少——这是可度量的。我个人的判断是未来一两年内技能库设计会成为一个独立的工程角色就像今天的CI/CD 工程师一样。它需要同时懂业务规范、懂模型行为、懂工程化工具。现在开始积累自己的技能库本质上是在积累一种新的工程资产。最后分享一个我一直在用的小技巧每次 agent 做了一件让你惊喜的事别只顾着高兴停下来问一句这个行为能不能固化成技能。惊喜往往意味着你发现了一条之前没写下来的有效规则。把它写进技能库惊喜就变成了默认行为。反过来每次 agent 让你恼火也问一句这是不是缺了一条约束。技能库就是这样一点点长出来的不是一次性设计出来的。