1. 从agent-skills说起为什么技能包正在成为AI编码代理的分水岭第一次看到agent-skills这个项目名的时候我脑子里蹦出来的不是某个具体工具而是一个很现实的问题为什么同样是用 Claude Code 或者别的 AI coding agent有的人能让它三分钟改完一个模块还顺手补上测试有的人折腾半小时它还在原地打转答案往往不在模型本身而在技能skills的组织方式上。agent-skills本质上是一套面向 AI 编码代理的技能定义与分发机制配套一个skills CLI工具。它要解决的问题很朴素把怎么让代理干某件事这件事从散落在各个 prompt 片段、聊天记录、个人笔记里的经验沉淀成可复用、可版本管理、可被代理自动加载的结构化技能包。你可以把它理解成给 AI 代理准备的标准作业程序库——每个技能就是一份说明书告诉代理在特定场景下该读哪些文件、按什么顺序执行、遵循什么约束、产出什么结果。这套东西适合谁三类人最该关注。第一类是重度使用 Claude Code 做日常开发的工程师尤其是那些已经过了哇它能写代码的新鲜期、开始被它怎么又跑偏了折磨的人。第二类是团队里负责工程效能的人需要把个人的 prompt 技巧变成团队资产。第三类是对 test-driven-development 有执念的开发者因为agent-skills里最典型的技能范式之一就是把 TDD 流程固化下来让代理先写测试再写实现而不是反过来。我自己的体感是AI 编码代理的能力上限其实早就够用了真正卡脖子的是上下文供给和流程约束。模型不知道你的项目约定、不知道你偏好哪种测试框架、不知道哪些目录不能碰它就只能靠猜。agent-skills的价值就在于把这些隐性知识显性化让代理每次开工前先加载对应的技能而不是每次都从零开始解释。下面我会从设计思路、核心机制、实操落地到踩坑排查把这套东西拆开讲透。2. 技能包的整体设计思路与方案选型2.1 为什么不是写更长的 prompt而是拆成技能很多人第一反应是我直接把要求写进CLAUDE.md或者系统提示里不就行了我一开始也这么干结果文件越写越长最后变成一个两千行的万能说明书代理反而抓不住重点。问题出在注意力稀释——当所有规则平铺在一起模型很难判断当前任务该优先遵守哪几条。agent-skills的思路是按场景切分。一个技能只负责一类任务比如新增一个 API 端点、修复一个失败的测试、重构一个函数并保持行为不变。每个技能内部包含触发条件、执行步骤、约束清单和验收标准。代理在处理任务时先匹配技能再加载对应内容。这样做的好处是上下文精准模型不用在一堆无关规则里做取舍。从工程角度看这其实是把软件工程里的模块化思想搬到了 prompt 工程上。就像你不会把所有函数塞进一个文件你也不该把所有指令塞进一个 prompt。技能包支持版本管理、支持复用、支持组合这些都是单一长 prompt 做不到的。2.2 技能目录结构一个技能到底长什么样基于常见实践一个典型的技能目录大概是这样组织的skills/ test-driven-development/ SKILL.md # 技能主文件描述触发条件和流程 references/ # 参考资料按需加载 testing-patterns.md scripts/ # 可执行脚本代理可调用 run-tests.sh api-endpoint/ SKILL.md templates/ handler.template核心是SKILL.md它通常包含几块内容元信息技能名、适用场景、关键词、前置检查开工前要确认什么、执行步骤有序的操作清单、约束不能做什么、验收怎么算完成。references/和scripts/是可选增强前者用于存放按需读取的长文档后者用于把确定性操作交给脚本而不是让模型自由发挥。注意技能文件不要写成散文。代理读的是指令不是文章。每一条尽量是祈使句能判定真假能对应到具体动作。2.3 与 Claude Code 等代理的集成方式agent-skills配套的skills CLI主要干两件事安装技能和注入技能。安装就是把技能包放到代理能读到的目录注入则是通过配置让代理在启动时知道这里有一批技能可用。以 Claude Code 为例常见的做法是在项目根目录放一个技能目录然后在CLAUDE.md里用一小段说明告诉代理当任务匹配某个技能时先读取对应的SKILL.md再动手。 这样代理不会一次性把所有技能全读进来而是按需加载既省上下文又提准确率。CLI 工具的价值在于把复制文件、改配置、校验格式这些重复劳动自动化避免手工操作出错。这里有个选型上的取舍值得说是让代理自动匹配技能还是人工显式指定我的经验是两者都要。自动匹配适合高频、边界清晰的场景人工指定适合复杂、容易误判的任务。CLI 通常两种模式都支持你可以在命令里直接点名某个技能也可以让代理自己判断。3. 核心机制拆解技能如何被加载、匹配与执行3.1 技能匹配代理怎么知道该用哪个技能匹配机制是整套体系里最容易被低估的一环。代理拿到一个任务后要先判断这属于哪类工作。常见做法是给每个技能定义一组触发关键词和场景描述代理用这些信息做语义匹配。比如修复失败的测试这个技能触发词可能包括test failed、failing test、red场景描述是当测试套件存在失败用例且需要定位并修复时。匹配的准确性直接决定后续体验。我踩过的坑是触发词写得太宽泛结果代理把重构任务误判成修 bug加载了错误的技能越做越偏。后来我的做法是给技能加负向条件明确写出不适用于什么情况。比如重构技能里写清楚如果任务涉及行为变更不要使用本技能。这一条小小的补充误匹配率下降非常明显。3.2 上下文注入按需加载而不是全量塞入技能加载的核心原则是最小必要上下文。代理不需要在开工前读完所有技能只需要读当前任务匹配的那一个以及它引用的参考资料。SKILL.md里可以用类似需要时读取references/xxx.md的指令把长文档的加载推迟到真正需要的时候。这样做有个直接好处token 成本可控。我做过粗略对比全量加载十个技能和按需加载一个技能单次任务的输入 token 差距能到五到八倍。对于高频使用代理的团队这个差距累积起来相当可观。而且上下文越干净模型跑偏的概率越低这是一举两得的事。3.3 执行约束把不要做什么写清楚大部分 prompt 都在讲要做什么但实际使用中代理闯祸往往是因为做了不该做的。agent-skills的约束清单就是专门治这个的。常见的约束包括不要修改指定目录外的文件、不要删除已有测试、不要引入新的第三方依赖、不要改动公共接口签名。这些约束要写得可判定。注意代码质量这种话没用代理没法判断自己有没有违反。不要引入新的依赖就很好代理能明确知道自己有没有踩线。我在实际项目里会把约束分成硬约束和软约束硬约束违反即失败软约束违反需要说明理由。这种分级让代理的行为更可控。3.4 验收标准怎么判断技能执行成功没有验收标准的技能是不完整的。代理做完一件事得有个客观标准判断做完了没有、做对了没有。对于 TDD 类技能验收标准很明确所有测试通过、新增测试覆盖了新行为、没有跳过或删除测试。对于重构类技能验收标准是原有测试全部通过、公共接口未变、代码复杂度下降。验收标准最好能自动执行。这就是scripts/目录的用武之地——把跑测试、跑 lint、跑类型检查写成脚本代理执行脚本拿到结果而不是自己感觉做完了。我见过太多代理自信满满地说已完成结果测试根本没跑。把验收脚本化能挡掉一大半这种问题。4. 实操落地从零搭一套可用的技能包4.1 环境准备与 skills CLI 安装先确认你的代理环境能正常工作。以 Claude Code 为例安装方式根据平台不同略有差异Mac 和 Ubuntu 上通常通过包管理器或官方脚本安装VS Code 用户可以直接装对应插件。安装完成后用claude --version之类的命令确认可用。这一步的细节官方文档写得很清楚我不赘述重点说技能相关的准备。skills CLI的安装一般是通过包管理器比如npm install -g或者从源码构建。装完后先跑一次skills --help确认命令可用。我建议在项目级别而不是全局级别安装技能这样不同项目可以用不同版本的技能包互不干扰。全局安装适合放那些你所有项目都用的通用技能比如 TDD 流程。提示如果你所在的环境对某些工具有访问限制优先确认官方文档里列出的支持范围避免在不可用的环境上浪费时间。4.2 编写第一个技能以 TDD 为例TDD 是理解技能包最好的切入点因为它的流程天然是有序、可判定的。一个 TDD 技能的SKILL.md大概这样写# 技能测试驱动开发 ## 适用场景 当需要新增功能或修复缺陷且项目已有测试框架时使用。 ## 前置检查 - 确认测试命令如 npm test / pytest - 确认测试文件命名约定 - 确认当前测试套件是否全绿 ## 执行步骤 1. 先写一个会失败的测试描述期望行为 2. 运行测试确认它确实失败红 3. 写最小实现让测试通过绿 4. 运行全部测试确认没有破坏其他用例 5. 在保持测试通过的前提下重构 ## 约束 - 不要先写实现再补测试 - 不要删除或跳过已有测试 - 不要一次写多个测试再一起实现 ## 验收 - 新增测试覆盖新行为 - 全部测试通过 - 无跳过的测试这份技能的关键在于步骤顺序不可颠倒。代理最容易犯的错就是先写实现再补一个能过的测试这违背了 TDD 的核心。把顺序写死并在约束里明确禁止能有效纠正这个行为。4.3 技能注入与代理配置技能写好后要让代理知道它的存在。常见做法是在项目根目录的代理配置文件里加一段说明告诉代理技能目录的位置和加载规则。以 Claude Code 为例可以在CLAUDE.md里写## 可用技能 技能存放在 ./skills 目录。当任务匹配某个技能时 先读取该技能的 SKILL.md按其中的步骤和约束执行。 不要一次性加载所有技能。这段说明本身很短但它建立了加载协议。代理知道去哪找、什么时候找、怎么用。skills CLI通常能自动生成或校验这段配置减少手工出错。配置完成后用一个简单任务测试一下看代理是否会主动读取技能文件。如果它没读多半是配置路径不对或者说明不够明确。4.4 参数与流程的取舍什么时候该用脚本不是所有步骤都适合让模型自由发挥。确定性操作应该脚本化。比如运行测试并解析结果这件事让模型自己跑命令、自己读输出、自己判断通过与否既慢又容易出错。写成脚本代理只负责调用和读结果稳定得多。判断标准很简单如果一个步骤有唯一正确答案且可以用代码表达就脚本化。跑测试、跑 lint、格式化代码、检查文件是否存在都属于这类。而设计接口、选择重构手法这类需要判断的留给模型。这个边界划清楚技能包的稳定性会高一个档次。5. 常见问题与排查技巧实录5.1 代理不加载技能怎么办这是最高频的问题。表现是代理直接开始干活完全没读技能文件。排查顺序如下先确认技能目录路径和配置文件里写的是否一致路径错了代理自然找不到再确认配置说明是否足够明确有些代理对可用技能这种模糊表述不敏感需要更直接的指令最后确认任务是否真的匹配了某个技能如果任务描述太模糊代理可能判断没有适用技能就跳过了。我的经验是在配置里给一个明确的触发示例比如当用户要求新增功能时读取 skills/test-driven-development/SKILL.md。有了具体例子代理的加载行为会稳定很多。5.2 技能被加载了但执行跑偏技能读了但代理没按步骤来。常见原因有三个步骤写得太抽象代理有自己的理解约束不够硬代理觉得可以变通验收标准缺失代理不知道做到什么程度算完。对应的解法是把步骤写成可执行动作、把约束写成硬性禁止、把验收写成可运行的检查。还有一种情况是技能之间冲突。比如同时加载了快速修复和严格 TDD两个技能代理不知道该听谁的。解决办法是明确技能优先级或者在技能里写清楚互斥关系。5.3 上下文超限与加载策略调整技能包用久了数量会膨胀加载时容易撑爆上下文。这时候要做的是分层把高频技能放在一级目录低频的放二级代理默认只扫一级。同时把长文档从SKILL.md里挪到references/改成按需读取。我一般会把单个SKILL.md控制在几百行以内超了就拆。5.4 常见问题速查表问题现象可能原因排查方向解决建议代理不读技能路径错误或说明模糊检查配置路径与触发描述加明确触发示例执行顺序错乱步骤抽象、约束不足检查步骤是否可执行步骤动作化、约束硬性化验收不通过却报完成缺少可运行验收检查是否有验收脚本把验收脚本化上下文超限技能过多或文档过长统计加载 token分层加载、按需读取技能互相冲突优先级不明检查技能适用范围明确互斥与优先级5.5 几个我踩过的坑第一个坑是技能写得太细。一开始我把每个操作都拆成一步结果技能文件长得像操作手册代理读起来费劲还容易在细节里迷路。后来我改成粗步骤 关键约束反而效果更好。技能是给代理的导航不是给新人的教程。第二个坑是忽略项目差异。同一套技能在不同项目里表现不一样因为测试命令、目录结构、代码风格都不同。解决办法是把项目相关的部分抽成变量或配置技能主体保持通用。比如测试命令不写死npm test而是写运行项目配置的测试命令。第三个坑是不做版本管理。技能改了之后之前跑通的任务可能又不行了。把技能包纳入 git 管理每次改动都有记录出问题能回滚。这一点在团队协作里尤其重要。6. 技能包的扩展方向与团队协作实践6.1 从个人技能到团队资产个人用技能包收益是效率团队用技能包收益是一致性。当所有人都用同一套技能代码风格、测试习惯、提交规范会自然趋同。做法是把技能包放进团队仓库配合 code review 流程技能改动需要评审。这样技能就从一个工具变成了团队规范的一部分。我见过效果最好的团队会把技能和 CI 打通技能里的验收脚本同时也是 CI 里跑的检查。这样代理在本地执行技能时遵守的标准和合并到主干时的标准完全一致不会出现本地过了 CI 挂了的情况。6.2 技能的组合与复用技能不是孤立的可以组合。比如新增 API 端点这个技能内部可以调用TDD技能来完成测试部分。组合的方式有两种一种是在技能里显式引用另一个技能另一种是让代理根据任务自动串联。显式引用更可控适合流程固定的场景自动串联更灵活适合探索性任务。复用的关键是抽象公共部分。多个技能都会用到的跑测试、检查格式这类步骤抽成共享脚本或子技能避免重复维护。这跟写代码抽公共函数是一个道理。6.3 持续迭代技能也需要测试技能本身也需要验证。我的做法是准备一组基准任务每次技能改动后用这些任务跑一遍看代理的表现有没有退化。基准任务不用多覆盖主要场景就行。这相当于给技能包做回归测试能挡住大部分改一处坏一处的问题。迭代节奏上我建议小步快跑。一次只改一个技能的一个点改完立刻验证。技能包不像代码那样有编译器帮你检查只能靠实际运行来发现问题。改得越少出问题时越容易定位。6.4 关于模型选择的一点经验技能包和模型是解耦的同一套技能可以配合不同的模型使用。实际体验下来能力强的模型对技能的依赖更低但用了技能后稳定性提升更明显能力弱的模型更依赖技能提供的明确指引。所以如果你在用多种模型技能包的约束部分要写得足够硬让弱模型也能照着走。有一点要注意不同模型对指令格式的敏感度不同。有的模型对 Markdown 结构响应好有的对纯文本列表响应好。如果你的技能在某个模型上表现异常先试试调整格式往往比改内容更有效。最后分享一个我一直在用的小习惯每次代理跑偏我都会问自己是技能没写清楚还是模型能力不够。如果是前者就改技能如果是后者就加约束或换模型。这个判断做多了技能包会越来越顺手代理也会越来越像你想要的那个靠谱同事。