1. 从“agent-skills”说起为什么它值得你花时间第一次看到agent-skills这个项目名我的直觉是这大概率是一个围绕 AI coding agent 能力扩展的工程化尝试。翻了一圈社区讨论和仓库结构之后确认了这个判断——它本质上是一套面向 AI 编程代理的“技能包”集合通过一个叫skills CLI的命令行工具来管理和加载不同的技能模块让 Claude Code 这类 AI coding agent 能够按需获得特定领域的操作能力。说白了它解决的是一个很实际的问题你手头有一个通用的 AI 编程助手但它对某些特定任务的处理方式不够专业——比如写测试的时候不遵循 TDD 流程比如处理某些框架的代码时总是用错 API比如执行终端命令时不够谨慎。agent-skills的思路是把这些“专业能力”拆成独立的技能模块用的时候加载进来不用的时候不占上下文。这套东西适合谁三类人最值得关注一是已经在日常开发中重度使用 Claude Code 的工程师二是正在搭建自己 AI 辅助开发工作流的团队技术负责人三是对 AI coding agent 底层机制好奇、想自己写技能模块的开发者。不管你用的是 Claude Code 的哪个版本不管你是 Mac 还是 Ubuntu只要你在用 AI 帮你写代码这套技能机制都值得了解。我花了大概两周时间把agent-skills的仓库结构、CLI 实现和几个核心技能模块的源码过了一遍也在自己的项目里实际跑了一段时间。下面把我理解到的设计思路、实操要点和踩过的坑按我自己的逻辑重新组织一遍。2. 整体设计思路为什么是“技能包”而不是“大而全”2.1 核心问题通用 agent 的“样样通、样样松”Claude Code 这类 AI coding agent 的默认行为模式是“通用助手”——你给它一个任务它根据训练时学到的通用模式来回应。这在大多数场景下够用但一旦涉及有明确流程规范的任务问题就暴露了。举个我自己的例子。我让 Claude Code 帮我给一个 Python 项目补单元测试它的默认行为是读代码、理解逻辑、写测试、跑一遍看能不能过。这个流程本身没问题但它不会主动遵循 test-driven-development 的“先写失败测试、再写实现、再重构”的节奏。它倾向于一次性把测试和实现都写完然后跑一遍确认通过就结束了。这导致测试的“驱动”作用完全丧失——测试变成了事后验证而不是设计工具。agent-skills的设计出发点就是解决这类问题。它不试图让一个 agent 变得全能而是把“专业能力”拆成独立的、可组合的技能模块。每个技能模块定义了一套特定的行为规范、操作流程和约束条件agent 加载这个技能后就会按照技能定义的流程来执行任务。这个设计思路和 Unix 的“小工具组合”哲学很像每个工具只做一件事但做好复杂任务通过组合多个工具来完成。agent-skills里的每个 skill 就是一个“小工具”skills CLI就是组合这些工具的那根管道。2.2 技能模块的组成结构我拆了几个技能模块的源码结构上基本一致。一个典型的 skill 包含以下几个部分元数据定义技能名称、版本、适用场景描述、依赖关系。这部分决定了 CLI 在加载技能时如何解析和校验。行为规范用自然语言或结构化格式描述的“这个技能被激活时agent 应该怎么做”。比如 TDD 技能会明确规定“必须先写测试、测试必须失败、实现必须最小化”。操作模板一些预定义的命令模板、代码片段模板或文件结构模板。agent 在执行任务时可以直接引用这些模板减少“自由发挥”带来的不确定性。约束条件明确列出“不能做什么”。比如“不能跳过测试直接写实现”、“不能在测试通过前重构”。这种结构的好处是技能的行为是可预测的。你加载了 TDD 技能agent 就会严格按照 TDD 的流程走不会因为“觉得这样更快”而跳过步骤。对于团队协作来说这意味着不同人用同一个技能得到的结果是一致的。2.3 为什么用 CLI 来管理skills CLI的存在意义在于“按需加载”。你不可能把所有技能都塞进 agent 的上下文里——那样既浪费 token又会造成技能之间的冲突。CLI 让你在需要的时候加载特定技能任务完成后卸载保持 agent 的上下文干净。我实测下来CLI 的核心命令大概有这么几类# 查看可用技能列表 skills list # 加载某个技能 skills load test-driven-development # 查看当前已加载的技能 skills status # 卸载技能 skills unload test-driven-development # 查看技能详情 skills info test-driven-development这套命令设计很直观和 npm、pip 这类包管理器的使用习惯一致上手成本很低。CLI 本身是用 Node.js 写的安装方式也很直接npm install -g agent-skills-cli安装完成后skills命令就可以在终端里直接使用了。这里有个细节值得注意CLI 默认会从官方仓库拉取技能列表但你可以通过配置指向自己的私有仓库。这对团队内部维护自己的技能库很有用。3. 核心技能模块拆解以 test-driven-development 为例3.1 TDD 技能的行为规范test-driven-development是agent-skills里最核心也最成熟的一个技能模块。它的行为规范定义得非常细致我把它拆成几个关键点来说。第一强制“红-绿-重构”循环。技能激活后agent 收到任何功能开发任务时必须先写一个会失败的测试。这个测试必须实际运行并确认失败然后才能写实现代码。实现代码必须是最小化的——只让当前测试通过不多写一行。测试通过后才允许重构。第二测试粒度控制。技能规范里明确要求“一次只处理一个测试用例”。也就是说agent 不能一次性写五个测试然后一起跑必须写一个、跑一个、通过一个、再写下一个。这个约束看起来有点死板但实际用下来效果很好——它强迫 agent 把注意力集中在当前这一个行为上避免“批量写测试”时出现的逻辑跳跃。第三禁止“测试后补”。技能激活状态下agent 不允许先写实现再补测试。如果它试图这么做技能规范会触发一个检查点要求它回退到测试优先的流程。这个约束是通过在 agent 的提示词里嵌入检查逻辑来实现的不是硬性的代码拦截但实测下来 agent 会遵守。3.2 实操中的加载与使用在实际项目里用这个技能流程大概是这样的。假设我要给一个 Python 函数calculate_discount添加功能。首先加载技能skills load test-driven-development然后给 Claude Code 下指令“给calculate_discount函数添加一个功能当订单金额超过 1000 时折扣率额外增加 5%。”技能激活后agent 的第一反应不是去改calculate_discount的实现而是先写测试。它会创建一个测试文件写一个测试用例def test_calculate_discount_bulk_order(): # 订单金额 1500基础折扣 10%额外 5%总折扣 15% result calculate_discount(1500, 0.10) assert result 0.15然后运行测试确认失败因为当前实现还没有这个逻辑。接着修改实现让测试通过。最后检查是否需要重构。整个过程 agent 会按照技能规范一步步执行每一步都有明确的输出。我实测下来这个流程比默认模式慢大概 20%-30%但产出的测试质量明显更高——测试覆盖了边界条件测试和实现之间的对应关系清晰后续修改时不容易破坏已有行为。3.3 技能之间的组合使用agent-skills支持同时加载多个技能。我试过把test-driven-development和一个叫code-review-checklist的技能一起加载。效果是agent 在写代码时会遵循 TDD 流程在完成一个功能后会自动按照 code review 清单检查自己的代码。这种组合使用的方式很灵活。你可以根据任务类型组合不同的技能——写新功能时加载 TDD 代码规范技能修 bug 时加载调试技能 TDD重构时加载重构技能 代码审查技能。不过要注意技能之间的冲突。我遇到过两个技能对同一个操作给出不同规范的情况——比如一个技能要求“先写测试”另一个技能要求“先分析性能瓶颈”。这种情况下 agent 会陷入犹豫输出质量下降。解决办法是加载技能前先看技能描述避免加载行为规范重叠的技能。4. 实操过程从零搭建一个自定义技能4.1 技能目录结构自己写一个技能模块需要遵循agent-skills的目录规范。一个标准的技能目录结构是这样的my-skill/ ├── skill.json # 技能元数据 ├── behavior.md # 行为规范描述 ├── templates/ # 操作模板 │ ├── test-template.py │ └── impl-template.py └── constraints.md # 约束条件skill.json是入口文件定义了技能的基本信息{ name: my-skill, version: 1.0.0, description: 一个自定义技能示例, author: your-name, dependencies: [], tags: [python, testing] }behavior.md是核心文件用自然语言描述技能激活后 agent 应该遵循的行为规范。这个文件的写法很关键——写得太模糊agent 会自由发挥写得太死板agent 会变得机械。我的经验是用“必须”、“禁止”、“建议”这类明确的词来区分约束级别同时给出具体的操作示例。4.2 行为规范的编写技巧写behavior.md的时候我踩过几个坑这里分享一下。第一个坑是“规范太抽象”。我一开始写的是“agent 应该写出高质量的代码”。这个规范等于没写——什么叫“高质量”agent 无法判断。后来改成“agent 写出的函数必须满足单一职责、参数不超过 4 个、有类型注解、有 docstring”效果立刻不一样了。第二个坑是“规范之间矛盾”。我在一个技能里同时写了“优先使用标准库”和“优先使用性能最优方案”结果 agent 在遇到标准库性能不是最优的情况时就会犹豫。后来我把这类规范改成有优先级的列表“性能优先但在性能差异小于 20% 时优先使用标准库”。第三个坑是“缺少示例”。纯文字规范 agent 理解起来容易有偏差加上具体的代码示例后agent 的行为会准确很多。比如在 TDD 技能里我加了一段“好的测试示例”和“坏的测试示例”的对比agent 写出来的测试质量明显提升。4.3 本地测试与调试技能写完后需要本地测试。skills CLI提供了本地加载的方式skills load ./my-skill --local加载后给 agent 下一个测试任务观察它的行为是否符合技能规范。如果不符合修改behavior.md后重新加载即可不需要重启 agent。调试过程中skills status命令很有用——它会显示当前加载的技能列表和每个技能的激活状态。如果技能没有正确加载这个命令能帮你快速定位问题。我一般会准备一组“测试任务”来验证技能效果一个简单任务、一个中等复杂度任务、一个边界情况任务。跑完这三个任务基本能判断技能规范是否清晰、约束是否合理。5. 常见问题与排查技巧实录5.1 技能加载失败最常见的问题是技能加载失败报错信息通常是“skill not found”或“invalid skill format”。排查思路如下问题现象可能原因解决方法skill not found技能名称拼写错误用skills list确认可用技能名称invalid skill formatskill.json 格式错误用 JSON 校验工具检查文件dependency missing依赖的技能未安装先安装依赖技能version conflict技能版本不兼容检查技能要求的 CLI 版本我遇到过一次“invalid skill format”排查了半天发现是skill.json里多了一个逗号。JSON 格式对逗号很敏感写的时候要小心。5.2 技能激活后 agent 行为异常有时候技能加载成功了但 agent 的行为不符合预期。可能的原因有几个一是技能规范太模糊agent 理解有偏差。解决办法是给规范加上具体的操作示例和反例。二是技能之间冲突。检查当前加载的技能列表看是否有行为规范重叠的技能。如果有卸载其中一个再试。三是 agent 的上下文被其他内容干扰。如果当前对话历史很长agent 可能会忽略技能规范。解决办法是开一个新对话重新加载技能。5.3 性能与 token 消耗加载技能会增加 agent 的 token 消耗因为技能规范本身要占用上下文空间。我实测下来一个中等复杂度的技能大概占用 500-1000 token。如果同时加载 3-4 个技能token 消耗会增加 2000-4000。这个开销在大多数场景下可以接受但如果你在做 token 敏感的操作比如批量处理大量文件建议只加载必要的技能任务完成后及时卸载。另外技能规范里的示例代码也会占用 token。我的经验是示例代码控制在 20 行以内只保留最核心的部分。完整的示例可以放在templates/目录里agent 需要时再读取。5.4 技能更新与版本管理agent-skills的技能是独立版本化的。更新技能用skills update test-driven-development更新前建议先看 changelog确认行为规范有没有变化。我有一次更新 TDD 技能后发现它新增了一个“测试覆盖率检查”的约束导致 agent 在写测试时会额外花时间检查覆盖率流程变慢了。后来我回退到了旧版本。版本回退用skills install test-driven-development1.2.0指定版本号即可。建议在团队内部维护一个“技能版本锁定文件”记录每个项目使用的技能版本避免不同人用不同版本导致行为不一致。6. 技能开发的进阶思路6.1 技能与项目上下文的结合基础的技能模块是通用的但实际项目中不同项目有不同的规范。agent-skills支持在技能里引用项目上下文——比如读取项目根目录的.agent-skills.json文件根据项目配置调整技能行为。这个机制很实用。比如 TDD 技能默认要求“先写测试”但有些遗留项目根本没有测试框架。你可以在.agent-skills.json里配置tdd_mode: advisory让技能变成“建议先写测试”而不是“强制先写测试”。6.2 技能的市场与共享agent-skills有一个社区技能仓库你可以把自己写的技能发布上去。发布流程和 npm 包发布类似skills publish ./my-skill发布前需要确保技能规范清晰、有完整的文档和示例。我发布过一个“Django 项目代码规范”的技能收获了不少反馈也根据反馈迭代了几个版本。社区技能的 quality 参差不齐使用前建议先看技能仓库的 star 数和 issue 情况。我一般只使用 star 数超过 50 且最近三个月有更新的技能。6.3 技能组合的自动化如果你经常使用固定的技能组合可以写一个配置文件来管理{ presets: { new-feature: [test-driven-development, code-review-checklist], bug-fix: [debugging, test-driven-development], refactor: [refactoring, code-review-checklist] } }然后通过skills load --preset new-feature一键加载。这个功能在 CLI 的较新版本里支持用起来很方便。7. 我个人的使用体会用了这段时间最大的感受是agent-skills的价值不在于“让 agent 更聪明”而在于“让 agent 更可控”。默认的 AI coding agent 像一个聪明但随性的助手你给它一个任务它按自己的理解去做结果好坏取决于它的“心情”。加载技能后agent 的行为变得可预测、可复现这对工程实践来说比“偶尔惊艳”重要得多。另一个体会是写技能规范的过程其实是在梳理自己的工程实践。我在写 TDD 技能规范的时候被迫把自己“觉得理所当然”的测试习惯拆解成明确的步骤和约束这个过程本身就很有价值。后来我把这些规范直接拿给团队新人看作为代码规范的补充材料效果也不错。最后分享一个小技巧技能规范里的“禁止”条款比“必须”条款更有效。我试过在技能里写“必须写测试”agent 有时候会敷衍了事但写“禁止在没有失败测试的情况下写实现”agent 就会严格执行。这可能是因为“禁止”给了 agent 一个明确的检查点而“必须”只是一个方向性要求。