项目标题就一个词skills。如果只从字面看很多人会先想到简历里的“技能特长”但做 AI 应用开发的朋友应该能感觉到这个方向现在更多指向的是大模型应用中的“技能包”。我这次想聊的就是如何把一套散乱的功能逻辑沉淀成可复用、可维护、可被智能体自动调用的 skills 能力体系。先说清楚这玩意儿到底解决什么问题你有一个大模型助手它很强但它不会主动按你的方式来干活。它拿到一个问题可能上来就答根本不走你设计好的流程。而 skills 就是给大模型装上的一套“施工图工具箱”告诉它什么场景该调用哪套流程、每个步骤怎么做、需要哪些参数、边界条件是什么。让模型从“有一张嘴”变成“有一双手”。适合谁看正在做智能体应用、写 prompt 工程、或者想把自己重复性工作流程自动化的人。1. 项目整体设计与思路拆解1.1 从 prompt 到 skills这套体系到底在解决什么先回到基本问题平时我们调教大模型最直接的方式就是写 prompt把规则讲清楚把示例放进去。但 prompt 有个天然短板——它是线性的、一次性的。你今天在这段对话里给了它一套处理步骤明天换个会话它全忘了这个功能用在一处想挪到另一个场景复用又得把整段 prompt 重新复制粘贴粘的过程中还得小心改错。而且 prompt 一旦写长模型对关键指令的遵循度会肉眼可见地下降尤其在多步骤任务里做着做着就偏离原路。skills 的思路就是把“知识”和“可执行动作”分开。知识还是靠 prompt 给但动作被抽象成一个个独立的能力模块。每个模块有明确的触发条件、输入参数、执行逻辑和输出格式。大模型像是一个调度中心它根据用户的请求判断该调哪个 skill调用之后把结果整合再回复。这样一来原来一个几千字的巨型 prompt 被拆散成若干个小而专的技能包模型只需要在对应场景读取对应内容上下文窗口的压力大幅减小指令遵循度反而更高。我实测下来同样的任务拆成 skills 之后成功率能从六七成拉到九成以上这是最直观的收益。1.2 为什么要做技能化封装三个关键理由与其说这是一种技术方案不如说是一种工程组织方式的转变。我从实际项目中总结出三个最核心的理由。第一是可复用性。技能一旦沉淀下来就能跨项目、跨场景调用。比如我封装过一个“Markdown 表格生成”技能原本只在数据周报场景里用后来写产品文档、做竞品分析、整理会议纪要全都在调它一套逻辑四处复用不用每次重写。一个团队里A 同学封装了 PDF 解析技能B 同学直接就能在自己的智能体里调用前提是大家都遵循同一套技能规范。第二是可测试性。prompt 写错了很难定位因为它的错误常常是“不够好”而不是“报错了”。技能化之后每个 skill 都有清晰的输入输出边界你可以针对单个技能设计测试用例用标准输入去验证输出是否符合预期。跑挂了能立刻知道是哪个环节的问题而不是在一整段 prompt 里大海捞针。第三是权限与安全边界。大模型直接操作文件、调用外部服务是有风险的而 skills 天然提供了一层封装模型不能凭空执行任意代码只能调用你暴露给它的有限技能。每个技能内部可以加参数校验、加日志记录、加白名单限制可以把风险控制在可控范围内。1.3 技能体系的组成与目录结构设计早期我搭技能体系走过一段弯路把所有东西都塞进一两个大文件里结果维护成本极高。后来参考了多种实现方案逐步沉淀出了一套目前用着很顺的结构。一个完整的技能包通常由一个主描述文件和若干辅助脚本组成。主描述文件负责“告诉模型这个技能是做什么的、什么时候用、怎么用”脚本负责“真正把活干完”。这套结构沿用了大多数开源智能体项目中的惯例核心是这样skills/ ├── skill-name/ │ ├── SKILL.md # 技能描述文件模型主要读这个 │ ├── scripts/ # 可选存放实际执行的脚本 │ │ ├── run.py │ │ └── utils.py │ ├── assets/ # 可选存放模板、参考资料 │ └── config.json # 可选技能参数配置目录是骨架SKILL.md 是灵魂。它承担着“让模型理解技能”的所有工作后续我会专门展开讲它怎么写。脚本是可选的如果你的技能只是做文本格式转换、输出特定结构的内容不碰外部系统那纯靠模型的生成能力就够了不需要脚本。但只要涉及比如读取文件、调用 API、计算数据就一定要通过脚本不要指望模型自己算它算不准。2. 核心细节解析与实操要点2.1 技能清单文件 SKILL.md 的编写规范SKILL.md 是整个技能体系里最核心的存在它的质量直接决定了模型能不能正确使用这个技能。我在大量实验后总结出五个必备块少一个都可能出问题。首先是元信息块一般是 YAML 格式的开头包含技能名称、版本、作者、触发场景描述。其中触发场景描述我建议写得越具体越好不要写“用于数据处理”这种大而空的话要写“当用户提供一份含订单明细的 Excel 或 CSV 并希望计算各区域销售额时使用”。模型判断是否触发技能靠的就是这段语义匹配。其次是输入参数说明这块容易被忽略但非常关键。技能不是凭空执行的它需要从用户的原始请求里抽取变量。你要明确列出每个参数的名字、类型、是否必填、取值范围。比如“数据文件路径字符串必填统计维度枚举值region/product/salesperson选填默认为 region”。参数定义清晰了模型抽取信息的准确率会大幅上升。第三是执行步骤用分步编号的形式告诉模型拿到参数后按什么顺序操作。这一步的价值在于把隐性经验显性化。比如做数据清洗很多隐性规则是“删除重复行”“日期统一转成 YYYY-MM-DD 格式”“金额字段保留两位小数”你不写出来模型就不会主动做。每一条执行步骤都要具体到可以被验证不要出现“根据数据情况适当处理”这种模糊表述。第四是输出格式明确定义结果的结构。是表格是 JSON还是自然语言总结字段有哪些顺序如何我通常都会附一个输出模板或示例模型照着长这个样子就行了省掉它自由发挥的空间。第五是边界与禁用场景说明什么情况下不该用这个技能防止误触发。有时候模型的判断会跑偏给它拉一道护栏比事后纠错省心得多。2.2 技能参数设计让技能可配置可复用参数设计是技能化过程中最考验功力的环节设计得好能应对各种变化设计得死板则换个场景就废了。举一个我实际做过的例子有个技能是生成项目周报早期我固定了模板字段结果每个项目组的周报格式都不一样技能只能给一组人用。后来我把周报模板改成了参数化配置标题格式、汇总粒度、数据维度、语言风格全部抽成参数。调用方在初始化技能的时候传入一份 JSON 配置技能根据配置动态调整输出结构。这样一来同一个技能在不同团队里展示出完全不同的效果底层逻辑却完全复用。除了功能参数还有一个容易被忽略的层面上下文注入的粒度。每个技能运行时你不可能把整个对话历史都塞给它也没必要。要提炼出与本次执行相关的上下文摘要一并作为输入。比如用户说“帮我看看昨天的工单处理情况”技能需要的最小上下文是整个对话历史里提取出来的关键信息块完全没必要知道用户前天问过什么菜谱。这个筛选过程目前可以靠大模型本身来完成你在 SKILL.md 里写明“从对话历史中提取与本技能相关的任务背景形成不超过 200 字的工作摘要”模型会自动做这件事。2.3 常见技能类型与适用场景对照在实践过程中我把技能粗略分成三大类每种的结构设计侧重点完全不同。第一类是信息转换类典型代表是格式转换、文本摘要、翻译润色。这类技能核心是输入输出模板对脚本依赖最低甚至可以不依赖。重点是输出格式要定义到严格比如“摘要必须控制在 150 字以内分成背景、结论、行动建议三段”。第二类是数据提取类比如从文档里抽关键字段、整理表格、生成结构化数据。这类技能必须有脚本配合因为模型的幻觉问题在数据场景下是不可接受的。正确姿势是模型只做语义识别把提取规则传给脚本脚本用正则或其他方式做精确处理结果再给模型去表达。第三类是外部操作类比如调用 API、发送通知、操作文件系统。这类技能最需要安全设计参数校验、权限控制、执行确认一样都不能少。模型提出调用意图脚本负责实际执行执行前必须经过合法性判断。三种技能可以嵌套组合复杂功能可以由多个基础技能拼装而成。一个编排型技能内部可以声明“本技能依赖 file_reader 和 formatter 两个子技能”模型在执行时先调用前者解析文件再调用后者整理格式你不需要在一个技能里把全部逻辑都写完。3. 实操过程与核心环节实现3.1 从零搭建一个技能完整步骤拆解光讲理论容易飘我带着你在本地从零搭一个能用的技能。就拿“CSV 数据统计报告生成器”来说目标很明确输入一个 CSV 文件路径和一个统计维度自动算出各分组的关键指标并以 Markdown 表格形式输出。第一步建目录结构。在工作目录下创建技能包mkdir -p skills/csv_stat/scripts第二步写 SKILL.md 的描述内容。这是权重最高的文件我直接贴一个精简但完整的版本作为模板--- name: csv_stat version: 1.0.0 description: 当用户提供 CSV 数据文件并请求进行分组统计时使用。自动读取文件按指定维度分组计算数量、总和、均值并输出 Markdown 表格。 params: - name: file_path type: string required: true description: CSV 文件的完整路径 - name: group_by type: string required: true description: 用于分组的列名 - name: value_col type: string required: false description: 需要统计的数值列名默认取第一列数值列 --- # CSV 统计技能 ## 执行步骤 1. 使用 python 脚本读取 file_path 指定的 CSV 文件。 2. 检查数据列名定位 group_by 和 value_col。 3. 按 group_by 分组计算每组记录数、value_col 的总和与均值数值保留两位小数。 4. 生成 Markdown 表格输出第一列为分组名后续列依次为记录数、总和、均值。 5. 若分组超过 20 组只展示数量前 20 的组并在表格后附加一句“更多分组未展示”。 ## 输出模板 | 分组 | 记录数 | 总和 | 均值 | | --- | --- | --- | --- | | A组 | 12 | 3456.78 | 288.07 |这个文件之所以写得这么细是因为模型读完之后就能完全清楚自己该做什么、按什么顺序做、最终交什么货。它不需要有创造性发挥的空间技能系统要的就是稳定可预期。第三步写辅助脚本。这里我用 Python 实现一个基础的统计逻辑重点放在参数安全和异常处理上# scripts/stat.py import sys import json import csv from collections import defaultdict def load_data(file_path): with open(file_path, newline, encodingutf-8-sig) as f: return list(csv.DictReader(f)) def compute_stats(rows, group_by, value_col): groups defaultdict(list) for row in rows: if group_by not in row or value_col not in row: continue try: val float(row[value_col]) except ValueError: continue groups[row[group_by]].append(val) result [] for name, values in groups.items(): result.append({ group: name, count: len(values), total: round(sum(values), 2), avg: round(sum(values) / len(values), 2) }) result.sort(keylambda x: x[total], reverseTrue) return result[:20] if __name__ __main__: args json.loads(sys.argv[1]) rows load_data(args[file_path]) stats compute_stats(rows, args[group_by], args.get(value_col)) print(json.dumps(stats, ensure_asciiFalse))脚本写好后你需要在 SKILL.md 里补充一条说明告诉模型如何调用脚本先组装参数 JSON再执行python scripts/stat.py {\file_path\:\...\,\group_by\:\...\}然后解析标准输出。模型不需要搞清楚脚本内部逻辑它只需要学会正确传参、拿结果。3.2 不同运行模式的实现细节技能的执行模式其实有两种我在早期没有区分清楚导致不少技能“能跑但不通用”。一种是纯模型模式适合格式转换、内容生成类技能。模型读完 SKILL.md 直接生成结果不碰任何外部系统。这种模式最省事但要求输出规范极度明确不给模型自由发挥空间。建议在 SKILL.md 中至少给一正一反两个示例好模型照着正例跟同时用反例约束它不要犯的错。另一种是模型脚本模式像刚才的统计技能就是这种。关键点在于“模型只负责语义理解和结果表达中间所有计算都必须交给脚本”。我看到很多人犯的错是让模型“心算”统计数据或者让模型自己在回复里写段 Python 代码执行这都不稳定。正确做法是把数据操作写成固定脚本模型只传递参数脚本执行后返回结构化结果模型再把结果翻译成用户能看懂的话。在执行模式的设计上还有一层要考虑技能之间的调用链。一个主技能可能依赖多个子技能。我一般会在 SKILL.md 里增加一个dependencies字段列出依赖的子技能名。当模型发现当前任务需要多个能力协作时它会先加载依赖技能。3.3 技能调试的完整流程与验收清单技能写完不是终点跑通一次也不代表稳定。我在每个技能上线前都会走一套固定的调试流程。第一步是参数极限测试。先用最常规的输入跑一遍然后用边界值试空文件、只有表头没有数据、单行数据、超大文件、包含空值和特殊字符的脏数据。脚本层面必须有对应的异常兜底模型层面要在 SKILL.md 里写明异常时该怎么回复用户。第二步是多轮对话场景测试。技能不仅要能用还要在上下文被多次打断、夹杂无关询问的情况下被正确触发。我会故意设计几个干扰对话来验证用户先问天气再丢一份文件过来做统计看看模型是否能准确切换技能用户统计到一半说“顺便帮我翻译一下这个句子”看看模型能不能正确处理多任务。第三步是输出一致性验证。同一份输入连续跑五次比对结果差异。如果是纯模型模式千万不要指望输出完全一致你只需要检查关键结构是否稳定字段是否齐全数值是否精确。如果输出格式出现明显漂移说明 SKILL.md 里的说明还不够具体。我给自己定了一个上线验收清单输入输出有明确的参数说明执行步骤可被逐步验证异常场景有兜底回复输出模板有示例已通过至少 10 组测试数据验证。满足这五条技能才算初步合格。4. 常见问题与排查技巧实录4.1 技能不触发的排查思路日常用得最多的问题就是技能写好了但模型就是不调用它就像旁边站着个工具人你手里的工具递过去他都不接。我通常按这个顺序排查先看触发描述写没写清楚。这是最大概率的问题很多人写“用于统计”模型根本不知道什么情况下该用你需要改写成“当用户要求对表格数据进行分析并按指定字段分组汇总时使用”把触发条件具象化。再看是不是被其他技能抢了。如果你同时挂载了多个技能模型的调度逻辑是优先匹配描述最贴近的那个。两个技能描述有重叠它就容易选错。这时候要从描述上做差异化明确划分各自边界。我之前排查过一个问题数据统计技能总是被一个通用数据助手技能截胡后来我把两个技能的描述都加了“场景排除”说明问题立刻解决。还有可能是技能加载顺序问题。多数框架是让模型先在技能目录里做相关性检索再决定加载哪些技能。如果排查完前两项还不行看看是不是技能名太抽象改成与功能强相关的名称比如csv_data_statistics比csv_stat的语义匹配度更高。4.2 运行失败与输出异常速查表现象可能原因排查与处理脚本报错 file not found文件路径传错或相对路径解析失败在 SKILL.md 中明确要求使用绝对路径脚本内补充路径存在性检查数据统计结果明显不对模型自己算了没走脚本强化 SKILL.md 中的脚本调用步骤禁止模型直接给出计算结论输出缺少字段SKILL.md 的输出模板定义不完整补全模板字段并给一个完整示例技能输出偶尔格式漂移上下文过长导致模型注意力分散在 SKILL.md 中强调严格遵循模板同时缩短运行时注入的上下文摘要明明有脚本却被忽略模型判断该场景不需要外部工具检查触发描述补充“此场景必须调用脚本”的强约束语句参数抽取不准参数说明不完整给每个参数补充取值范围和示例值并在描述里写清楚来源这张表是我日常维护技能库的时候沉淀出来的基本覆盖了九成以上的问题场景。遇到不确定的情况优先从“说明有没有写到位”这个方向去查多半能找到原因。4.3 实战中的避坑经验踩坑是最快的成长方式这些坑我都是真金白银试出来的。第一个坑是技能描述里的“价值判断”。早期我喜欢在描述里写“生成高质量报告”后来发现模型会对“高质量”有自己的理解每次输出风格都不一样。正确做法是去掉一切主观形容词把判断标准量化成可执行规则。你要的是“包含背景、数据、结论三个部分总字数不超过 500 字”而不是“写一份高质量的简报”。第二个坑是文件路径和编码问题。CSV 文件有人用 GBK 编码有人用 UTF-8脚本里如果不做兼容就会报编码错误。我的习惯是脚本里优先尝试 UTF-8报错就回退 GBK实在不行再返回明确错误提示。很多看起来是“模型不听话”的问题根源都出在这种底层细节上。第三个坑是技能版本管理混乱。技能是会迭代的改了一版之后模型可能加载到旧版本缓存。我在技能目录里强制要求带版本号遇到行为异常先确认加载版本。另外 SKILL.md 里建议增加“更新时间”字段排查的时候能快速定位是不是用了过期配置。5. 技能能力的进阶扩展思路5.1 从单技能到技能编排构建组合能力单个技能解决单点问题真正体现 value 的是技能编排。拿“竞品分析报告”这个场景举例它本质上可以拆为信息采集技能、数据清洗技能、指数计算技能、报告生成技能。四个技能按照固定顺序串联起来前一个的输出作为后一个的输入。实现方式是在主编排技能里写明流程并声明依赖的子技能。模型拿到“帮我做一份 XX 产品的竞品分析”这个请求后先调用信息采集技能获取数据再调数据清洗技能处理接着算指标最后生成报告。每一步的输出都会暂存到上下文里最终汇总成完整结果。这种编排最大的价值在于灵活调整如果某个环节要替换算法只需要替换对应的子技能编排层的描述完全不用动。可以理解为把一条流水线上的某个工位换个机器人其他工位照常运转。5.2 让技能库随着使用自动迭代到这一步技能已经能稳定干活了但还有一个课题它能不能越用越好我自己做了一个轻量的闭环每个技能执行时都记录输入、输出、模型是否成功完成。定期回放这些记录筛出失败的样本分析原因再把经验教训写进 SKILL.md 的注意事项里。这轮操作下来技能会慢慢变得更“懂”实际业务。比如我有个周报生成技能第一版不知道怎么处理“本周无大事”的情况生成的周报很空洞。后来从失败记录里发现这个模式在技能描述中补了一条规则当任务内容为空时明确输出“本周无重点任务”而不是硬编内容。这个技能后来就很少让人失望了。技能库不是一次性工程它更像一个需要持续施肥的花园。每用一次都是收集数据的机会每修一版都是技能能力的跃迁。把维护技能的机制搭好这套体系才会真正成为你的第二大脑。5.3 团队协作与技能共享规范如果你不是一个人在维护技能库团队协作规范就变得非常重要。我见过最混乱的情况是几个成员各写各的技能同名不同逻辑的包有一堆调用时经常张冠李戴。定得早比定得好更重要几条基础规则分享给你技能命名用统一前缀比如业务域缩写加功能名每个技能必须标注维护人技能变更必须同步更新描述文件里的版本号核心技能变动前在团队内先发变更说明。有了这些基础约定多人协作维护一个共享技能库才能不失控。6. 写在最后回到项目标题本身skills 这两个字承载的东西其实很多。从小处说它是 prompt 工程的进阶形态是让大模型稳定交付的手段从大处说它是人和模型协作方式的一次重构——把你头脑里那些只可意会不可言传的经验固化成模型也能遵循的明确规则。我个人实际操作下来的体会是不要急着把所有功能都技能化先从你最高频、最重复、最容易被模型搞砸的那一两个场景入手完整跑通流程感觉确实稳定可靠了再逐步扩大范围。技能化不是目的它是梳理业务流程、沉淀方法论的过程写完若干个技能之后你会对自己手头的工作有一种前所未有的清晰感。最后再分享一个小技巧每个技能上线前找一位没参与编写的同事帮你读一遍 SKILL.md如果他读完之后能说出“这个技能是干什么的、什么情况下用、输出长什么样”说明描述已经达标如果他一脸茫然那就继续改。好的技能描述应该像一个清晰的交接文档而不是只有作者自己才看得懂的天书。