很多人第一次听到SKILL这个概念时都会下意识把它当作某种高级工具函数或插件包。但实际上Anthropic官方对SKILL的定位要更深刻——它本质上是给Agent的一份作业指导书而不仅仅是给它多一把扳手。这也是为什么我们在实际做Agent工程时经常发现接入再多MCP工具模型在真实场景里依然会手忙脚乱而一份写得好的SKILL却能让模型瞬间进入熟练工状态。这篇内容我结合Anthropic官方最佳实践文档、社区里大量的SKILL实现案例以及我自己在项目里手写SKILL和调试Agent行为的经验把什么是SKILL和怎么写一个优秀SKILL这两件事彻底拆开讲清楚。无论你是刚开始接触Agent开发还是已经在用Claude Code、Codex这类工具这篇对你都会有实际帮助。1. 先搞清楚SKILL到底是什么它不是工具而是作业指导书1.1 一句话定义与核心机制SKILL在Anthropic的Agent体系里是一个可复用的行为封装单元。它用Markdown文件SKILL.md来告诉模型在遇到某类任务时你应当遵循怎样的思考路径、调用哪些工具、按什么顺序执行、最终产出什么格式的结果。关键点在于SKILL不是让模型多一个能力而是让模型知道怎么正确地干活。举个生活化的类比——你给一个实习生一台单反相机这是工具/MCP他拿到手也不一定拍得出好照片但你给他一份《室内人像拍摄SOP》告诉他光圈优先模式、对焦在人眼、用窗户光做主光源、先拍20张再选片——他照着做出片质量立刻不一样。SKILL就是这份SOP。从技术实现角度看SKILL的核心机制是当你把SKILL.md文件放进Agent的skills目录后系统会把该文件的内容注入到模型的上下文里或者在Agent初始化时暴露给它模型在运行过程中如果判断当前任务命中某个SKILL的适用范围就会主动照着流程走。官方文档里反复强调一个词progressive disclosure渐进式披露——也就是说SKILL.md文件不要一次性把所有细节都堆给模型而是只给摘要和关键路径细节放在模型需要时才去读取的辅助文件里这样既能保证模型知道有这个技能又不会占用太多上下文窗口。1.2 SKILL、MCP、Prompt三者到底什么关系这三个概念经常被放在一起比较我直接说结论Prompt提示词是一次性口述要求。你跟模型说帮我写份周报要包含数据对比和下周计划模型听完就干完事就忘。它灵活但不可复用每次都得从头说。MCP工具接入层是给Agent装上手和脚。MCP Server暴露一堆工具查数据库、发邮件、读文件解决的问题是Agent能操作哪些外部系统。但它不负责告诉模型什么时候用、怎么组合、产出什么样工具列表一多模型经常选择困难甚至调错参数。SKILL技能封装层是把一件事的完整做法固化下来。它把识别任务类型 → 拆解子步骤 → 调用哪些工具 → 如何处理结果 → 输出什么格式这一整套流程写成文档。特别重要的一点是SKILL本身不是工具它不直接执行任何操作操作还是要靠MCP工具或Agent内置能力去完成。所以真正的工程化结构是MCP解决能力边界SKILL解决行为质量。如果只接MCPAgent像个有手有脚但没受过培训的新员工加上SKILL之后它才变成熟手。还有一层关系容易忽略——SKILL是对Prompt的结构化管理。你可以把SKILL理解为一套有目录、有分工、有边界的工程化Prompt套装但它比普通Prompt强在三个方面可复用一个SKILL文件多处引用、可版本管理Git管理、可渐进加载只注入摘要细节按需读取。1.3 SKILL在Agent工程中的真实价值这几年做Agent工程化最大的痛点不是模型能力不够而是模型行为不稳定。同一个任务今天它知道先查资料再写答案明天可能直接就凭记忆胡编了这个会话它按你想要的格式输出换个会话又自作主张改了结构。SKILL就是用来解决这种行为漂移的。我自己实践下来SKILL带来的具体价值有这么几个把专家经验沉淀进Agent不用每次重复叮嘱模型你要注意这里别忘记先做那一步一份写好的SKILL会把完整流程固化下来。团队里新来的成员不用从头教Agent的脾气和习惯看SKILL文件就全明白了。大幅降低上下文损耗官方推荐的渐进式披露设计让Agent在大多数场景下只需要读取SKILL.md的摘要部分很短真正遇到复杂细节时才去读附加文档相比把一整套操作手册塞进System Prompt上下文占用可以少一个数量级。让调试和复盘变得可操作模型行为出了问题你不需要对着几百行的Prompt猜原因直接打开对应的SKILL.md检查是哪一步写得不清楚、哪个边界没定义好。改一行描述再跑测试这种可定位、可修复的体验Prompt根本给不了。2. SKILL的标准结构与目录规划一个小文件加一个配套文件夹2.1 一个完整SKILL的物理构成按照Anthropic官方的推荐一个SKILL在项目里通常是这样组织的your-project/ ├── skills/ │ ├── document-review/ # SKILL目录名简短清晰 │ │ ├── SKILL.md # 技能主文件必须存在 │ │ ├── scripts/ # 可选辅助脚本目录 │ │ │ └── extract_key_points.py │ │ └── assets/ # 可选参考文档、模板等 │ │ └── review_template.md │ └── meeting-summary/ │ └── SKILL.md目录名用短横线连接的小写单词kebab-case比如document-review、code-review、meeting-summary。SKILL.md是每个SKILL的灵魂文件除它以外的目录都是可选的。之所以推荐SKILL.md scripts assets这种结构核心考量就是渐进式披露。SKILL.md里只写摘要、何时使用、关键步骤 scripts目录放可执行脚本用于把机械化的数据处理从模型那里接管过来模型只负责判断和编排计算交给脚本准确率明显更高assets目录放模板、参考文档、示例输出模型需要时再读取。2.2 SKILL.md的YAML头信息怎么填才有价值SKILL.md的头部有一段YAML格式的frontmatter它决定了Agent在什么情况下能认出这个技能。拿Anthropic官方最佳实践的推荐写法来看一个合格的头部信息长这样--- name: document-review description: 文档审校技能。在用户提供文章、报告、技术文档并要求检查错误、优化表达、统一风格时使用。适用于中文和英文文档重点关注逻辑连贯性、事实一致性、格式规范性和可读性。 ---写description是这里最有讲究的部分。官方文档和社区的共识是description不要只写这是什么要写清楚何时触发和能力边界。我见过太多人只写一句文档审校结果模型在用户让它翻译一段文字时都误触发了——因为审校和翻译的边界没写明白。我推荐一个高可靠性的description模板四个要素缺一不可能力名称这个技能叫什么一句话说清。触发场景哪些情况应该调用这个技能写具体不要用模糊词。明确排除哪些情况不该调用这个技能把容易混淆的相邻场景点出来。地理/语言适用范围如果有语言或领域限制明确写出来。2.3 正文部分主文件只写流程骨架SKILL.md的正文部分官方推荐的是从宏观到微观的写作逻辑而不是事无巨细地罗列所有知识。我实践的写法是第一部分概述1-2句话——这个技能做什么、在什么场景发挥作用。这部分要简短模型读得快。第二部分何时使用When to Use——把应该用和不应该用的场景分列出来。这部分是把双刃剑写太粗模型容易乱触发写太细占用上下文。我的习惯是列举最常见的3-5个触发场景再加2-3个明确的不适用场景。第三部分核心流程Key Steps——这是技能的主体。按顺序告诉模型完成任务需要经历哪些步骤每一步要关注什么。这里只写骨架——做什么、产出什么不写怎么做的细节。细节留给脚本或assets里的参考文档。第四部分输出规范Output Format——明确产出物的格式标准。这一步经常被忽略但恰恰是最影响实用性的模型输出格式乱七八糟后面接手的程序就崩。2.4 scripts和assets的补充角色scripts目录凡是可以用代码精确完成的事情不要指望模型用自己的推理去算。比如统计文档字数、提取关键词、生成格式化JSON、批量重命名文件——这些在脚本里几十行代码就能做得完美让模型写代码再执行反而容易出错。一个重要的心得是让Agent调用MCP工具或执行脚本时一定要在SKILL.md里把传什么参数、期望什么返回格式写清楚否则模型会自由发挥传参不规范脚本根本跑不起来。assets目录放那些模型需要时才应该读的深度材料。比如更完整的示例、风格指南、历史优秀案例、原始参考文档。这样主文件SKILL.md体积可以控制在几百行以内模型绝大多数情况下只需要轻量读取主文件真正遇到特殊场景时才去翻assets——上下文占用率显著下降对API场景来说还能省钱。3. 怎么写一个优秀SKILL从白纸到可复用技能包的七个关键步骤3.1 第一步明确技能边界先定义不做什么动手写SKILL.md之前先做边界定义练习。拿我最近帮团队写的会议纪要生成SKILL举例动笔之前先列了三个问题这个技能解决什么任务将会议语音转录稿整理为结构化会议纪要。它不该处理什么不负责安排会议、不发会议邀请、不自动生成待办事项的提醒通知。它的输入是什么、产出是什么输入是语音转文字后的文本或笔记草稿产出是包含会议主题/时间/参与人/讨论要点/决议/待办事项六个部分的纪要文档。把这三个边界问题回答清楚后面写description和正文的时候笔头就有方向了。很多SKILL写得差不是文笔问题是边界没想清楚——什么都想做结果模型遇到任何任务都模模糊糊想触发误用率高得吓人。3.2 第二步设计description让模型一眼认出这就是我要找的description直接决定Agent的召回率和准确率。我的经验是写description时把自己当成产品经理在写功能入口文案要兼顾召回和去重从召回角度——必须包含任务领域的高频词。比如文档审校技能description里必须有检查错误优化表达语法格式风格统一这类词模型在上下文中做语义匹配时这些词是命中的关键信号。从去重角度——必须写清不在这里使用的场景。比如同样一个文档审校技能如果团队里还有专门的翻译审校SKILL那这个description里必须明确如果任务是对外文内容进行翻译并审校译文请勿使用本技能请使用translation-review技能。3.3 第三步画核心流程用步骤编号强迫模型按顺序执行在SKILL.md的Key Steps部分我强烈建议用有序列表来组织流程。Anthropic官方推荐的做法也是步骤化的因为模型对第一步第二步这种显式的序号极其敏感按顺序执行的服从率远高于整段描述。以文档审校SKILL为例核心流程写出来大概是读取用户提供的文档全文理解主题和用途。通读全文标记明显的错别字、语法错误、标点问题——这一轮只做机械错误检查不做深层次修改。逐段检查逻辑连贯性段内论证是否完整、段落之间是否有断裂、结论是否有依据支撑。检查事实一致性人名、时间、数据、引用来源是否前后矛盾。统一风格和格式对照assets中的风格指南检查标题层级、术语用词、编号格式、引用格式。汇总修改意见按严重程度分类必改/建议/可选输出审校报告。每一步都要给关注什么、产出什么但不要给具体怎么改。因为模型的语言能力很强你给它框架它就能发挥你反而去逐字教它怎么写既占空间又限制了它的灵活性。3.4 第四步把机械操作写成脚本模型只做判断和编排这是很多SKILL作者忽略的一步。举个实际例子我见过一个周报汇总SKILL作者让模型直接阅读10个团队成员的周报文本然后自己总结。结果模型经常漏掉某些人的重要进展或者把不同人的数据混在一起。正确做法是在SKILL目录里放一个scripts/extract_updates.py脚本它的职责是先把所有周报里的本周进展风险项下周计划三个字段提取出来并结构化模型只需调用脚本获得结构化数据再基于数据做概括和优先级排序。这样做的最大优势是错误率大幅下降脚本处理结构化数据是100%准确的模型只做它擅长的高层判断。我在SKILL.md里推荐这么写脚本调用部分使用 scripts/extract_updates.py 周报目录 提取团队成员周报中的关键更新。脚本会输出JSON格式的汇总对象包含每个成员的名字、进展摘要、风险项、下周计划。拿到JSON数据后基于它撰写汇总报告不要再直接引用原始周报文本。这样模型看到的是一个步骤5:运行该脚本 → 读取Json输出 → 基于输出撰写报告而不是读10份周报并提炼要点。准确率天差地别。3.5 第五步给出输出范例比描述一百句都管用对模型来说一个完整的输入输出示例胜过你对格式做的十句文字描述。在assets目录里放一个example_output.md给一个完整的输出样例让模型照着学。这个操作非常朴素但效果立竿见影——模型是Few-shot学习者给它一个完整范例格式服从率从60%提升到95%以上。拿文档审校SKILL来说示例里应该包含一份修改前的段落、对应的修改后段落、审校报告里怎么分类标注问题必改/建议/可选、用什么符号标示修改位置。模型看到这种一对一的对照马上就知道自己要产出的东西长什么样。3.6 第六步明确注意事项小节防止模型自由发挥在SKILL.md末尾我习惯加一个关键注意点/边界限制小节。内容通常是不要做的事比如不要改变原文的核心观点不要对数据准确性做主观臆断需要谨慎处理的场景比如如果原文有引用外部数据标出需要人工核实引用来源)当遇到异常情况的兜底方案比如文档编码无法解析时报告错误并请求重新提供文件这个部分本质上是给模型画红线。模型在自由发挥时经常会做出看起来合理但实际越权的操作——你加了注意点它跑偏的概率会显著下降。3.7 第七步设计测试用例验证触发条件和输出质量SKILL写完不是结束测试才是真正的工作量所在。我的测试清单一般包含三类触发测试给一段看似相关但实际不适用或者反之的任务文本看模型是否正确触发或正确不触发。这一步测的是description写得好不好。流程测试给一个标准任务输入看模型是否严格按SKILL.md里的步骤走完了流程有没有跳步、有没有多余动作。输出测试检查产出质量。格式对不对、内容全不全、有没有幻觉。这里建议找两三个人同时看同一份输出每个人对质量的判断不太一样收集足够反馈再迭代。官方文档里也推荐建立一个评测集eval set把你期望Agent在触发、执行、输出三个环节达到的标准写成一组测试样例每次修改SKILL之后跑一遍评测集确保没有引入回归。4. 我踩过的坑SKILL最容易犯的五个错误4.1 把SKILL当成万能说明书塞太多内容第一次写SKILL的时候我犯的最严重的错误就是恨不得把所有业务规则、行业知识、历史经验全部塞进SKILL.md。结果是文件写了上千行模型读一次就要消耗大量上下文而且细节越多模型在关键路径上的注意力越分散——经常陷入某个旁支细节忘了主线流程。官方推荐的渐进式披露是有道理的。主文件保持精简只保留骨架——触发条件、关键步骤、输出规范、红线提醒。真正需要时再去读取assets里更详细的参考资料。这个主文件几百行、参考文档能多厚就多厚的比例是实践下来最舒服的结构。4.2 description写得太笼统模型乱触发用于文档处理和在用户提供中文或英文文档并要求检查语法错误、优化表达、统一格式时使用如果是纯翻译任务请不要使用本技能——这两句话的触发质量天差地别。前者会让模型在用户提帮我翻译这段的时候也去打这个技能的主意后者把边界划得明明白白。4.3 脚本和SKILL之间缺少接口说明最开始我写的SKILL里让模型去跑脚本但没在SKILL.md里写清楚脚本的参数和返回格式。模型捣鼓半天传了个不存在的路径参数进去脚本抛异常Agent卡住。后来学乖了——每个脚本的调用说明都写成运行什么命令、传什么参数、返回什么结构、失败如何处理模型照着填参数几乎零障碍。此外脚本本身要加基本的错误处理文件不存在的时候返回友好提示而不是直接traceback模型看到后还能自动换个路径重试不至于卡死在那儿。4.4 忽略输出规范下游程序全是坑有的SKILL做完后下游还要对接自动化流程——比如把会议纪要写入项目管理工具、把审校报告发送到邮件系统。模型输出格式跑偏一个字段名下游程序就崩。我的解决方案就是在SKILL.md里放一个**输出JSON结构定义或输出Markdown模板**并在下一步把示例文件放进assets。然后测试的时候专门检查模型输出和模板的一致性。4.5 没有版本管理改坏了不知道回滚SKILL是工程产物理应纳入Git管理。我之前手写改了一版SKILL.md没提交Git跑了两天测试发现输出质量反而不如上一版想回滚却找不回来了。后来所有SKILL目录都进Git仓库每次改动一个commit备注里写清楚改了什么、为什么改”。测试完新的不满意就checkout回旧版。这种做法也方便团队协作——别人改了你的SKILL你能在code review里看到改动点避免悄悄改了啥的情况。5. 从0到1实操用代码审查SKILL演示完整写法纸上谈兵到此为止我直接用一个我自己写过的代码审查SKILL来做一个从零到一的完整实例你对照着抄就行。5.1 目录结构skills/ ├── code-review/ │ ├── SKILL.md │ ├── scripts/ │ │ ├── detect_secrets.py │ │ └── complexity_analysis.py │ └── assets/ │ ├── code_review_guide.md │ └── review_example.md5.2 SKILL.md全文--- name: code-review description: 代码审查技能。在用户提供源代码文件或代码片段并要求检查代码质量、找出潜在缺陷、评估安全风险时使用。适用于Python、JavaScript、Java、Go等主流编程语言。如果用户要求的是编写新功能而非审查现有代码请勿使用本技能。 --- # 代码审查技能 对用户提供的源代码进行系统性审查输出结构化审查报告帮助开发者在合并代码前发现潜在缺陷。 ## 何时使用 - 当用户要求审查代码检查代码质量看看这段代码有什么问题时使用。 - 当用户在Pull Request场景下要求帮我Review代码时使用。 - **不要**在用户要求写一个函数实现某个功能时使用。 ## 核心流程 1. 读取待审查的代码文件或代码片段。 2. 运行 scripts/detect_secrets.py 文件或目录路径检测硬编码密钥、API密钥、密码等敏感信息。脚本输出JSON数组包含风险类型和位置。 3. 运行 scripts/complexity_analysis.py 文件或目录路径计算圈复杂度、代码行数、嵌套深度等指标。脚本输出JSON对象。 4. 人工模型逐段阅读代码从以下维度检查并可对照assets/code_review_guide.md中的详细检查清单 - 逻辑正确性边界条件、空值处理、条件判断是否符合预期 - 并发安全性共享状态、竞态条件、锁使用是否正确 - 性能隐患无意义的重复计算、可避免的O(n^2)复杂度 - 可维护性命名是否清晰、职责是否单一、是否存在魔法数字 5. 汇总脚本检测结果和人工分析结果按严重程度分级输出审查报告。 ## 输出规范 按以下Markdown结构输出审查报告 ## 代码审查报告 ### 1. 概要 - 审查文件: 文件名 - 总体评估: 通过/需改进/存在高风险 ### 2. 严重问题必须修复 - 文件位置:行号 - 问题描述与修改建议 ### 3. 建议改进 - 文件位置:行号 - 问题描述与修改建议 ### 4. 潜在风险提示 - 脚本检测到的敏感信息或复杂度风险 ## 关键注意点 - 不要修改用户的代码只输出审查报告。 - 如果用户未提供完整代码只给了片段请在报告中注明仅对提供的片段做审查不覆盖完整上下文。 - 发现疑似敏感信息时不要输出具体密钥内容只指位置和类型并提示用户立即更换。安全优先。5.3 运行效果与复盘这个SKILL跑起来后Agent的行为显著变得更像一个负责任的代码审查员了先跑脚本检测敏感信息和复杂度再人工逐段分析最后按标准格式输出报告。不会有以前那种模型看了三行代码就开始发表长篇大论漏洞漏一堆的情况。复盘这个SKILL的成功要素第一个是description的触发边界写得很清楚明确排除写新功能第二个是步骤强制了顺序先脚本后人工第三个是输出格式固定死了下游接自动化处理很方便第四个是资产文件——code_review_guide.md 里有详细的审查维度清单遇到了具体场景模型会去参考平时不占上下文。6. SKILL的适用边界与选型判断什么时候该写、什么时候别写最后聊一个非常实际的工程问题是不是所有场景都值得写SKILL我的建议是以下三种情况适合上SKILL任务出现频率高每周至少有几次同类任务写一份SKILL能让模型在下一次直接进入状态省去反复调Prompt的时间。流程相对固定任务步骤可以标准化、顺序化。步骤越固定SKILL的收益越大。需要多人协作或跨会话复用团队里多个成员都在让Agent做类似的事写一份优质SKILL就等于把最佳实践沉淀下来全员共享。反过来以下情况不要急着写SKILL一次性任务用完就忘了写SKILL的投入产出比太低直接用Prompt约束就好。高度开放、没有固定流程的任务比如帮我头脑风暴几个创意这类任务没有标准步骤硬套SKILL反而束缚模型的发散能力。你还没搞清楚最优流程的任务先手工调教几轮确认什么做法效果好之后再固化成SKILL。过早把不成熟的流程写进SKILL会让模型在错误的路线上跑很久。另外关于SKILL会不会被模型忽略/误触发的问题我的实测经验是SKILL的本质是在上下文里注入一段行为准则文本——模型是否采用它是个概率问题。即使你把description写得很精准也无法做到100%命中但做得好的SKILL触发率和流程服从率通常在90%以上。剩下的10%就得靠测试后的持续迭代补。这也是为什么我一直强调评测集的重要性——要是没有一套固定的测试用例你到底把触发率从80%提到了85%还是90%根本说不清。写到这儿SKILL这件事基本聊透了。最后给一个我在实践中非常管用的小建议每写一个SKILL一定要花时间建立对应的eval set哪怕只有5-10个测试样例。因为SKILL这东西最核心的生态位就在沉淀工程化能力上——没有评测反馈的沉淀等于闭着眼优化一个系统而不是所看方向。等SKILL版本多起来这个评测集的价值会越来越大。比如模型升级了、API改了、业务规则变了跑一遍eval set马上就知道哪些SKILL需要调整比靠肉眼盯输出靠谱得多。要入坑SKILL就从今天下午写一个文档审校或会议纪要这种小技能开始吧。
