1. 为什么值得花时间研究 SKILL 的写法第一次接触 Anthropic 官方那套 SKILL 规范的时候我其实是有点不以为然的。当时脑子里想的是不就是把提示词拆成几个文件、加个元数据头吗能有多大差别结果真拿它去跑一个稍微复杂点的任务——比如自动整理一批会议纪要并生成待办清单——才发现问题全冒出来了模型该调用工具的时候不调用不该调用的时候乱调用中间步骤一多就开始丢上下文最后输出格式还飘。折腾了一下午回头再读官方那几篇关于 SKILL 的说明才意识到人家强调的那几个点恰恰是我踩坑的地方。SKILL 这个东西说白了就是给 Agent 用的“技能包”。它跟普通的提示词最大的区别在于普通提示词是“你告诉模型怎么做”而 SKILL 是“你告诉模型在什么情况下、按什么流程、用什么工具去做”。前者是一次性的对话后者是可复用、可组合、可被 Agent 自主调度的工作单元。这个区别听起来很抽象但落到实际项目里它直接决定了你的 Agent 是“能用”还是“好用”。我写这篇文章不是要把官方文档翻译一遍——那种事没意义。我想做的是把官方那套最佳实践里最核心的三个技巧拆开结合我自己在真实项目里踩过的坑讲清楚每个技巧背后的“为什么”以及具体怎么落地。这三个技巧分别是用元数据把触发条件写死、把工作流拆成可验证的闭环、用渐进式披露控制上下文膨胀。如果你正在做 Agent 开发、工作流编排或者只是想让自己的提示词工程更规范一点这篇应该能帮你省下不少试错时间。2. 技巧一用元数据把触发条件写死别让模型猜2.1 元数据不是装饰是路由依据很多人写 SKILL 的时候元数据部分就是随便填填name 写个大概description 写一句“用于处理某某任务”然后正文里再详细展开。这个习惯在单 SKILL 场景下问题不大但一旦你的 Agent 挂了十几个 SKILL模型要在里面挑一个来用元数据就成了唯一的路由依据。我举个真实的例子。之前做一个简历筛选的工作流里面有两个 SKILL一个是“解析简历 PDF 并提取结构化字段”另一个是“根据岗位要求给候选人打分”。我一开始把两个 SKILL 的 description 都写得很笼统结果模型经常在收到一份简历的时候直接跳到打分环节字段还没提取就开始评分输出自然是一塌糊涂。后来我把第一个 SKILL 的 description 改成“当输入包含 PDF 文件或原始简历文本且尚未提取出姓名、学历、工作年限等结构化字段时使用”第二个改成“当结构化字段已提取完成需要根据岗位 JD 进行匹配度评分时使用”路由准确率立刻上来了。这里的核心逻辑是元数据里的 description 不是给人看的是给模型做决策用的。所以它必须包含三个要素——触发条件、输入形态、输出结果。缺一个模型就可能在该用的时候不用或者在不该用的时候硬用。2.2 触发条件要写到“可判定”的程度什么叫“可判定”就是模型读完这句话能明确判断当前上下文是否满足条件。像“用于处理文档相关任务”这种描述就是不可判定的因为“文档相关”太宽泛了。而“当用户上传的文件扩展名为 .pdf 或 .docx且请求中包含‘总结’‘提取’‘整理’等意图词时使用”就是可判定的。我自己的经验是触发条件最好包含两类信息输入信号和前置状态。输入信号指的是当前上下文里出现了什么——文件类型、关键词、用户意图前置状态指的是之前已经完成了什么、还没完成什么。比如“当上一步已经完成字段提取且当前请求涉及评分或排序时使用”这就是一个带前置状态的触发条件。注意触发条件不要写得太窄否则 SKILL 永远不被调用也不要写得太宽否则会被滥用。一个实用的判断标准是如果你把这条 description 单独拿给一个不了解项目的人看他能不能准确说出“什么情况下该用这个 SKILL”如果能就合格了。2.3 元数据字段的取舍与常见坑官方规范里元数据字段有好几个但实际用下来真正影响行为的主要是三个name、description、when_to_use。name要短且唯一最好用动词开头比如extract_resume_fields就比resume_parser更明确。description写清楚这个 SKILL 做什么、输出什么。when_to_use则是触发条件的详细展开。我踩过的一个坑是在description里写了太多实现细节比如“使用正则表达式提取手机号使用日期解析库处理时间字段”。这些内容模型在路由阶段根本不需要知道反而会干扰判断。实现细节应该放在正文的步骤说明里元数据只负责“什么时候用”和“用了能得到什么”。另一个坑是元数据里的语言不统一。有的 SKILL 用中文写 description有的用英文模型在跨语言路由时会出现理解偏差。建议要么全中文要么全英文别混着来。3. 技巧二把工作流拆成可验证的闭环3.1 什么是“闭环”为什么它重要“闭环控制”这个词是从控制论里借来的放到 Agent 工作流里意思就是每一步操作都要有一个明确的验证环节确认上一步的结果符合预期之后再进入下一步。没有闭环的工作流就像开环控制的电机——你给了指令但不知道它转了多少圈、有没有堵转出了问题只能等最终结果不对了才发现。我做过一个 Coze 上的工作流任务是“把一篇长文拆成多个短视频脚本”。最初的版本是线性的读取文章 → 分段 → 每段生成脚本 → 汇总输出。跑了几次之后发现分段环节经常把一段完整的意思切成两半导致后面生成的脚本逻辑断裂。但因为中间没有验证模型一路往下跑最后输出一堆看起来像那么回事、实际上没法用的脚本。后来我加了一个闭环分段完成之后先让模型自己检查“每一段是否语义完整”如果不完整就重新分。这个检查步骤只多花了几秒钟但输出质量提升非常明显。这就是闭环的价值——用小的验证成本换大的返工成本。3.2 闭环的三种常见形态在实际项目里闭环不一定都是“检查-重试”这一种形态。我总结下来常用的有三种第一种是格式校验闭环。比如要求模型输出 JSON那就用代码解析一下解析失败就让它重新输出。这种闭环最简单也最可靠因为验证逻辑是确定性的。第二种是语义校验闭环。比如上面说的分段完整性检查或者“生成的摘要是否包含了原文的核心论点”。这种闭环需要模型自己来判断可靠性取决于提示词的质量但胜在灵活。第三种是外部工具校验闭环。比如生成代码之后跑一遍单元测试或者生成 SQL 之后在测试库上执行一下。这种闭环最接近真实工程实践但搭建成本也最高。我的建议是能用第一种就别用第二种能用第二种就别用第三种。格式校验几乎零成本语义校验需要精心设计提示词外部工具校验则要考虑环境隔离和安全性。很多工作流其实只需要格式校验就够了没必要上重型方案。3.3 闭环的粒度怎么定闭环不是越多越好。我见过有人在每一步后面都加一个验证结果整个工作流跑一遍要调用十几次模型延迟高得没法用。闭环的粒度应该根据这一步出错的代价来定。如果某一步出错之后后面的步骤还能纠正回来那就不需要闭环。比如“提取关键词”这一步就算漏了一两个词后面的摘要生成也不至于完全跑偏。但如果某一步出错会导致后续全部无效那就必须加闭环。比如“解析结构化字段”这一步如果字段名对不上后面的打分逻辑就全乱了。一个实用的判断方法是问自己“如果这一步的输出是错的我能在最终结果里看出来吗”。如果看不出来那就需要闭环如果一眼能看出来那可以靠人工兜底不一定非要自动化验证。4. 技巧三用渐进式披露控制上下文膨胀4.1 上下文超长是工作流的隐形杀手做 Dify 工作流或者 Coze 工作流的人应该都有体会工作流一长上下文就爆炸。每个节点都把前面的输出全量传下去到后面模型要处理的 token 数可能是最初的十几倍。这不仅拖慢速度、增加成本更严重的是会稀释关键信息——模型在一大堆无关内容里找重点很容易找偏。Anthropic 官方在 SKILL 规范里提到的“渐进式披露”就是解决这个问题的。核心思路是不要把 SKILL 的全部内容一次性塞给模型而是先给一个概要等模型确定要用这个 SKILL 了再逐步展开细节。这个思路其实跟人查手册是一样的。你拿到一本操作手册不会从第一页读到最后一页而是先看目录找到相关章节再看那一章的具体内容。渐进式披露就是把这个过程自动化了。4.2 三层结构概要、步骤、细节我自己的 SKILL 文件通常分成三层来写第一层是概要层放在元数据和正文开头用两三句话说明这个 SKILL 做什么、输入输出是什么。这一层是模型在路由阶段一定会读到的。第二层是步骤层列出这个 SKILL 的主要步骤每一步一句话。模型决定使用这个 SKILL 之后会先读这一层了解整体流程。第三层是细节层针对每个步骤展开具体的操作说明、参数配置、注意事项。这一层只有在模型执行到对应步骤时才会被引用。这样做的效果是在路由阶段模型只需要处理概要层的信息上下文占用很小在执行阶段模型按需读取步骤层和细节层不会一次性把所有内容都加载进来。4.3 引用式写法与文件拆分渐进式披露在实现上有两种常见做法。一种是引用式写法就是在 SKILL 正文里用“详见 XX 章节”的方式指向细节让模型自己决定要不要去读。另一种是文件拆分把不同层的内容放在不同文件里通过工具调用来按需读取。引用式写法适合内容不太多、单个文件能装下的场景。比如一个 SKILL 总共两三千字那用引用式就够了没必要拆文件。文件拆分适合内容很多、或者多个 SKILL 共享部分细节的场景。比如你有五个 SKILL 都需要用到同一套“日期格式转换”的规则那就把这套规则单独放一个文件五个 SKILL 都引用它。提示文件拆分的时候文件名要能自解释。比如date_format_rules.md就比rules.md好因为模型在决定要不要读这个文件的时候只能看到文件名。我实测下来渐进式披露对长工作流的性能提升非常明显。一个原本要传 8000 token 上下文的工作流用了渐进式披露之后大部分节点的上下文能控制在 2000 token 以内整体延迟降低了差不多一半。5. 三个技巧怎么组合使用5.1 一个完整案例的拆解光说技巧容易空我拿一个实际做过的项目来串一遍。这个项目是“自动整理会议纪要并生成待办清单”工作流大概是这样接收会议录音转写文本 → 提取议题和结论 → 识别待办事项 → 分配负责人和截止时间 → 输出结构化清单。按照三个技巧来改造之前这个工作流经常出问题有时候把闲聊内容也当成议题有时候待办事项漏掉有时候负责人分配错。改造之后我是这么做的元数据层面我给每个 SKILL 都写了明确的触发条件。比如“提取议题和结论”这个 SKILL 的触发条件是“当输入为会议转写文本且尚未提取出结构化议题时使用”。这样就避免了它在已经提取过的情况下被重复调用。闭环层面我在“识别待办事项”后面加了一个语义校验让模型检查“每一条待办是否都有明确的动作和对象”。如果没有就重新识别。这个校验拦住了一大批模糊的待办比如“跟进一下那个事”这种。渐进式披露层面我把“分配负责人”的规则拆成了单独的文件里面包含了“根据历史会议记录推断负责人”“根据议题关键词匹配部门”等具体规则。主 SKILL 里只写“按照负责人分配规则执行详见 rules 文件”模型在执行到这一步时才去读规则文件。5.2 组合使用的优先级如果你刚开始接触这三个技巧我建议的优先级是先做元数据再做闭环最后做渐进式披露。元数据的改动成本最低收益最直接。很多时候工作流出问题就是因为模型不知道该在什么时候用什么 SKILL把元数据写清楚就能解决一大半问题。闭环的改动成本中等但需要你对工作流的每个环节有清晰的理解知道哪里容易出错、出错代价多大。这个需要跑几次、观察几次才能摸清楚。渐进式披露的改动成本最高因为它涉及到文件结构和引用关系的重新设计。建议等工作流基本稳定了、只是性能或成本有问题的时候再考虑。5.3 常见误区与避坑清单我见过也踩过的一些坑列在这里供参考误区后果正确做法元数据 description 写得太笼统模型路由错误该用的不用写清楚触发条件、输入形态、输出结果每个步骤都加闭环延迟高、成本高只在出错代价大的步骤加闭环闭环验证逻辑太复杂验证本身成为新的错误源优先用确定性校验语义校验要精简渐进式披露拆得太碎模型频繁读文件反而更慢按内容量决定是否拆分小内容用引用式文件命名不可自解释模型不知道该不该读文件名包含内容关键词三个技巧同时大改出问题不知道是哪个改动导致的一次改一个改完跑测试再改下一个6. 实操中容易忽略的细节6.1 测试 SKILL 的触发准确率元数据写完之后别急着上生产先做一轮触发测试。方法很简单准备一批输入样本每个样本标注“应该触发哪个 SKILL”然后让模型自己路由看准确率。如果准确率低于 90%就回去改 description。我一般会准备 20 到 30 个样本覆盖各种边界情况明显该触发的、明显不该触发的、模棱两可的。模棱两可的那些最能暴露问题——如果模型在这些样本上犹豫说明你的触发条件写得不够明确。6.2 闭环的重试次数要设上限闭环里的“检查-重试”不能无限循环。我一般设最多重试两次两次还不过就降级处理——要么输出当前结果并标记“未通过校验”要么走一个兜底逻辑。无限重试的后果是一旦某个环节卡住整个工作流就挂在那里既浪费资源又影响体验。6.3 渐进式披露的引用要可追踪用了引用式写法之后要确保每个引用都能被解析到。我遇到过的情况是SKILL 正文里写了“详见 XX 文件”但那个文件后来被改名了模型找不到就自己瞎编了一套规则。所以每次改文件名或者移动文件位置都要检查一遍引用关系。6.4 版本管理别偷懒SKILL 文件是要迭代的每次改动都要有记录。我自己的做法是在文件头部加一个简单的版本注释写清楚这次改了什么、为什么改。别小看这个习惯等你有十几个 SKILL、改了几十版之后没有版本记录根本记不清哪个版本对应哪个行为。7. 关于 Agent 安全的一点补充做 Agent 工作流的时候安全问题是绕不开的。SKILL 本质上是在给模型授权——授权它调用工具、访问数据、执行操作。所以元数据里最好也体现一下权限边界比如“这个 SKILL 只读取数据不写入”“这个 SKILL 只能访问指定目录下的文件”。闭环在这里也能起作用。比如一个会写入数据的 SKILL可以在写入之前加一个确认闭环让模型检查“即将写入的内容是否符合预期格式和范围”。这不能完全防止恶意输入但能拦住大部分误操作。另外SKILL 之间的调用关系要清晰。如果一个 SKILL 会触发另一个 SKILL那就要确保不会形成循环调用。我见过一个案例SKILL A 在特定条件下调用 SKILL BSKILL B 又在特定条件下调用 SKILL A结果两个 SKILL 互相触发把上下文撑爆了。避免这种情况的方法是在元数据里明确标注“本 SKILL 不调用其他 SKILL”或者“本 SKILL 只调用 XX”。8. 我个人的几条经验总结第一个经验是别追求一次写完美。SKILL 这东西是迭代出来的第一版能跑通就行后面根据实际表现慢慢调。我见过有人花两天时间设计一个“完美”的 SKILL结果上线之后发现触发条件跟实际输入对不上全部重写。第二个经验是多观察模型的“犹豫时刻”。当模型在两个 SKILL 之间反复横跳或者在一个闭环里反复重试的时候那就是信号——说明你的元数据或者闭环设计有问题。这些时刻比最终输出更能反映工作流的健康度。第三个经验是保持 SKILL 的单一职责。一个 SKILL 只做一件事做深做透。我见过有人把一个 SKILL 写成“万能处理器”什么任务都往里塞结果触发条件怎么写都不对闭环也没法加因为不同任务的验证逻辑完全不一样。拆成多个小 SKILL每个都有自己的明确边界组合起来反而更灵活。第四个经验是文档和 SKILL 一起维护。SKILL 是给模型看的文档是给人看的。两者要同步更新否则过一段时间你自己都忘了某个 SKILL 为什么那么写。我现在的习惯是每次改 SKILL 都在对应的文档里记一笔哪怕只是一句话。最后说一个我最近才意识到的点SKILL 的写法其实反映的是你对任务的理解程度。如果你对任务本身的理解是模糊的那写出来的 SKILL 一定是模糊的模型执行起来也一定是飘的。所以与其在 SKILL 的格式上反复打磨不如先花时间把任务拆清楚——拆到每一步都有明确的输入、输出、验证标准。到那个时候SKILL 怎么写就是水到渠成的事了。