最近身边不少人盯着Anthropic官方那篇SKILL实践指南反复啃啃完还是跑来问我文件结构我照抄了SKILL.md也写了为什么模型就是不按我想的来这个反馈我太熟了。SKILL这个功能官网上看就是“一个文件夹加一个Markdown文件”这么简单但真正让它好用起来的门道全藏在上下文管理、指令写法、测试迭代这些细节里。我前前后后搭了几十个SKILL把能踩的坑基本都踩了一遍回头再看官方那套最佳实践才意识到那真不是随便写写是踩完坑之后总结出来的。这篇文章我就把其中最有价值的三个技巧拆开揉碎讲清楚再带大家完整走一遍从拆需求到测试跑通的实操流程希望对正在折腾SKILL工作流的朋友有点用。1. 先把SKILL这个东西的底层逻辑掰清楚1.1 一个SKILL文件夹里到底装了什么很多人对SKILL的第一印象是“这玩意儿就是个高级提示词”这个理解不算错但太粗糙了。一个标准的SKILL本质上是一个独立目录里面装三类东西最核心的SKILL.md、可选的scripts/脚本目录、可选的assets/资源目录。SKILL.md开头是带name和description字段的YAML frontmatter后面跟着正文指令模型根据description判断这个技能是否匹配当前任务scripts/里放的是能被安全执行的独立程序通常是Python脚本用来处理重活、杂活比如解析PDF、批量改文件、算指标assets/放的是参考素材比如模板文件、示例数据、风格样例。这套“描述触发指令执行脚本兜底”的组合才是SKILL真正的工程化价值所在。description解决“什么时候该用”的问题SKILL.md正文解决“该怎么干”的问题脚本解决“哪些事不该让模型硬扛”的问题。三者各司其职缺一个整个工作流都会别扭。我见过不少人的SKILL只有孤零零一个SKILL.md把所有逻辑全塞进去结果指令又长又乱模型执行到一半就开始自由发挥。记住一个原则凡是能写进脚本的确定性逻辑就不要塞进提示词里让模型猜。1.2 SKILL和普通提示词、低代码工作流的本质区别理解SKILL的价值最好的方式是拿它跟另外两种常见方案做对比。第一种是普通提示词充其量是一段文字每次都要复制粘贴没有结构化没有可复用性改一个细节就要全文重写。第二种是Coze、Dify这类低代码工作流把节点拖拽串联起来可视化程度高但调试和扩展都依赖平台节点之间传参多了以后维护成本也不低尤其逻辑复杂时整个画布会变成一团蜘蛛网。SKILL走的是中间路线它把“什么时候用”和“怎么用”固化在一个文件夹里既不需要拖拽画布也不需要写复杂的编排框架目录一拷就能带走换个项目照样用。跟低代码工作流比SKILL的优势在于“轻”整个技能就是一个普通文件夹版本管理靠git就行不绑定任何特定平台跟普通提示词比优势在于“稳”脚本能保证计算和解析的准确性模型只负责理解和决策各干各擅长的活。这种“模型负责动脑、脚本负责动手”的划分方式是SKILL工作流和传统Agent方案最不一样的地方。2. 技巧一指令文风要从“功能简介”切换到“操作手册”2.1 官方实践里反复强调的“可执行性”Anthropic官方最佳实践里有个核心观点我特别认同好的SKILL.md读起来应该像一份操作手册而不是功能简介。很多人的SKILL.md开头写“本技能用于简历筛选能够评估候选人资质输出评估结果”这种描述本身没错但仔细想想它是在向模型“介绍”一个功能不是在“指挥”模型干活。官方指南反复强调SKILL.md的正文是给模型看的“作业指导书”模型不会像人一样“领会意图”它只会按照你能给出的最具体指令去执行。你写得越抽象它自由发挥的空间就越大结果就越不可控。这里有一个所有模型产品的共同特性模型对“步骤感”极其敏感。你给它“评估候选人”它就真的只丢给你一段泛泛的评价你给它“先读JD提取硬性要求→再逐项比对简历→输出表格”它就会老老实实走完这套流程。指令的颗粒度直接决定输出的颗粒度这一点在SKILL场景下被放大得尤其明显因为SKILL的设计初衷就是重复执行同一套标准化流程流程里每一步都不清晰的话技能怎么可能稳定。2.2 反例与正例的完整对照拿“简历筛选”这个场景举个例子。一个典型的“功能简介式”写法是这样的本技能帮助用户筛选简历分析候选人背景给出录用建议。然后正文草草几句完事。模型拿到这种指令能给你输出但每次输出的格式、维度、侧重点全凭当天心情有时夸学历有时夸项目经验完全没法横向比较候选人。正例应该长这样先定义执行前提——只有当用户提供了岗位JD或明确的招聘要求、且附上了待筛选简历时才执行然后拆步骤——第一步提取JD中的硬性条件并逐个列出第二步逐份简历与硬性条件比对标注“满足/不满足/存疑”第三步对存疑项给出可追问的问题第四步按统一表格格式汇总输出。最后还要约定输出格式。这套写法从“做什么”变成了“先做什么、再做什么、最后交什么”模型照做的成功率会明显上一个台阶。这也是我在实际项目中体会最深的一点写SKILL.md时把自己当成在给一个聪明但极度较真的实习生写任务单而不是在写产品介绍。2.3 触发说明description的写法要点description字段同样值得抠细节。官方实践的隐藏要点是description写得好不好直接决定这个SKILL在库里的“曝光率”。现在的Agent系统在每轮任务开始时都会做一次技能匹配匹配依据就是description跟当前用户请求的语义相似度。写得太窄比如“用于简历筛选”遇到“帮我看下这个候选人怎么样”就匹配不上写得太泛比如“用于处理文档”又会在不该触发的时候乱入。我的经验是description里塞三个要素核心能力、触发场景、典型输入形式。可以用类似这样的写法“根据岗位JD对中文简历进行结构化筛选和评分适用于招聘初筛、候选人横向对比、简历质量评估等场景输入通常为JD文本和一份或多份简历内容。”这样既覆盖了同义表达又把边界画清楚了。顺便说一句description里尽量不要堆砌跟功能无关的热词匹配机制没那么玄乎描述越自然越准确越好。3. 技巧二长逻辑一律外置用渐进式披露保住上下文3.1 为什么脚本外置比贴在SKILL.md里更稳第二个技巧涉及一个特别多人忽略的问题上下文长度。SKILL.md被加载进上下文的时候是整段整段地塞进去的以“支持/推荐”之类的内容为主导的冗长指令表面看是写得详细实际是在白白占用宝贵的上下文窗口。官方实践里给出过一个非常关键的建议——把复杂逻辑拆到独立脚本里而不是写进SKILL.md让模型一步步“朗读并执行”。因为对模型来说读代码、理解代码、再执行代码三步全在上下文里消耗token而执行脚本只需要一次输出调用结果干净利落。我在实际使用中对比过两种方案同样做一个“批量重命名文件并生成变更清单”的技能把正则表达式、遍历逻辑、重名处理全写进SKILL.md时模型经常在正则上翻车要么写错要么被上下文干扰改错了语义把逻辑写进scripts/rename_files.pySKILL.md里只写“运行脚本传入目标目录读取输出清单”之后成功率几乎是百分百。原因不复杂确定性逻辑本来就该用确定性工具完成模型不是正则执行器硬让它当结果必然不稳定。这也是官方实践里“脚本能做的别让模型做”这条原则的由来。3.2 渐进式披露的两种用法脚本外置之外还有一个配套技巧叫渐进式披露。这个词听着玄乎说白了就一句话**所有细节分层摆放按需展开。**第一层是SKILL.md正文只写流程骨架和关键决策点第二层是正文里用链接或路径指向的明细文档比如assets/example_output.md、assets/style_guide.md第三层才是脚本和完整数据集模型在没有明确需要时根本不碰它们。这样做的好处非常实际。一方面SKILL.md保持精简每次加载占用的上下文很少模型能快速抓取主干另一方面当某一步确实需要更细的参考比如输出格式拿不准时模型可以按路径打开示例文件照着做颗粒度和灵活性全都有了。我自己常用的做法是在SKILL.md关键位置写“输出格式参考assets/example_output.md”这样模型在不确定时会自己去看不会一遍遍消耗上下文去猜格式。别小看这个细节长会话里上下文就是这么一点一点省出来的。3.3 一套建议的目录结构结合上面的思路我给一个可以直接抄的目录结构适用于大多数“处理数据产出报告”类技能my-skill/ ├── SKILL.md ├── scripts/ │ ├── parse_input.py │ └── generate_report.py └── assets/ ├── example_input.md └── example_output.mdSKILL.md负责流程编排scripts/负责具体计算和转换assets/存放参考样例。命名上用动词开头parse_、generate_是为了让模型一眼看出脚本功能。还有一个容易踩的坑脚本一定要写健壮一点开头就检查入参、处理异常、给出明确报错否则模型拿到报错信息时往往一头雾水。脚本输出也尽量用结构化格式比如JSON方便模型读取和转述。如果你希望这个技能在Claude Code之外的场景也好用那脚本的独立性、退出码规范、错误信息可读性就更重要了。4. 技巧三用编号步骤返回点重构指令让模型照着做4.1 编号化步骤为什么比散文指令可靠第三个技巧是关于SKILL.md正文的编排方式。官方实践里有个很容易被忽略的小细节步骤建议用编号列表一条条列出来而不是用散文段落从头写到尾。这背后是有认知逻辑的——散文是一维线性结构模型要自己从中抽取流程顺序编号列表则是二维结构步骤与步骤的先后关系一目了然模型更容易形成明确的执行路径。我自己实测下来同样一套操作流程散文写法的执行偏差率明显高于编号写法尤其在步骤超过五步的时候。编号步骤带来的另一个好处是方便“引用”。当第5步依赖第2步的结果时我可以直接写“将第2步生成的候选列表作为输入继续”这种交叉引用在散文里很难表达清楚。此外编号便于模型在执行过程中汇报进度比如“已完成第1、2步正在执行第3步”排查问题的时候能快速定位卡点。这一步小小的格式改造相当于给模型的执行过程装了一套坐标系。4.2 在SKILL.md里做交叉引用与中间态记录做交叉引用的时候要刻意设计“中间态”。什么叫中间态就是每一步结束时要产出什么、格式是什么、放在哪里、下一步怎么拿到它。举个例子简历筛选技能里“提取JD硬性条件”是第1步那就明确第1步输出一个“硬性条件清单”以列表形式暂存在回答里“比对简历”是第2步那就写明“逐份比对第1步的硬性条件清单输出匹配表”。每一步的产出一旦定义清楚整个流程就串起来了。同时建议在SKILL.md里加一个“执行约定”小节把通用规则集中说明比如“所有输出使用中文”“评分先给出依据再给分数”“不确定的信息标记为存疑而非猜测”等。这些规则不属于某个具体步骤但会影响每一步。把它们集中放一起模型更容易记住也方便你自己后续维护。这个做法是官方实践里“可扫描性”思路的延伸让指令在视觉结构上先清晰起来模型才能在执行逻辑上清晰起来。4.3 一个可以直接改用的SKILL.md模板综合上面这些要点我给一个通用的SKILL.md模板框架大家直接替换内容就能用--- name: skill-example description: 用于[核心能力]适用于[触发场景]输入通常为[典型输入形式] --- # 技能概述 在执行本技能前先确认以下前提[列出前提条件不满足时向用户询问]。 ## 执行约定 - 输出语言[中文/英文] - 所有结论必须给出依据 - 不确定信息标记为“存疑”禁止猜测 ## 执行步骤 1. [第一步动作]详细说明怎么做产出什么中间态。 2. [第二步动作]引用第1步的中间态继续处理。 3. [第三步动作]生成最终结果按约定格式输出。 4. [第四步动作]如有必要调用scripts/下的脚本完成处理。 ## 输出格式 [给出最终输出的模板或指向assets/example_output.md]用这套框架写SKILL.md前五分钟就能搭出骨架后续只需要根据具体场景往步骤里填细节。我后来所有的技能基本都是从这个模板改出来的稳定性和可维护性都相当不错。模板不是死板的教条但它能在你思路还不清晰的时候逼着你先想清楚边界、步骤和产物这三个问题想清楚了技能就成了一半。5. 实战全流程从零搭一个“简历筛选SKILL”5.1 需求拆解先定义边界再动手理论讲完了拿一个完整的例子走一遍流程实战一次比看十遍文档都有用。我选“简历筛选”这个场景是因为它足够典型输入是JD加若干份简历输出是结构化评估表中间涉及文本解析、条件比对、评分排序既考验指令设计又需要脚本辅助非常适合用来演示前面说的三个技巧。动手之前先拆需求。我给自己定了三个边界第一技能只做初筛不代替面试官做最终决策第二硬性条件学历、年限、技能栈由脚本帮忙比对软性匹配度由模型判断并给出理由第三输出必须是统一表格方便后续横向比较。边界定清楚之后目录结构就自然出来了——一个resume_review/文件夹里面放SKILL.md、scripts/parse_resume.py和assets/example_output.md。5.2 编写SKILL.md与脚本的完整细节SKILL.md我是按第四节那个模板改的先写描述和前提再列执行步骤。description我写了很长一段把“初筛、评估、比较候选人、给出录用建议”这些同义场景全放进去保证匹配命中率。执行步骤一共五步提取硬性条件、解析简历为结构化数据、逐条比对、输出评估表、给出追问建议。其中第二步我明确写了“调用scripts/parse_resume.py解析简历脚本输出JSON格式的候选人结构化信息”第四步写了“输出格式参考assets/example_output.md”。脚本这块我写了一个parse_resume.py核心逻辑是接收简历文本路径或直接接收文本内容提取姓名、工作年限、技能关键词、教育背景最后输出JSON。代码不算复杂但有两个细节值得说一是对所有字段做了缺失兜底简历里没有的字段就输出null而不是报错二是把技能匹配逻辑也放进了脚本JD里的技能关键词列表由模型提取后作为参数传给脚本脚本负责做包含匹配这样匹配结果就是确定性的不会出现模型“觉得差不多就写了匹配”的情况。脚本跑完输出结构清晰的JSON后续的比对和评分由模型基于这些数据继续完成。5.3 测试、翻车、迭代的完整记录第一次测试就翻车了。我用一份真实的项目简历和一个虚构的JD去测结果脚本本身跑通了但模型的评估表里出现了“存疑”标记被忽略的情况。查了一下发现是我在SKILL.md里只写了“不确定标记存疑”没有明确说“存疑项必须单独列出并给出可追问的问题”。这是个典型的指令颗粒度问题改了一版之后好了。第二次翻车更有意思。我同时往输入里塞了五份简历其中两份还特别长结果模型在处理到第三份的时候开始丢信息评估表里漏了好几项。排查下来发现是中间态没有固化——模型在前几步生成的候选人结构化列表没有以明确格式暂存长上下文里被冲淡了。我的解决方案是在步骤三里明确要求“每处理完一份简历立即在回答中以固定区块输出该候选人的提取结果全部处理完后再汇总成表”相当于让模型自己给自己做缓存。改完之后五份简历一口气跑完信息完整性明显提升。这轮测试给我的教训是SKILL的bug绝大多数不是脚本bug而是指令bug。脚本出问题好歹有报错信息可以排查指令出问题则表现为“模型自由发挥”更加隐蔽。所以我的习惯是每改一次SKILL.md就准备一组固定测试用例跑一遍把输出跟上次的对比看变化是否符合预期。只有靠这种“笨办法”技能的稳定性才能慢慢积累起来这也是官方实践里强调测试迭代的原因。6. 排查手册SKILL工作流翻车的常见场景6.1 技能没被触发怎么办技能没触发是最常见、也最让人抓狂的问题。明明文件夹结构没问题仓库里也注册了但模型就是不用这个技能。这种情况九成是description写得不对。要么写得太窄用户换了个说法请求就匹配不上了要么写得太泛跟其他技能互相干扰匹配排序被挤下去了。排查方法很简单先在别的会话里用各种近义说法去问看哪条能触发哪条不能然后逆推修改description。记住一个原则description是写给人看的自然语言不是给机器看的标签描述越贴近真实用户说法触发率越高。还有一种是触发条件设计问题。有些技能必须在特定输入下才执行但用户没有给全输入模型又不知道该不该调用。这种要回到SKILL.md的“前提条件”小节写清楚触发前需要哪些信息缺失时是先问用户还是先猜。我的建议是强制先问宁可多问一句也不要让模型在缺参数的情况下用错误假设开始干活后续返工成本远高于那一次追问。6.2 脚本运行时报错脚本运行时崩溃原因通常集中在三类路径问题、依赖问题、入参格式问题。路径问题最典型脚本里如果用了相对路径读取文件而技能运行时的当前工作目录不是你预想的那个就会找不到文件。我的习惯是脚本开头统一处理路径优先基于脚本自身位置定位资源再兼容外部传入的绝对路径。依赖问题则提醒你脚本要尽量只依赖标准库需要第三方库时要么在SKILL.md里写明安装命令要么用pip封装成独立可执行环境别让模型去猜环境里装了什么。入参格式则是很多人会忽略的点。SKILL脚本的入参通常来自模型比如“把JD文本传给脚本”但模型在传参时可能带进多余的空格、换行甚至解释性文字。所以脚本解析入参时一定要做清洗去首尾空白、检查必填字段、遇到非预期格式直接返回友好错误。我见过太多脚本因为一行开头多了个空格整个正则匹配失效。脚本是给模型用的工具工具就要对“粗糙的调用方式”足够宽容。6.3 上下文被撑爆与输出不稳定长会话里跑SKILL经常遇到上下文被撑爆然后模型行为开始飘忽不定。这个问题很大程度上是设计问题SKILL.md太长、assets内容被频繁加载、脚本输出太大这些都导致上下文快速膨胀。解决办法有几个最重要的就是前面讲的“轻量SKILL.md渐进式披露”再配合脚本只输出结构化摘要而不是整段原始数据。另外长任务一定要引导模型分批处理一批处理完把结果整理成紧凑摘要再继续下一批而不是把全部原材料堆在上下文里。输出不稳定通常是因为指令里缺少“约束锚点”。什么叫约束锚点就是你给模型的具体限制条件比如“评分范围为1到10分”“结论必须有依据”“表格列固定为五列”。锚点越多输出越收敛。如果发现输出时好时坏先别急着改模型回头检查SKILL.md里是不是有太多模棱两可的词比如“大致”“适当”“合理”把这类模糊表达全部改成可量化的描述问题的复发率通常会明显下降。6.4 多SKILL共存的命名与互斥问题当技能库越来越大另一个问题冒出来了多个SKILL之间互相抢触发。我仓库里一度有两个技能都跟“文档处理”相关结果同一个任务两个都触发输出互相打架。解决思路是把description里的场景边界写得更窄更具体并且给每个技能加明确的“不适用”场景描述比如“本技能仅处理PDF格式不处理Word文档”。这看起来像是在教模型识别技能库本质上是逼你自己想清楚每个技能的能力边界。技能不是越多越好而是边界越清晰越好。命名上我也吃过大亏。早期为了省事技能名用过“process.py”“utils.py”这种写法后来根本分不清谁是谁模型匹配时也容易混。现在我的命名规范是动词_对象的格式比如parse_resume.py、generate_report.py文件夹名用能表达完整场景的短句比如resume-cv-reviewer。这套规范在技能数量超过十个之后节省的维护时间非常可观。最后再分享一个我个人的小习惯每个SKILL里的assets/example_output.md尽量用真实项目产生的样例而不是手写的理想样例。真实样例里藏着各种边界情况模型照着它输出能提前把很多坑暴露出来比事后踩雷舒服多了。