项目标题就一个词：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='', encoding='utf-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(key=lambda x: x["total"], reverse=True) 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_ascii=False))脚本写好后，你需要在 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，如果他读完之后能说出“这个技能是干什么的、什么情况下用、输出长什么样”，说明描述已经达标；如果他一脸茫然，那就继续改。好的技能描述，应该像一个清晰的交接文档，而不是只有作者自己才看得懂的天书。
