最近一个月我把团队里所有Agent相关的东西重新撸了一遍最后发现真正拉开使用体验差距的不是模型选得多大而是skill写得怎么样。同一个Codex、同一个Claude Code配上不同的skill产出质量能差出两三倍。今天这篇我想把你拉回到一个更底层的问题高效创建skill的流程到底是什么。很多人以为写skill就是往Markdown里塞一堆行业知识给AI念经。真不是。skill的本质是把“一次性做对的经验”抽象成“可重复执行的流程”让AI在没有你盯着的时候也能稳定复现。这篇文章我会从方法抽象的角度完整拆解一套我自己一直在用的创建流程文末附一份可以直接抄走的Review清单拿来评审任何一个skill好不好使。1. 先把skill的本质想清楚它到底是一个文件还是一种方法1.1 skill为什么突然这么热最近半年越来越多的Agent产品开始支持“skill”这个概念。Claude Code有skills目录Codex也有类似的能力不少工具类Agent甚至把skill做成了内置商店。热词榜单上“skill和agent的区别”“如何写一个skill”长期霸榜说明大家已经意识到skill是驱动Agent做出高质量产出的关键一环。我理解skill本质上是一组预置的“能力插件”。它解决的是Agent的上下文问题——模型每次对话只能塞有限的内容你不可能把一本操作手册全放进系统提示词里。skill的思路是把某个任务领域的方法论、步骤、判断规则、质量标准打包成文件放在Agent能按需读取的位置。AI接到任务后先判断“这个任务和哪个skill匹配”再读取对应文件按文件里的流程去执行。这跟传统“喂给AI一堆资料”最大的区别是资料只是被AI检索skill是被AI执行。你给AI一份日志排查手册AI会帮你总结但如果你给AI一个日志分析skillAI会按手册里的排查路径一步步走走到哪一步该看什么、该排除什么、什么时候该停下来问人全都照着做。前者是知识后者是技能。1.2 决定skill生死的三个文件一个完整的skill通常包含三块内容缺了哪一块都会觉得“不跟手”。入口文件是最核心的部分一般叫SKILL.md里面写清楚这个skill解决什么问题、怎么触发、执行步骤是什么。这个文件就像机器的操作面板AI全凭它来决定“我现在该干什么”。参考文档是备查的资料可以是行业标准、代码规范、设计模式也可以是你自己沉淀的案例。它只在需要的时候被读取避免大量信息塞进上下文把AI搞懵。可执行脚本是锦上添花的部分适合那些需要调用工具、跑计算的任务。比如生成的报告要自动转成PDF或者代码里要跑正则批量替换这些写成脚本比让AI逐行做可靠得多。1.3 方法抽象把“一次做对”变成“次次做对”我自己对“方法抽象”这四个字有很深的执念因为见过太多人把一个优秀解决方案直接丢给AI结果AI只能复述不能执行。什么叫抽象举个例子。你手上有一次非常成功的竞品分析报告从市场调研到价格比对到SWOT写得特别漂亮。如果让AI照着这份报告重新做一份AI大概率只是换皮——结构像了过程没学到。但如果抽出这份报告背后的方法先搜集哪些数据源头、按什么维度做对比、每个维度怎么打分、结论怎么推导、报告怎么写才能说服决策者——把这些步骤和规则变成流程文件AI才能“学会”做竞品分析。所以方法抽象的核心动作是两个第一把优秀的做法拆成步骤第二把每一步的完成标准和判断条件写清楚。skill的创建过程本质就是做这两个抽象动作。2. 高效创建skill的六步流程2.1 第一步写清楚“解决什么问题、不解决什么问题”很多人创建skill死在第一步因为他们想一个skill解决所有问题。边界模糊的直接后果是AI不知道该在什么时候调用它即使调用了也不知道什么时候该停下。我在创建skill前会强制自己写两句话。第一句是这个skill的适用范围比如“适用于中小规模项目的日志异常排查覆盖应用层和中间件层”第二句是明确不做什么比如“不适用于分布式链路追踪不负责性能调优”。这不是给自己设限而是给AI一个决策边界。这句话会直接影响你在SKILL.md里怎么写description描述。description是A判断是否调用skill的唯一依据写得越精确触发率越高。如果描述含糊AI要么遇事不决就调用把上下文搞乱要么该用的时候根本没发现它存在。2.2 第二步找一份真实的优秀产出做底稿创建一个好skill最忌讳凭空编造流程。我通常建议先去找一到三份真实案例最好是那种你亲历过、结果特别好的项目记录。比如要创建一个“需求文档评审skill”先找一份你们团队公认写得好的PRD再找一份评审记录、几轮修改意见。这些原始材料是方法抽象的原料后续的步骤和判断规则全都要从这里面抽出来。这一步要特别注意找的案例要有代表性覆盖这个任务里最典型的几种情况。如果创建的是代码审查skill至少要准备前端、后端、脚本三种类型的代码样本。样本太少抽出来的方法会以偏概全样本太多整理成本又太高。三份是一个比较合适的起步量。2.3 第三步从底稿里抽出方法和决策点这是整个流程里最需要经验的部分也是“方法抽象”最关键的一步。具体做法是拿着案例一步步反推做成这样之前经历了哪些判断我一般会列出三个问题来回看材料。第一完成这个任务的标准流程分几步每步的输入输出是什么第二中间有哪些分支选择比如日志里出现了A类型异常走的是这条路出现B类型异常走的是另一条。第三每一步做完拿什么标准确认“这一步确实做对了”这些标准就是AI执行过程中的质检点。把这些问题答案抽出来之后整理成一张执行流程图但这张图最终要变成文字化的步骤描述因为AI目前的强项是读文本不是读图。2.4 第四步写SKILL.md第一版只写流程和检查点写SKILL.md的第一版时不要一上来就想把内容写全更不要急着写长篇大论的背景知识。先搭骨架任务定义、适用边界、执行步骤、质检清单、反模式提醒。每一条都尽可能短像操作手册里的指令而不是像教材里的段落。我在这一步有个习惯写完每个步骤后会刻意问自己“如果是一个刚入职的实习生只看这几句话他能不能按顺序完成他卡住了会怎么处理”如果答案是不能说明表达得还不够可执行需要拆细或补判断条件。第一版不求完美目标是让AI能“跑起来”完成一次真实任务。哪怕结果还粗糙也比憋着一口气写半个月但从未验证强得多。2.5 第五步用小样本回归测试把写好的skill放到真实任务里去跑至少跑三到五次不同的任务。第一次可能会翻车太正常了。运行过程中你要重点关注三个信号AI有没有在正确的时间点触发这个skill触发之后有没有按SKILL.md里的步骤执行执行过程中有没有在哪一步卡住或走偏。每发现一个问题就回到SKILL.md里改对应的描述或步骤。测试的时候一定要用“真实任务”不要用你自己编的练习样例。真实任务的变量多、边界模糊更容易暴露skill在判断条件上的漏洞。我自己踩过最典型的坑是写一个会议纪要skill测试样例全用清晰录音的会议一上真实场景就发现AI分不清“老板最后拍板的结论”和“随口提的意向”后来在流程里加了一步“输出前先列出所有带决策语义的句子由使用者确认”问题才解决。2.6 第六步用Review清单评审后定稿前五步走完之后skill已经能用了但不一定经得起推敲。我会在交付之前过一遍Review清单从设计、编写、实测三个维度逐项打勾发现问题就改改完再跑一轮测试。这套Review清单就是这篇文章的核心交付物之一我会在后面第三节单独展开还附了一张可以直接打印出来用的表格。3. SKILL.md的写法直接决定技能好不好使3.1 frontmatter别乱填SKILL.md通常以YAML格式的frontmatter开头包含name和description两个核心字段。很多人不在乎这两行字随便写这是大忌。name字段是skill的唯一标识建议用连字符分隔的小写英文命名比如log-analysis、prd-reviewer。这个名字会出现在AI的内部索引里简洁明确最重要。description字段是AI判断“什么时候用这个skill”的说明书。我推荐一种三段式写法做什么什么时候用什么时候别用。举一个实际例子“分析应用日志并识别异常根因。当用户上传日志文件或描述线上故障时使用。不要用于代码编写、测试用例生成等编码类任务。”这样AI拿到的信息量是完整的触发决策才不会出错。3.2 正文用“先检查、后行动”的结构SKILL.md的正文最忌讳平铺直叙地写“第一步…第二步…第三步…”。虽然看起来逻辑清晰但没有给AI设置任务状态感知。我常用的是“检查-执行-检查”的结构。开头先让AI做一次现状检查当前手头有哪些输入哪些信息还没拿到拿不到应该怎么办然后进入执行流程每一步之间插入完成确认做完这一步后输出结果要满足什么条件才能进入下一步。这样设计的原因很朴素Agent在执行复杂任务时最容易出现的问题是——它不知道自己在哪个阶段也不知道自己做得对不对。检查点就是给它装一个进度条和路标降低跑偏的概率。3.3 判断条件写成决策表比写成长句更稳执行流程中难免有分支选择。比如代码审查skill里发现严重安全漏洞时应该停下并输出告警发现风格问题时只给优化建议。这种if-then规则如果写在长句里面AI会按自己的理解执行没法保证每次都走对。我的做法是把分支条件整理成结构化文本就像下面这样- 当发现SQL注入、硬编码密钥、越权访问时 立即停止审查先输出严重问题清单再继续其他检查。 - 当发现性能瓶颈但不确定是否为安全问题时 标记为待确认在同一轮审查末尾单独提问不要擅自下结论。 - 当发现代码风格、命名问题时 记录到建议清单不中断流程。这种决策表格式的分支描述相当于给Agent写了一套路由规则每个路口都有明确箭头。3.4 给AI一个“完成任务前必须自查”的结尾很多SKILL.md写到执行步骤结束就没了AI交完结果就算完事。其实还差最后一步——回头看。我建议在每个skill的结尾都固定加一段“完成标准”让AI在交付前对最终的输出做一次自查。可以是一条条列出的checklist比如“检查点1是否给出了明确的结论而不是只罗列数据”“检查点2是否标注了不确定项”“检查点3是否按任务的原始要求覆盖了所有问题”。这一步的作用是把“AI一次性输出”变成“AI有质检意识后再输出”大幅减少低级错误。而且它给了AI一个机会在交付前自己修正一遍效果比手动改prompt好得多。4. 配套的Review清单可直接抄走这套清单是我创建skill时每次都会过一遍的评估表按设计、编写、实测三个维度划分每一项都可以打分0-NG1-勉强2-合格。我建议新建skill后刷三遍真实任务再打分否则很容易自嗨。4.1 设计层评审设计层的核心是确认“这个skill该不该存在、边界是否清晰”。检查项说明自评分问题真实存在这个skill解决的确实是高频、可重复的问题而不是一次性任务0-2边界明确适用场景和不适用场景在description里都写清楚了0-2目标清晰使用这个skill后输出物能在质量上明显高于不用0-2案例支撑至少有3个真实案例作为流程抽取依据0-2复用价值这个流程换个场景还能再用一部分不是纯知识堆砌0-2这五项里我特别看重“案例支撑”。如果创建者说不出真实案例只靠想象写出来的步骤大概率一跑就崩。4.2 编写层评审编写层的核心是确认“AI拿到这个文件后能顺利执行”。检查项说明自评分触发描述准确description能区分该触发和不该触发的情况0-2步骤可执行每一步都是动作指令不是背景说明0-2判断条件完整分支选择都有明确的if-then规则0-2质检点到位每个关键步骤结束后都有完成标准0-2反模式覆盖明确写出了什么不该做至少3条0-2反模式覆盖是我特别强调的一项。很多人写skill只写“怎么做”不写“千万别怎么做”这就导致AI在不该自作主张的时候自作主张。我见过一个写周报的skill因为没写“不要编造未发生的工作内容”AI居然自动脑补了几条工作进展。反模式就像是护栏没有护栏的流程走不稳。4.3 实测层评审实测层是唯一能验证skill质量的手段不跑任务等于什么都没有。检查项说明自评分真实场景跑通至少在5个不同真实任务上执行成功0-2触发时机正确该触发时触发不该触发时不触发0-2产出质量稳定多次执行的结果质量差别不大0-2失败可恢复执行中途出错时AI能识别并给出补救方案0-2用户反馈至少一个实际使用者确认比手动做更高效0-2这项里最容易翻车的是“触发时机正确”。有些skill写完之后你发现AI在几乎所有任务里都想调用它说明description写得过于宽泛。这个问题在纯写代码阶段看不出来只有实测时才会暴露。这套清单总评分在24分以上满分30我才会把这个skill放进团队共用目录低于18分我建议直接推翻重写不要边用边补。补丁太多的skill最后会变成一团浆糊不如重新来一遍。5. 常见问题与排查技巧实录5.1 描述写太长AI根本触发不了第一个常见问题是description写得像一篇小作文AI在快速决策的时候直接忽略掉。description的功能是“快速匹配”不是“详细教学”。它应该像搜索引擎里的摘要一屏之内能看完。我的处理办法是description控制在三句话以内分别交代“做什么”“什么时候用”“什么时候不用”。如果三句话内你还写不清楚说明这个skill的定位本身就有问题先回头重新定义边界。5.2 把知识库当skill缺少动作指令我在不少团队里见过这种skillSKILL.md里堆了一堆行业术语、背景资料、注意事项看起来内容很丰富但AI读完不知道该干什么。这本质上是一份放错位置的知识库不是技能包。判断一个skill是技能包还是知识库有个简单测试把SKILL.md里的“动作动词”全部圈出来如果超过一半是“了解”“知道”“理解”那它就是个知识库。合格skill里的动词应该是“列出”“排查”“验证”“输出”“确认”这些可执行的动作。5.3 skill之间步骤撞车当一个项目里同时有多个skill时很容易出现步骤冲突。比如一个“代码审查skill”要求所有代码改动必须先生成测试用例另一个“快速原型skill”则完全不提测试AI如果同时读到两个skill就不知道该听谁的。解决这个问题我推荐两个手段。第一在各自description里增加“与其他skill同用时遵循”的说明比如“本skill涉及测试时以代码审查skill为准”第二在SKILL.md末尾加一个“执行优先顺序”小节明确自己和其他skill的关系。Agent遇到冲突时能按这个顺序自行决策。5.4 没有给AI纠错路径最后也是最重要的一个问题skill里没有纠错机制。很多skill默认AI第一次读取文件时就能正确执行但运行环境千变万化AI中途遇到异常输入、缺文件、格式不符合预期时完全没有预案。我习惯在SKILL.md中单独留一节“异常处理”用表格列出常见的异常情况和处理动作。比如“输入文件无法解析时先尝试两种编码格式再报告错误”“中途发现缺少必要参数时列出全部缺失项并请使用者补充不自行猜测”。有了这一节AI在真实场景里才不会再“沉默地优雅失败”。最后说一个我的个人习惯我现在每次写完一个新skill不会急着给别人用而是先自己连着跑五六次真实任务每次都录屏记录AI的执行路径。我特别关注它哪一步突然跳出了SKILL.md的流程——因为那不是AI笨而是流程里缺少了某个它需要的判断条件。补上这个条件skill就更完整一分。创建skill是件“先慢后快”的事情第一次写可能花掉一整天但一个抽象得好的方法论能被反复调用几十次上百次。这套流程和Review清单是我自己踩了无数坑之后沉淀下来的版本希望能帮你少走一些弯路。