1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这大概率不是一个应用而是一套能力包。事实也确实如此——它本质上是一个围绕 AI coding agent 构建的技能集合与工程化实践框架核心目标是把让 AI 写代码这件事从随缘对话变成可复用、可测试、可交付的工程流程。为什么这个方向值得单独拎出来讲因为过去一年里AI 编程工具的能力边界扩张得非常快但绝大多数人用它的方式还停留在打开对话框描述需求复制粘贴结果。这种方式在写一个工具函数时够用一旦进入真实项目——多文件、有依赖、有测试、有历史包袱——就会立刻暴露问题AI 不知道你的项目约定不知道哪些文件不能动不知道改完之后怎么验证。agent-skills这类项目要解决的正是这个断层。它适合谁三类人最该关注。第一类是已经在用 AI coding agent 但总觉得差一口气的开发者你的痛点不是模型不够聪明而是缺少结构化的技能封装。第二类是想把 AI 编程引入团队协作的技术负责人你需要的是可复现的流程而不是个人技巧。第三类是刚接触这类工具的新手与其零散地学一堆命令不如先理解技能这个抽象层是怎么组织的。需要提前说明的是agent-skills本身是一个偏方法论 脚手架性质的项目它不绑定某一个具体的模型或客户端。所以下面讲的内容无论你用的是哪家的 coding agent思路都是通用的。我会结合当前主流的 AI 编程工具生态包括 Claude Code 这类终端 agent、VS Code 插件形态的 agent、以及各种第三方模型接入方案来展开但重点始终放在技能如何设计、如何测试、如何落地这条主线上。2. 为什么技能是 AI 编程的关键抽象层2.1 从提示词到技能的认知升级大部分人接触 AI 编程的第一步是学提示词技巧怎么描述需求更清楚怎么给例子怎么让它一步步思考。这些技巧有用但有个致命缺陷——它们是不可复用的。你这次调教得很好下次换个任务一切重来。技能skill这个概念的价值在于它把一次成功的交互沉淀成了一个可重复调用的能力单元。一个技能通常包含几样东西明确的触发条件什么时候该用它、结构化的执行步骤怎么做、以及验证标准怎么算做完了。这跟人类团队里的 SOP 是一个道理——老师傅的手艺要变成新人能照着做的流程中间必须经过文档化这一步。我自己的体会是当你手里积累了十几个打磨过的技能之后用 AI 编程的效率会发生质变。因为这时候你不再是在求AI 帮你干活而是在调度一个已经训练好的工作流。2.2 技能与工具调用、MCP 的区别在哪这里容易混淆。工具调用tool use解决的是AI 能碰到什么比如能不能读文件、能不能执行命令。MCP 这类协议解决的是AI 能连到什么外部系统比如数据库、API、第三方服务。而技能解决的是AI 知道该怎么组合这些能力去完成一类任务。打个比方工具调用是给了一个厨师刀和锅MCP 是给他接通了食材供应链而技能是菜谱。没有菜谱厨师拿着再好的工具也可能做出一盘黑暗料理。agent-skills关注的正是菜谱这一层——而且是那种经过反复试做、标注了火候和用量的靠谱菜谱。2.3 一个技能的最小可用结构基于我实际拆解和编写技能的经验一个能跑起来的技能至少要有这几个部分名称与描述一句话说清这个技能干什么描述要写得让 agent 能判断当前任务是否匹配。前置条件需要哪些环境、哪些文件、哪些权限。写清楚能避免 agent 在错误的前提下瞎干。执行步骤分步骤的操作说明每步尽量原子化避免然后适当调整这种模糊表述。验证方法怎么确认这一步做对了。这是最容易被忽略、也最重要的一环。失败处理出错了怎么办是回滚还是重试还是上报。很多人写技能只写中间那部分执行步骤结果 agent 跑起来要么不知道何时启动要么做完不知道对错。把首尾补齐技能才算完整。3. 用测试驱动的方式写技能TDD 思路的迁移3.1 为什么技能也需要测试agent-skills相关讨论里test-driven-development是个高频词。一开始我也觉得奇怪技能不就是一段说明文字吗怎么测试后来想明白了。技能的本质是对 agent 行为的约束和引导而 agent 的行为是不确定的。同一段技能描述换个模型、换个上下文执行结果可能完全不同。如果不测试你根本不知道这个技能是真能用还是只在某一次特定对话里碰巧成功了。这跟传统软件开发里不写测试的代码等于没写是同一个逻辑。技能是给 AI 用的代码自然也需要测试来保证它的可靠性。3.2 技能测试的三种粒度我把技能测试分成三个层次从轻到重测试粒度测什么怎么测适用场景触发测试agent 能否在正确场景识别并调用该技能构造若干该触发和不该触发的任务描述看命中率所有技能步骤测试技能描述的步骤能否被正确执行在沙箱环境跑一遍检查每步产出涉及多步操作的技能结果测试最终产出是否符合预期用断言或人工检查验证交付物有明确交付标准的技能触发测试最容易被跳过但它其实最关键。一个技能如果总是在不该用的时候被调用那它带来的干扰比帮助还大。我一般会准备至少 5 个正例和 5 个反例来测触发。3.3 把验证标准写进技能本身TDD 的精髓是先写测试再写实现。迁移到技能编写上就是先定义什么叫做完了再写怎么做。举个例子假设你要写一个给现有函数补单元测试的技能。不要一上来就写读取函数、分析分支、生成测试用例。而是先写验证标准生成的测试要能覆盖所有分支、要能独立运行、命名要符合项目规范、不能修改原函数。把这四条作为验收条件写进技能agent 在执行时就会主动往这个方向靠。这个顺序的调整看似小实际效果差别很大。先写验收标准等于给 agent 装了个目标导航只写步骤agent 容易机械执行而偏离真实意图。4. 技能在真实项目里的落地路径4.1 从最痛的那个环节开始新手常犯的错是想一次性搭一套完整的技能体系。我的建议是反过来的先找到你日常最烦、最重复、最容易出错的那个环节只给它写一个技能。比如很多人卡在改完代码不知道有没有破坏别的东西。那你的第一个技能就可以是改动后自动跑相关测试并汇总结果。这个技能边界清晰、验证标准明确、收益立竿见影。跑通一个你就有信心和手感去写第二个。4.2 技能的目录组织与命名当技能多起来之后组织方式就重要了。我见过比较合理的做法是按领域 动作来分目录比如skills/ code/ add-unit-test/ refactor-function/ fix-lint-error/ review/ check-security/ review-pr/ docs/ update-readme/ generate-changelog/每个技能一个目录目录里放技能描述文件通常是 markdown 或特定格式的配置文件必要时附带示例和测试用例。命名用动词开头一眼能看出这个技能做什么。注意技能名不要用helperutils这种含糊词。agent 判断是否调用某个技能很大程度上依赖名称和描述的语义匹配名字越具体误触发越少。4.3 技能之间的组合与依赖真实任务往往需要多个技能串联。比如修复一个 bug可能涉及定位问题诊断技能→ 写复现测试测试技能→ 修改代码重构技能→ 验证测试技能。这里有个坑如果技能之间没有明确的衔接约定agent 可能在中间某步就以为完事了。解决办法是在技能描述里写清楚完成本技能后通常需要接续哪个技能或者干脆把常用的组合封装成一个更高层的技能。我个人的经验是组合技能不要超过三层嵌套。层数一多agent 的上下文里塞满了各种指令反而容易混乱。宁可把复杂流程拆成几个独立的、各自可验证的技能让 agent 分步执行。5. 接入不同模型与客户端时的技能适配5.1 技能描述为什么要模型无关当前 AI 编程生态里模型和客户端的选择非常多有终端形态的 agent有编辑器插件形态的也有各种第三方模型接入方案。如果你写的技能强绑定了某一个客户端的特定语法那换个环境就废了。所以agent-skills这类项目的价值之一就是推动技能描述尽量用自然语言 通用约定来表达而不是依赖某个平台的私有格式。这样同一套技能今天在这个工具里用明天换个工具还能用。5.2 不同客户端的技能加载方式差异虽然技能内容可以通用但加载方式各家不同。常见的有几种文件约定式把技能放在项目里某个约定目录agent 启动时自动扫描加载。这种方式最省心适合团队共享。配置声明式在配置文件里显式列出要启用哪些技能。控制更精细但维护成本高一点。运行时注入在对话开始时手动把技能内容贴进去。灵活但不可复用只适合临时试验。我的建议是开发阶段用运行时注入快速迭代稳定后转成文件约定式纳入版本管理。这样既保证了打磨效率又保证了最终的可复现性。5.3 模型能力差异对技能执行的影响同一个技能用不同能力的模型执行效果可能天差地别。能力强的模型能理解模糊描述、能自己补全缺失步骤能力弱的模型则需要你把每一步都写死。这就带来一个现实问题技能该写多细我的做法是按你团队里最弱的那个模型来写。宁可写得啰嗦一点也不要指望模型自己领会。等确认流程稳定了再考虑给强模型写一个精简版。另外涉及终端命令执行的技能要格外小心。不同环境下命令的可用性不同技能里最好写明如果某命令不存在改用某某替代方案给 agent 留退路。6. 我踩过的坑和几条实操心得6.1 技能描述里的隐形假设我写过一个自动格式化代码的技能描述里默认项目用的是某个格式化工具。结果在一个用另一套工具的项目里agent 照着技能去装了一个不存在的依赖折腾半天。教训是技能里任何默认都要显式写出来并给出检测方法。比如先检查项目根目录有没有配置文件有则用对应工具没有则询问用户。把假设变成判断技能才真正健壮。6.2 验证步骤不能省但也不能太重早期我写的技能验证步骤特别详细恨不得每一步都让 agent 跑一遍完整测试。结果是执行速度慢得让人抓狂agent 大部分时间花在验证上。后来我改成分层验证关键节点做完整验证中间步骤只做轻量检查比如文件是否存在、语法是否能解析。这样既保证了最终质量又不至于拖垮效率。6.3 技能要跟着项目一起演进项目在变技能也得跟着变。我见过团队把技能写完之后就再也没动过半年后技能描述里的目录结构早就和实际对不上了agent 照着执行必然出错。我的做法是把技能纳入代码评审流程——改了项目结构或约定就顺手更新相关技能。技能和代码一样是需要维护的活文档不是写完就完事的一次性产物。6.4 给技能写反例这一条是我觉得最有价值的技巧。除了告诉 agent该怎么做我还会在技能里加一段常见错误做法明确列出几种不该出现的行为。比如在重构函数技能里写不要在一次改动中同时修改函数签名和内部逻辑这会让你无法判断是哪部分导致了测试失败。这种反例对 agent 的约束效果往往比正面描述还强。因为模型在生成时会主动避开你明确禁止的模式。7. 把技能体系跑起来之后我观察到的变化技能体系真正跑顺之后最明显的变化不是写代码变快了而是**AI 的输出变得可预期了**。以前用 AI 编程像开盲盒同样的需求每次结果都不一样有了技能约束之后输出质量的下限被显著抬高你不需要每次都盯着它、纠正它。第二个变化是团队协作。技能是可以共享的资产。一个成员踩过的坑、总结出的最佳实践写成技能之后其他人以及他们调用的 agent都能直接受益。这比写文档有效得多因为文档没人看技能是 agent 强制执行。第三个变化比较微妙你会开始用工程化的眼光看待 AI 编程。不再纠结于某一次对话的措辞而是思考这类任务应该沉淀成什么样的技能。这个视角的转变才是agent-skills这类实践真正想推动的东西。如果你现在还在用最原始的方式和 AI 编程工具打交道我的建议是别急着搭大体系先挑一个你每天都要重复的小任务认真给它写一个带验证标准的技能。跑通这一个你就理解整套方法论了。剩下的无非是复制这个模式而已。
