在AI Agent开发圈子里最近有一个词被反复提起——SKILL。如果你关注过Anthropic的官方文档或者翻过Claude相关的最佳实践案例大概率已经见过这个称呼甚至有人把它和Tool、MCP放在一起对比结论却是众说纷纭。我用了一段时间也踩了不少坑今天想结合官方的最佳实践把什么是SKILL、以及怎么写一个优秀的SKILL这件事彻底讲清楚。先说人话版本SKILL是给Agent准备的一套标准动作包。它把一个专业任务的工作流程、判断规则、参考知识和产出规范打包成一个可以被Agent按需调用的独立单元。以前你让Agent干活靠的是临时对话里的提示词现在你让它干活可以直接说调用某某技能来处理。这背后其实是Agent工程化的一次思路转变——从现场发挥走向标准化复用。这篇文章适合谁适合已经开始接触Agent SDK、正在研究如何让Agent稳定完成专业任务的人也适合想搞清楚SKILL和Tool、MCP到底差在哪的开发者。我会从概念讲到结构再从结构讲到实操写法最后分享一堆我实际踩过的坑。内容偏实战建议找个安静的时间慢慢看。1. SKILL是什么——给Agent的标准动作包1.1 先从Agent为什么需要SKILL说起我最早接触Agent时习惯把所有逻辑塞进一个系统提示词里。任务简单还凑合一旦涉及多步骤、多判断、多分支提示词就开始失控——不是漏步骤就是跑偏。后来换成了Tool调用模式让Agent自己去调API稳定了一些但依然有一个尴尬Agent知道该用什么工具却不一定知道该怎么专业地使用工具。举个具体例子。你给Agent一个图像处理工具它能调用接口但并不知道处理某类图片时应该先压缩再增强最后还要检查格式是否符合目标平台规范。这些知识不在工具接口里而在专业人员的操作经验里。SKILL就是来填这个空位的——它把会用工具提升到懂行地完成工作。1.2 SKILL与Tool、MCP、Prompt的本质区别很多人把SKILL当成另一种Tool这个理解不准确。我用一个类比说明Tool是零件。它告诉Agent你能做这个操作比如读取文件、调用API、发请求。MCP是插座。它把外部系统的数据和服务标准化接入Agent让Tool的来源更统一。Prompt是口头嘱咐。它告诉Agent你该怎么做但没有任何结构约束。SKILL是作业指导书。它把何时做、按什么步骤做、做到什么标准、用什么方法做完整封装Agent拿到后能照着执行。从设计目标看SKILL解决的问题是**专业能力的封装与复用**。Tool解决的是动作是否能做SKILL解决的是任务是否能做对、做专业。维度Tool / MCPSKILL核心内容接口、数据、外部操作流程、规则、知识、经验触发方式Agent自主决定调用Agent根据任务描述匹配加载主要文件可执行脚本或接口定义SKILL.md 参考资源能力目标能做什么怎么做得专业变更成本改接口/逻辑改文档/流程无需动代码还有一点值得注意SKILL和Tool可以配合使用。一个优秀的SKILL内部完全可以引用多个Tool或MCP服务它相当于在这些底层能力之上加了一层人类专家大脑。1.3 SKILL的标准文件结构与加载机制在Anthropic的实践体系中一个SKILL通常表现为一个目录核心入口是一个SKILL.md文件目录里还可以附带脚本、模板、参考资料、配置数据等辅助文件。典型结构长这样my-skill/ ├─ SKILL.md # 技能的核心说明书 ├─ scripts/ # 可选的辅助脚本 ├─ templates/ # 可选的输出模板 ├─ references/ # 可选的参考资料、数据表 └─ assets/ # 可选的静态资源Agent在运行时会根据用户的任务描述自动判断是否需要加载某个SKILL。加载的依据就是这个SKILL的名称和描述信息。一旦匹配成功Agent会把SKILL.md里的指令纳入自己的操作上下文然后按照其中的步骤干活。这个加载机制有一个很关键的细节Agent不会同时加载所有技能。它只挑选与当前任务最相关的那个。这意味着SKILL.md的描述写得清不清楚直接决定了这个技能能不能被正确触发。我后面会专门展开讲这一点。2. 拆解SKILL.md每个字段都是设计过的2.1 name与description触发逻辑的第一道关卡SKILL.md的开头两样东西最容易被忽略也最致命name和description。name是这个技能的IDdescription是Agent判断这个技能适不适用于当前任务的依据。你如果看一眼官方最佳实践就会发现他们特别强调description要写清楚这个技能的用途、适用场景和触发条件。举个例子一个糟糕的description可能是图像处理技能——太模糊了Agent无法判断具体什么时候用它。一个合格的description应该写成类似这样的效果用途范围适用于哪些类型的图像处理任务场景边界在什么情况下应该用什么情况下不应该用任务特征触发该技能通常伴随哪些任务关键词或输入特征。我自己的经验是description至少花30分钟来打磨写完后找三个不同类型的人分别读一遍看他们能不能准确说清什么时候该用这个技能。如果三个人答案不一致说明描述还有歧义需要继续收敛。2.2 instructions给Agent的操作手册怎么写instructions是SKILL.md的主体也是真正体现专业经验和工程素养的部分。官方最佳实践给了一个很实用的提醒instructions要让Agent像阅读一份标准作业程序一样执行而不是像看一段广告文案。我拆解一下优秀的instructions应该具备的层次输入前置条件开始步骤前Agent需要检查什么。比如确保输入文件格式为PNG确认数据列名与模板一致。核心处理流程按序执行的步骤每步尽量可验证。比如第一步读取原始数据并做重复值统计第二步根据统计结果决定是否清洗第三步输出清洗报告。分支规则遇到不同情况怎么处理。比如如果样本量少于100则跳过置信度计算如果超过则执行完整流程。产出规范最终输出要满足什么格式和验收标准。比如报告必须包含摘要、数据概览、结论三节字数控制在800字以内。这里有一个重要的技巧每一步都要尽量提供一个可检查点。比如完成后检查文件是否完整执行后核对输出行数是否与输入一致。Agent和人类一样如果流程里没有验证节点很容易产出看似完成其实半成品的结果。2.3 examples与参考材料让Agent照葫芦画瓢一篇SKILL.md只有流程描述还不够因为流程描述解决的是逻辑一致性但Agent还需要风格参照。官方实践强烈建议在SKILL里附上1到3个完整的示例可以是输入输出的前后对比、一个成品案例、或者一段正确的处理示范。我举个直观的例子如果你在写一个周报生成SKILL光写生成周报是不够的。你应该给一份范例周报让Agent明白周报的语气、结构、颗粒度。再给一个反例比如不要写流水账不要堆砌无结论的数据这能明显提升最终输出的质量。参考材料可以包括行业标准、规范文本历史优秀案例数据字典、字段说明常用模板、代码片段。这些材料不用全部塞进SKILL.md正文而是作为目录里的独立文件引用。Agent加载SKILL时会根据指令按需读取这些参考材料。这样做的好处是保持SKILL.md的简洁同时又能承载足够深的专业知识。2.4 参数与输出格式控制Agent的产出标准一个高质量SKILL还应该明确输入参数和输出格式。不是每个技能都需要像函数签名一样严格定义参数但至少你要让Agent知道这个技能接受的输入长什么样产出的结果用什么结构。我在实际使用中发现输出格式的约束往往比输入参数的约束更重要。因为Agent默认会用它习惯的叙述方式回答而你的业务系统通常需要结构化结果。比较好的做法是在SKILL.md的产出规范里直接给一个模板甚至是JSON结构示例然后要求Agent严格按该结构产出。另外还可以在SKILL.md里定义输出前自查清单。比如结果是否覆盖了任务要求的全部问题数据字段是否完整结论是否有依据支撑格式是否与模板一致。这一步能大幅减少你后期人工检查的成本。3. 实战手写一个高质量SKILL的完整流程3.1 选好技能边界写SKILL第一步不是动笔而是选边界。一个技能一定只解决一个领域的一类任务千万不要试图做一个万能技能。官方最佳实践里的建议也很明确技能要聚焦、职责单一让Agent在匹配时能快速命中。我把选边界拆成三个判断问题这个技能的任务是否有明确起点和终点是否具有可重复的操作流程是否积累了经验性知识而不仅仅是调用接口如果三个问题都回答是那么它适合做成SKILL。如果只是简单调用一次接口那用Tool就够了。我见过有人把发送HTTP请求也做成一个SKILL说实话这就是过度设计——SKILL承载的是专业流程不是单一动作。3.2 写清楚触发条件与禁用场景触发条件我前面提过这里再补充一个官方实践里容易漏掉的重要维度禁用场景。一个优秀SKILL不仅要告诉Agent什么情况下用我还要明确什么情况下不要用我。比如你写了一个数据分析报告生成SKILL如果用户只是想快速算一个平均值这个技能其实没必要被触发。你可以在description里加一句本技能仅用于生成完整数据分析报告简单数值查询请直接回答不建议触发本技能。禁用场景写清楚的作用有两个一是减少误触发带来的上下文浪费二是帮助Agent在任务不匹配时切换到更合适的处理方式。我实测下来加上禁用场景之后技能触发的准确率明显提高。3.3 步骤化、可验证的指令设计这是整个SKILL.md最核心的部分。我直接用一个我写过的实际技能来演示——结构化复盘报告生成。我在SKILL.md的instructions部分写了这样几段输入检查先确认用户给出的复盘范围、时间段、涉及的改进项。如果缺失先补充提问不接受不完整输入直接开工。复盘流程按目标回顾—结果对比—原因分析—改进计划四段结构生成。目标回顾要引用原始目标结果对比要用数据说话原因分析至少给出两个角度主观和客观改进计划必须包含负责人和时间节点。质量标准报告完成后检查是否每个改进项都有对应的可执行动作。如果发现加强沟通提升效率这类无法落地的表述必须改写为具体动作。这里的关键是每个步骤都不是建议式的语言而是强制式的操作指令。Agent和新人一样你给它留余地它就会偷懒你给它明确的检查点它才会输出稳定的结果。3.4 从优秀SKILL中提炼的五条军规我把安thropic官方推荐实践里反复出现的原则结合自己的踩坑经验浓缩成五条军规描述决定命运SKILL.md的description是第一生产力模糊的描述等于技能不存在。流程胜过自由发挥给你的Agent一套严格的步骤而不是一句你看着办。示例是最有效的沟通少写要高质量多贴一份高质量成品。资源文件按需加载不要把所有知识堆进SKILL.md用引用替代复制。没有验收标准的流程是伪流程每个关键步骤必须配一个可检查的验收节点。这五条字面上都很简单但真正做到位需要反复迭代和真实场景测试。4. 踩坑记录与排查清单4.1 description太宽泛导致误触发这是我最早犯的错。当时我写了一个技术方案设计SKILLdescription写的是帮助设计技术方案。结果Agent在用户随便问一句技术上的思路是什么时就触发了这个技能加载了一堆方案模板回答又长又重完全不符合用户的预期。排查后发现description缺少场景边界。后来我改成当用户需要为一个具体业务问题生成多方案对比、包含选型建议的技术方案时触发若用户只是询问思路或解释概念请直接回答不触发本技能。改完后误触发率几乎降为零。4.2 指令缺少验证环节导致半成品另一个典型问题是流程中缺少中间检查。我之前写了一个需求文档整理SKILLinstructions要求Agent提取需求并生成条目但没要求它核对原始需求是否全部被覆盖。结果是Agent偶尔漏掉隐藏在长段落里的需求点输出看起来很完整实际不完整。在每一步加一个核对清单就能解决这个问题。比如要求Agent在生成完条目后逐条对照原文标记每个条目的来源位置并输出覆盖率统计。Agent一旦发现自己漏了需求通常会主动补充。4.3 资源文件处理不当还有一次我把大量参考资料直接粘贴在SKILL.md里导致Agent每次加载技能都要消耗大量上下文响应变慢且容易迷失。后来我把参考资料拆到references目录并在SKILL.md里只写当需要对比框架版本时读取references/framework-comparison.md。这里有个原则SKILL.md只保留流程指令和必要的输出要求知识性内容全部进外部文件。这样既保持指令清晰又能让Agent按需读取不浪费上下文窗口。4.4 技能更新迭代的技巧技能不是一次写完就完事的。我的做法是给SKILL.md加一个版本记录区块每次更新都写清楚变更点和原因。这样做的好处是当Agent在运行中发现旧指令有问题时你能快速定位是哪个版本导致的你要做A/B测试时也能方便地回滚。另外建议每个技能都设计一个简单的self-test流程。比如在SKILL.md最后写一段验证方法让Agent在技能执行完毕后自我评分。这样你不需要每次人工盯流程Agent自己就能完成质量闭环。5. SKILL带来的工程化思考5.1 写skill这件事本质上是在做知识工程用了这么久SKILL我最大的感受是它把很多零散、口语化、藏在个人经验里的做事方法变成了可执行的工程产物。以前团队里的高级分析师教新人要花很多时间现在我们可以把他们的思维方式固化成一个SKILL任何拿到这个技能的人都能稳定产出接近专家水平的结果。这对AI原生开发范式的意义很大。过去我们追求把逻辑写在代码里、把知识存在知识库里现在SKILL提供了一条新路径——把怎么干活的专业经验沉淀为一种可调用的标准化资产。5.2 下一步可以怎么扩展如果你已经掌握了单个SKILL的写法下一步可以尝试这几个方向技能组合把多个SKILL串联形成一条完整的专业工作流。比如数据采集SKILL 清洗SKILL 分析SKILL 报告SKILL。技能进化根据Agent的实际输出效果定期更新SKILL的指令和示例让技能像软件一样持续迭代。团队共享把SKILL作为团队资产统一管理配合版本控制工具让每个项目都能快速利用团队积累的专业能力。我个人目前维护着一个几十个SKILL的库日常开发中Agent的稳定输出率比早期靠提示词驱动时提升了一个量级。当然这也离不开不断的踩坑和迭代。最后再分享一个小技巧每写一个SKILL先在10个不同风格的真实任务上试跑一遍每一次触发失败或输出不达标都值得回去修SKILL.md而不是去改Agent的设置有误。这听起来麻烦却是让技能真正可用的最短路径。