1. 从“agent-skills”说起为什么AI编码代理需要一套技能库第一次看到“agent-skills”这个标题很多人会以为它又是一个提示词合集。但真正在AI编码代理AI coding agents这条线上折腾过的人会明白它要解决的是一个更底层的问题如何让代理在真实项目里稳定地执行复杂任务而不是每次都要靠人重新描述一遍流程。我最初接触这个概念是在用Claude Code做一个小型重构项目的时候。当时我让它“帮我加一个带测试的功能”结果它写出来的代码能跑但测试文件放错了目录命名也不符合项目规范。问题不在于模型能力不够而在于它不知道这个项目的“规矩”。agent-skills要做的就是把这些规矩、流程、领域知识打包成可复用的技能单元让代理在需要的时候自动加载。简单说agent-skills是一套面向AI编码代理的技能组织方式。它把“怎么做某类任务”的知识从一次性提示词里抽出来变成结构化的、可版本管理的、可组合的模块。适合谁看如果你已经在用Claude Code、Cursor这类工具并且开始觉得“每次都要重复交代同一件事很烦”那这套东西就是为你准备的。如果你还没入门也可以把它理解成给AI代理写的“岗位操作手册”。2. 核心设计思路技能不是提示词而是可执行的上下文包2.1 为什么不能继续用长提示词硬扛很多人一开始的做法是把所有要求写在一个巨大的系统提示里代码风格、目录结构、测试框架、提交规范全塞进去。我试过超过一定长度后模型对中间部分的注意力会明显下降而且每次任务都带着一堆无关规则既浪费上下文窗口也容易让代理抓错重点。agent-skills的思路完全不同。它把知识按领域切分每个技能只负责一类任务。比如“写单元测试”是一个技能“处理数据库迁移”是另一个技能。代理在执行任务时根据当前上下文按需加载相关技能而不是一次性吞下所有规则。这就像给新员工一本分章节的操作手册而不是让他背完整本员工守则。2.2 技能单元应该包含什么一个设计良好的技能单元通常包含四个部分。第一是触发条件说明什么情况下该用这个技能比如“当任务涉及新增API端点时”。第二是操作步骤用自然语言或伪代码描述执行流程。第三是约束与规范比如命名约定、目录位置、必须调用的工具。第四是验证方式说明怎么判断任务完成得对不对。这四部分缺一不可。我见过只写步骤不写验证的技能结果代理做完之后自己都不知道对不对还得人来兜底。也见过只写约束不写触发条件的代理根本不知道什么时候该用最后变成了摆设。2.3 与test-driven-development的天然契合热词里出现了test-driven-development这不是巧合。TDD的核心是“先写测试再写实现”这个流程天然适合做成技能。因为测试本身就是一种可执行的验证方式代理写完测试后可以立即运行根据结果调整实现。我在实际项目里把TDD拆成了三个技能写失败测试、实现最小通过代码、重构。每个技能都有明确的输入输出和验证条件。代理执行时按顺序加载每一步都有反馈不会出现“一口气写完一大坨然后发现方向错了”的情况。这种拆分方式比让代理“用TDD写一个功能”要可靠得多因为后者太模糊代理很容易跳过测试直接写实现。3. 技能库的目录结构与组织方式3.1 一个可落地的目录布局技能库的物理结构直接影响可用性。我目前用的布局是这样的根目录下有一个skills文件夹里面每个技能一个子目录目录名就是技能标识。每个技能目录里至少有一个SKILL.md作为入口描述触发条件和操作步骤。如果有辅助脚本或模板也放在同一目录下。skills/ write-unit-test/ SKILL.md templates/ test-template.js handle-db-migration/ SKILL.md scripts/ generate-migration.sh refactor-module/ SKILL.md这种布局的好处是自包含。每个技能需要的所有东西都在自己的目录里复制、删除、版本管理都很干净。我试过把所有技能写在一个大文件里维护起来非常痛苦改一个技能要翻半天。3.2 SKILL.md的写法要点SKILL.md是技能的核心文件写法上有几个关键点。开头必须有一段简短的描述说明这个技能解决什么问题。然后是触发条件用列表列出具体场景。接着是操作步骤按顺序编号。最后是验证清单列出完成后的检查项。我习惯在操作步骤里嵌入具体的命令或代码片段而不是只写“运行测试”。比如写npm test -- --grep user service代理可以直接执行不需要再猜。验证清单也要具体比如“测试文件位于tests/unit/目录下”比“测试文件位置正确”要可操作得多。3.3 技能之间的依赖与组合有些任务需要多个技能配合。比如“新增一个带测试的API端点”可能需要先加载“写单元测试”技能再加载“实现API端点”技能。这时候可以在技能里声明依赖关系或者在更高层的编排逻辑里指定顺序。我的做法是在技能描述里加一个depends_on字段列出前置技能。代理加载时先检查依赖是否满足不满足就先加载依赖。这样避免了技能之间的隐式耦合也让整个技能库的依赖关系一目了然。不过要注意依赖不要搞得太深超过三层的依赖链就很难调试了。4. 实操从零搭建一个最小可用技能库4.1 环境准备与工具选择搭建技能库本身不需要复杂的环境。一个文本编辑器、一个版本控制工具就够了。如果你用的是Claude Code它本身支持读取项目里的文件作为上下文所以技能库直接放在项目目录里就能被识别。我建议把技能库放在项目根目录下的.agent-skills/文件夹里这样既不会污染源码目录也方便在多个项目之间共享。如果团队多人使用可以把技能库单独建一个仓库通过子模块或软链接引入。我试过直接复制粘贴结果不同项目的技能版本不一致排查问题很麻烦。4.2 编写第一个技能以“写单元测试”为例假设我们要写一个“写单元测试”的技能。首先确定触发条件当任务涉及新增函数或修改函数行为时。然后写操作步骤第一步读取目标函数的签名和现有测试文件第二步根据函数行为设计测试用例覆盖正常路径和边界情况第三步把测试写入指定目录命名遵循*.test.js格式第四步运行测试并确认失败因为实现还没写。验证清单包括测试文件位置正确、测试命名符合规范、测试能运行且当前失败、每个测试只验证一个行为。这些步骤写进SKILL.md后代理在执行相关任务时就会按这个流程走。我实测下来有了这个技能后代理写测试的规范性明显提升不会再出现测试文件乱放的情况。4.3 技能加载与触发的实现方式技能加载有两种常见方式。一种是显式加载在任务开始时手动指定要用哪些技能。另一种是隐式触发代理根据当前任务描述自动匹配技能。显式加载更可控适合关键流程隐式触发更方便适合日常任务。我的做法是混合使用。对于核心流程比如发布前的检查用显式加载确保不会漏。对于日常编码用隐式触发在技能描述里写好触发关键词代理匹配到就加载。不过隐式触发有个坑如果触发条件写得太宽泛代理会加载一堆不相关的技能反而干扰执行。所以触发条件要尽量具体比如“当任务描述中包含‘新增API’或‘添加端点’时”就比“当任务涉及后端开发时”要好。5. 常见问题与排查技巧实录5.1 技能不生效或加载失败最常见的问题是技能写好了但代理没加载。排查思路分三步。第一检查技能文件路径是否正确代理是否真的能读到。第二检查触发条件是否匹配当前任务可以手动在任务描述里加入触发关键词测试。第三检查技能文件格式是否有语法错误比如SKILL.md的标题层级混乱导致解析失败。我踩过的一个坑是技能文件名用了大写字母而加载逻辑只匹配小写结果一直加载不到。后来统一用短横线小写命名问题就消失了。另外如果技能依赖外部脚本要确保脚本有执行权限否则代理调用时会静默失败。5.2 技能之间冲突或重复执行当多个技能覆盖同一类任务时可能会出现冲突。比如两个技能都定义了“写测试”的步骤代理不知道该听谁的。解决办法是在技能描述里加优先级字段或者在加载时做去重。我的做法是每个领域只保留一个主技能其他变体作为子技能通过参数区分。重复执行通常是因为触发条件重叠。比如“写单元测试”和“写集成测试”都匹配“写测试”这个关键词代理可能两个都加载。这时候需要把触发条件写得更精确或者在技能里加互斥声明。我一般会在技能描述里写清楚“本技能仅适用于单元测试集成测试请使用xxx技能”。5.3 技能库的版本管理与团队协作技能库是活的会随着项目演进不断调整。如果没有版本管理很容易出现“昨天还能用今天就不行了”的情况。我的做法是把技能库纳入Git管理每次修改都提交并在提交信息里说明改了什么、为什么改。团队协作时建议指定一个技能库维护者负责审核合并。其他人可以提交修改建议但不要直接改主分支。我见过多人同时改同一个技能结果合并后逻辑矛盾代理执行时行为诡异。另外技能库的变更最好和项目代码变更分开提交方便回溯。5.4 常见问题速查表问题现象可能原因排查方法解决方式技能完全不加载路径错误或文件缺失检查代理日志中的文件读取记录修正路径确认文件存在技能加载但不执行触发条件不匹配手动在任务中加入触发关键词调整触发条件或显式加载执行结果不符合预期步骤描述模糊逐条对照技能步骤检查细化步骤加入具体命令多个技能冲突触发条件重叠列出所有匹配的技能加优先级或互斥声明技能执行报错依赖脚本权限或路径问题手动运行依赖脚本修正权限或使用绝对路径6. 进阶让技能库自我进化6.1 从执行日志中提取新技能技能库不应该只靠人手写。代理每次执行任务都会产生日志日志里包含了实际执行的步骤和遇到的问题。定期分析这些日志可以发现哪些流程被反复执行、哪些地方容易出错。把这些高频流程抽出来就能形成新技能。我现在的做法是每周花半小时翻一遍代理的执行日志把重复出现的操作模式记下来。如果某个模式出现超过三次就考虑把它做成技能。这样技能库会随着使用越来越贴合实际需求而不是一开始就设计一大堆用不上的技能。6.2 技能效果的量化评估光有技能还不够还得知道技能有没有用。我通常看两个指标任务一次通过率和人工干预次数。如果某个技能上线后相关任务的一次通过率提升、人工干预减少说明技能有效。反之就要检查技能设计是否有问题。评估周期不要太短至少跑两周再下结论。因为代理的行为有随机性单次结果说明不了问题。我一般会记录每个技能的使用次数和对应任务的结果积累到一定样本后再做判断。这个过程中也会发现一些“看起来有用但实际上没被触发过”的技能这些就可以考虑删掉或重写触发条件。6.3 技能库的扩展方向技能库的边界可以很宽。除了编码任务还可以覆盖代码审查、文档生成、依赖升级、性能分析等场景。我目前正在尝试把“代码审查”做成技能让代理在提交前自动检查常见问题比如未处理的异常、硬编码的配置、缺失的边界检查。另一个方向是跨项目复用。把通用技能抽出来放在共享仓库项目特有技能放在项目仓库通过加载顺序实现覆盖。这样新项目启动时可以直接继承通用技能只需要补充项目特有的部分。我试过这种方式新项目的代理配置时间从半天缩短到一小时左右。7. 一些实操心得与避坑建议技能描述里的步骤不要写得太抽象。“处理错误”这种描述代理没法执行“捕获异常并记录到日志文件日志级别为error”才是可操作的。我一开始写技能时总想着概括结果代理执行时各种自由发挥后来改成具体命令和代码片段稳定性大幅提升。触发条件宁窄勿宽。宽泛的触发条件会让代理加载一堆无关技能不仅浪费上下文还容易干扰判断。我现在的做法是每个技能只匹配两到三个具体关键词宁可手动加载也不要让代理自己猜。技能库要定期清理。用不上的技能、过时的技能、被其他技能取代的技能都要及时删掉。技能库不是越大越好维护一个精简、高命中率的技能库比堆一堆没人用的技能要有价值得多。我每季度会做一次技能库审查把过去三个月没被触发过的技能标记出来确认无用后就删除。最后分享一个小技巧在技能文件里加一个“反例”部分列出这个技能不适用的情况。比如“写单元测试”技能里可以写“不适用于集成测试和端到端测试”。这样代理在匹配时会更加谨慎减少误用。这个做法是我从代码注释里的“不做什么”得到的灵感实测下来对提升技能匹配准确率有帮助。