在LLM应用开发的圈子里泡久了，你会发现一个特别有意思的现象：同样是用大模型，有的人每次写需求都要把提示词从头捋一遍，改个场景就得把上下文重新喂一遍；有的人却能像搭积木一样，把拆词、查资料、写摘要、生成报表这些零散动作分装成一个个模块，接到哪用到哪，效率高出一个量级。差距往往就出在一个不起眼的概念上：skills。
我说的skills，不是简历上那种“熟练掌握某某框架”的自我评价，而是大模型智能体场景下一种可复用、可组合、可独立调用的能力封装单元。简单说，它就是一段带明确输入输出契约、有边界、有兜底的“干活技能”，可以被模型按需调用，也可以被你在不同项目之间平移到任何工作流里。
这篇文章我想把围绕skills的一套打法完整拆开：它到底解决什么问题、在什么场景下值得用、怎么写才不算写废、怎么把零散技能沉淀成自己的武器库。全程是实操视角，不聊虚的，适合那些已经在用大模型做自动化任务、搭智能体，或者正打算把自己的工作流改造成“模型为主、人为辅”的开发者看。
1. 技能库的核心设计：为什么单段提示词不够用
1.1 提示词失效的典型时刻
先还原一个很常见的场景。你在某平台的在线对话里让模型帮你写一段Python脚本，它写得又快又好。但当你把同样的需求丢给一个自动化流程去执行时，效果却忽上忽下：有时候它理解对了，有时候它给你返回一段“解释”，就是不给你代码；有时候它把参数名猜错了，有时候它干脆把需求理解成另一个方向的任务。
问题出在哪？在线对话是人机协同的，而自动化流程是机器独跑的。人在场的时候，模型跑偏了你还能话赶话把它拽回来；人一旦不在场，所有歧义就全变成了概率问题。而提示词本质上是一种“非结构化意图表达”，它没有约束输出的形式，没有界定输入的边界，也没有告诉模型“遇到哪种情况你必须停下来”。
Skills想要解决的，恰恰就是这个缺口：把“意图表达”升级成“能力契约”。
1.2 Skills的工程化定义
我在实际项目中给skills定过一个相对严谨的公式，写的时候也推荐你按这个思路去框：
一个skill = 明确的触发条件 + 可校验的输入参数 + 分步骤的执行逻辑 + 标准化的输出格式 + 边界与兜底规则
这五个要素缺一不可。没有触发条件，模型不知道该在什么时候调它；没有参数定义，输入就是一团模糊；没有执行逻辑，模型只能靠“临场发挥”来干活；没有输出格式，下游程序没法直接消费结果；没有边界兜底，一旦输入超纲，整个流程就会挂在半路。
你可以把一个skill想象成餐厅后厨的一道标准菜谱：厨师（模型）不需要每次重新发明菜的做法，只要按照配料表、火候标准和时间节点去执行，出锅的菜就大体稳定。客人（主流程）不需要关心后厨的细节，只要下单时选对菜名，上菜时就拿到预期结果。
1.3 什么时候值得上技能库
不是所有需求都应该做成skill。我见过有人为了“让模型帮我把一句话翻译成英文”这种五分钟能做完的事，专门写了一整套带版本管理的技能文档，这就是典型的用力过猛。
判断一个能力是否值得沉淀成skill，我一般过三个问题：
- 这个能力被调用的频率高不高？每天用十次以上的，值得做；一年用两次的，直接写提示词就行。
- 这个能力的输入输出是否能稳定固化？比如“把一段文本总结成三个要点”这种边界清楚的，适合做；而“帮我参谋一下职业规划”这种开放式的，做了反而别扭。
- 这个能力的失败成本高不高？如果模型自由发挥导致的结果你根本不敢直接用，那就有必要用skill把输出约束死。
对照这个标准，你会发现在智能体场景里，真正值得沉淀的往往都是那些“脏活累活”类的能力：网页内容抓取、数据结构化提取、代码片段生成、文档格式转换、API参数拼装、报告模板填充。这些任务特征明确、重复度高、出错影响大，天然适配技能化改造。
2. 核心结构解析：一个标准Skill的拆解与实现
2.1 目录结构与两个核心文件
一个规范的skill，在我的工程实践里通常占两个核心文件，外加一个可选示例目录：
- SKILL.md：技能描述主文件，包含名称、触发条件、参数说明、执行步骤、输出格式、注意事项。
- scheme.json（或者你习惯的yaml格式）：输入参数的结构化定义，用于校验模型传参是否合法。
- examples/ 目录：存放成功调用的输入输出样例，给模型做few-shot参考。
目录结构不需要复杂，但也别省。把样例单独放一个目录，方便你后续扩充覆盖面，而不是把样例堆在描述文件里变成一坨读不完的长文。
2.2 SKILL.md 的书写顺序
我在写SKILL.md时有一套固定的顺序，这个顺序本身也反映了一个逻辑链路，新手直接照抄结构就行：
第一步：名称定位。给技能起名要直白，最好能做到“模型看到名字就能判断该不该调用”。比如extract_contacts就比info_parser清晰得多。
第二步：触发条件。用一两句话说明什么情况下模型应该调用这个技能。写的时候宁可多写几条边界，也别只写一条主场景。比如extract_contacts，触发条件可以是“用户要求从文本中提取联系方式”“用户提供的文档包含联系人信息且需要结构化”，两条并行。
第三步：参数字典。这里要配合scheme.json一起写。每个参数说清楚类型、必填性、含义、允许的取值范围。出现过“模型把参数名猜错”的坑之后，我习惯在描述里加一句“参数名以scheme为准，不要自行创造字段”。
第四步：执行步骤。这是整个skill的核心，建议写成编号列表，一步步来。步骤之间不能有歧义。写“判断文本是否包含邮箱地址，若不包含则跳过邮箱提取”，就比写“提取信息”要稳定得多。
第五步：输出格式。这一步很多人会漏掉，但它恰恰是自动化场景的生命线。要明确到“用JSON数组返回”“数组元素包含name和phone两个字段”“没有数据时返回空数组”这种颗粒度。
第六步：兜底与异常。什么情况下算“处理失败”、失败时应该返回什么样的占位信息，都要定义清楚。不加这条，模型遇到处理不了的情况时会自己编一个结果，那是灾难。
2.3 scheme.json的参数约束
scheme.json的核心作用就一句话：把模型的自由发挥挡在入口之前。
我见过最有效的一个参考写法是侧重三个字段的：
type：参数类型，限制为string、number、array等基础类型。required：哪些字段缺了就不能执行。description：参数的业务含义和取值样例，这里写得越细，模型越不容易猜错。
配合SKILL.md里的“参数名以scheme为准”这句话，两者组合起来，能让模型的传参错误率大幅下降。实测下来，加了参数约束后，结构化场景下的解析成功率能从七成左右直接抬到九成五以上。
3. 从零开始：把一句话扩展成一个可直接使用的技能
3.1 一个实操案例的完整推演
为了不空谈理论，我拿一个我经常在项目里用到的技能来完整演示一遍：“文章摘要生成器”。
第一步，先定义它的触发条件。这个技能被设计成用来处理“输入一篇长文，输出摘要并拆成关键要点”的场景，核心关键词是“摘要”“要点”“总结这篇内容”。我把触发条件写成了三行，覆盖用户直接要求、用户间接暗示、以及主流程主动调用三种情况。
第二步，定义参数。在scheme.json里，我定义了两个字段：content（必填，string，原始文本内容）和max_points（选填，number，要点数量上限，默认5）。description写得很细：content要传原文，如果用户给的是链接或文件路径，先由其他前置技能把内容抓取成文本，再传进来。
第三步，执行步骤。我把模型的思考过程规定成了四步：先通读全文确定主题；再按逻辑顺序抽取核心信息；然后合并相似项，确保每个要点之间没有重叠；最后按照指定格式输出。每一步都写明了“如果遇到什么情况则跳转到哪一步”，避免模型钻牛角尖。
第四步，输出格式。我选了JSON，结构是{"summary": "一句话摘要", "points": ["要点1", "要点2"], "keywords": ["关键词1", "关键词2"]}。同时在描述里写死了“keywords最多5个，不足以5个时按实际数量输出，不要硬凑”，把模型发挥空间压缩到可控范围。
第五步，兜底。我规定：当content为空或字数少于100时，返回{"error": "content_too_short"}，并附上一句“请提供不少于100字的原文”。这样主流程就能根据error字段快速判断是重试还是换路径，而不会把一段毫无意义的模型胡话当真。
3.2 样例选择与注入策略
SKILL.md之外，examples目录的作用是给模型提供“标准答案感”。我在写摘要技能时放了三个样例，分别覆盖三类典型输入：一篇技术博客、一段采访对话、一份产品说明。每个样例都包含完整的输入参数和对应的输出JSON。
这里有一个容易忽略的点：样例不是越多越好，而是覆盖率越高越好。模型见过技术类文本的摘要写法之后，再遇到“对话类文本要摘要”时就容易发懵。因此三到五个风格差异足够大的样例，远比二十个风格相近的样例更有效。
如果主流程用的是带系统提示词注入的架构，还可以在调用skill时动态决定要不要把样例拼进上下文。上下文长度紧张时，样例可以省掉；模型表现不稳定时，样例则建议全量注入，效果改善很明显。
3.3 与主流程的集成方式
写好skill之后，怎么让它被真正用到，是整个工程的关键一跳。在我的项目里有两种最常见的接入方式：
- 框架原生调用：如果你用的是现成的智能体开发框架，可以直接调用它内置的skills加载接口，框架会自动解析SKILL.md和scheme.json，在模型推理时动态注入。
- 自研动态路由：如果主流程完全是自己写的，我建议走“技能清单预扫描 + 关键词触发”的路线。先把所有技能的名称和触发条件喂给模型，让模型决定“当前用户请求是否应该调用某个技能”，再把对应技能的描述文件加载到上下文。
第二种方式更灵活，但需要额外做好技能清单的长度控制。技能数量一多，描述文件全塞进去会让上下文爆炸。我的处理方法是两级加载：先加载目录（只有名称和触发条件，每行不超过20字），模型决定调用哪个后再加载该技能的完整描述。
4. 避坑与排查：那些文档里不会写的实操教训
4.1 输出格式被模型悄悄改变
这是我在早期项目里踩过最深的一个坑。SKILL.md里明明白白写着“用JSON数组返回”，实际跑起来却发现模型偶尔会输出带markdown代码块包裹的JSON、偶尔会输出json标签的文本，偶尔还会在数组外面包一层对象。解析脚本一跑就崩，定位问题花了很久。
后来解决的核心动作是双层的：一方面在SKILL.md里补了一句话“直接输出JSON，不要使用代码块标记”；另一方面在工程侧增加了一个容错解析函数，先把markdown代码块剥掉再进行JSON解析。两层配合，解析成功率就稳定了。这一条经验几乎可以平移到所有涉及结构化输出的skill上。
4.2 参数误解导致的结果偏移
还有一次，我让模型调用一个“文本分类”的skill，传入的category参数取值范围是"A/B/C"，结果模型传了个"类别A"。原因在于我写description时用了“类别”这个词，模型就自由发挥了。改成“取值必须是A、B、C中的一个，A代表某某，B代表某某，C代表某某”之后，再也没有传错过。
这类问题的根源在于：模型对自然语言的理解是概率性的，你给它留了哪怕一毫米的解释空间，它就可能产生一公里外的误解。因此参数的取值说明必须“枚举式”，不要“描述式”，能写清所有合法值的就逐项列出，列不全的也必须给一个典型示例。
4.3 技能被错误触发造成干扰
某项目里有个技能叫query_database，触发条件写了“用户需要查询数据时调用”。结果用户说“我想问一下这个数据是不是有问题”，模型也把数据库查询技能调出来了，白白执行了一次无意义的查询。
给技能触发条件加一个“负面清单”是更稳妥的做法。比如在query_database的触发条件末尾补一句“仅当用户明确要求查询或检索数据时才调用，遇到数据分析类问题请调用其他技能，不要执行数据库查询”。负面约束能把模型的触发误判率压低一个级别。
4.4 长期闲置的技能开始“夹生”
有一点很容易被忽视：技能库是会被遗忘的。某技能跑得很顺之后，你可能连续三周都没去动它。等到下一次要用时，模型忽然在这个技能上频繁跑偏，而SKILL.md一个字都没改过。
问题往往出在“上下文漂移”上：当前主要任务的上下文风格和这个旧技能的例子风格差距拉大了，模型的风格偏好就被带跑了。此时只需要在examples里补充一个贴近当前使用场景的新样例，效果立刻能恢复。所以我的习惯是：每次在某个新场景下成功执行某技能后，就把这次实际执行记录追加进examples，保持样例库的“保鲜度”。
5. 持续演进：把技能库变成一个可积累的资产
5.1 一周一次的小复盘
技能库不是一次性写好的，而是需要持续生长的。我给自己定的节奏是每周抽十分钟做一轮轻量复盘：这周哪些任务反复让模型干了同样的活但没有走skill？哪个skill在这个月的调用中出错率明显偏高？有没有新出现的参数形态是scheme.json没有覆盖的？
做法很简单，把本周所有实际执行过的模型请求日志翻一遍，按“任务类型”分组，找出出现频次最高的三组，对比技能库里的覆盖情况，缺什么补什么。坚持两三周，你会发现技能库的增长方向会越来越贴合自己的真实需求，而不是靠拍脑袋想功能。
5.2 版本管理的轻量方案
不少人对skill做版本管理时直接上了一个完整的代码仓库，我觉得对大部分个人项目来说没有必要。更轻量的做法是：在SKILL.md头部加一个version字段，每次改动后递增小版本号；同时在examples目录里用日期后缀归档历史样例。
这样做的好处是，当模型忽然跑偏时，你可以快速回退到上一个版本的SKILL.md试一把，定位是“技能描述改坏了”还是“模型本身抽风了”。我在实际项目里用这个土办法，比上重型管理工具舒服得多。
5.3 跨项目复用的平移策略
技能库积累到一定程度后，你会发现它成为一种可携带的个人资产。从A项目迁到B项目，不需要把提示词翻出来重新调，只要把skills目录拷过去，在B项目里重新跑一遍样例，看看哪些技能表现不对，微调一下描述和样例就能用。
这个“平移—调整—稳定”的循环，基本就是我现在的标准工作流。每次进入一个新项目，我花在“让模型听懂我说话”上的时间少了很多，更多精力可以放在业务流程设计本身。
最后再分享一个我个人的习惯：每个skill正式投入使用前，我一定会先在离线环境里用一套固定的测试用例跑一遍。所谓测试用例，其实就是那条技能历史上遇到过的所有异常输入合集。输入一栏是各种会把模型带偏的刁钻问法，输出期望一栏是正确结果。跑完一轮，把失败案例逐个补进SKILL.md的兜底规则里再跑，直到全部通过才敢接进生产流程。这套办法看起来原始，但确实让我的技能库稳定性上了一个台阶。
