Agent技能包实战：用SKILL.md让大模型稳定执行多步流程

今年做AI Agent应用最明显的感受就是：模型越来越聪明，但活儿不一定干得漂亮。让它聊天、总结、写文案是轻松，可一旦要求它“按一套固定流程走完、再按指定格式交付结果”，它就经常在某个环节给你跑偏。我们团队从年初开始认真对待“技能化”这件事，绕了很多弯之后，把重心落在了一个叫agent-skills的项目思路上。简单说，就是给Agent准备一组可复用的“技能包”，每个技能包含一份操作手册加一组脚本，模型接到相关任务时按手册执行。这篇文章不讲空概念，直接拆解agent-skills里面的设计逻辑、目录结构、实操细节和踩过的坑，给正在做Agent应用或者准备把重复流程交给大模型的团队一个可复用的参考。

1. agent-skills 到底解决了什么问题

1.1 传统Agent工具箱的局限在哪

现在大多数Agent项目都有“工具调用”的能力，本质上就是给模型暴露一批函数：查天气、算个价格、调一下数据库。这套机制解决的是“点状能力”，模型需要什么就调什么，就像给一个新人配上独立的工具，他需要哪个就临时拿哪个。但对稍微复杂一点的任务，问题马上就来了。

比如我要一个“生成销售周报”的流程：先读取数据源，清洗掉异常值，按模板汇总，再输出成指定格式的Excel，最后校验一遍文件是否能正常打开。用传统的function calling做，你得把查数据、清洗、汇总、写Excel、校验拆成五个独立函数，然后祈祷模型每一步都记得按正确的顺序调用、传递正确格式的中间结果。实测下来的感受就是：偶尔能跑通一次，但换一组数据、换一个措辞的请求，它就开始自由发挥。不是你Prompt写得不好，而是“多步流程 + 强约束规范”本身就是传统工具调用不擅长的事。

这里要提一个很多团队忽略的点：大模型在短上下文里执行单步操作非常稳定，但在长上下文里同时管理“流程顺序、数据格式、输出要求、异常处理、业务规范”这五件事时，注意力会被稀释。你会发现它该调用的脚本忘了调用，不该用来凑字段的规则偏偏凑上了。这不是模型变笨了，而是你让它同时承载了太多没有结构化的职责。

1.2 技能包如何把“动作”升级成“流程”

agent-skills的核心思路，是把“某个岗位的整套干活方式”打包成一个自包含的模块。每个模块不是单纯的一堆函数，而是“操作手册 + 脚本工具 + 参考资料”三件套。模型接到任务时，先判断自己需要哪个技能，然后读取对应的操作手册，按手册里的步骤走，需要执行脚本时再调用脚本。

我习惯用一个类比来解释这件事：以前你是在给新同事发一堆零散工具，用时现找；技能包则是给新同事一本《岗位操作手册》，里面写了什么情况该做什么、具体怎么做、做到什么程度算合格，工具箱就挂在手边。模型拿到技能包之后，不再是“我自己想一套流程”去完成任务，而是“按这套成熟流程”去完成任务。这个转变非常关键，因为你在技能包里沉淀的是测试过、优化过、踩过坑之后的稳定流程，而不是每次让模型临时发挥。

用这个思路来做项目之后，有几个很直观的好处。第一，Agent的主Prompt可以保持精简，不用塞一堆行业规则和操作细节。第二，每个技能可以独立开发、独立测试、独立版本管理，像是维护一个小型API库。第三，一个技能能跨项目复用，团队里A项目打磨好的报表技能，B项目直接拿过去就能用。我们后来把同一套技能从月度报表迁移到财务口径报表，只改了几行说明文档，整个迁移成本极低。

2. 深入拆解一个技能包的内部结构

2.1 目录结构与三个核心部件的分工

一个标准技能包，长这样：

skills/ └── excel_report/ ├── SKILL.md ├── scripts/ │ └── generate_report.py └── reference/ └── report_template.xlsx

SKILL.md是整个技能包的大脑，也是给大模型读的操作手册。它解释这个技能在什么场景下用、执行步骤是什么、输出规范是什么、有哪些坑不能踩。scripts/目录放可执行的脚本，是技能的“手”。reference/目录放模型执行复杂任务时需要参考的资料，比如模板文件、样例数据、业务规则补充说明，充当“参考书”。

这套三层结构有一个内在的取舍逻辑：把“描述性知识”放进SKILL.md和reference，把“确定性计算”放进scripts。模型负责做判断和流程控制，脚本负责做精确计算。举例来说，你不可能让模型手动把1000行数据汇总成报表格式，但你可以让模型判断“当前数据源是CSV，符合技能使用条件”，然后调用generate_report.py完成转换。这种分工让模型发挥它擅长的语言理解与任务拆解能力，同时避开它不擅长的机械计算。

2.2 SKILL.md是写给大模型看的产品说明书

SKILL.md的写法与传统技术文档差别很大。传统文档默认读者是人，你会写“本模块用于生成报表”；而SKILL.md的读者是语言模型，你需要写成“当用户请求符合以下条件时，使用本技能；执行时严格遵循以下步骤；如果遇到XX情况，执行YY处理”。

一个可用的SKILL.md，至少包含四个部分：技能识别信息、适用条件、执行步骤、输出规范。技能识别信息写在文件头部的YAML区域，包括技能名称和一句话描述。适用条件和输出规范则直接影响模型能否正确决策，这个部分我建议写得像“准入条件”一样明确。举一个我们在实际项目中用过的桌面端报表技能示例：

--- name: excel_report description: 生成标准Excel报表，支持CSV数据源转换、表头规范化、基础样式设置 when_to_use: 用户要求生成xlsx报表、周报、月报，且提供或可获取到表格数据 when_not_to_use: 用户只是需要纯文本形式的结果，或仅需要简单几句话的汇总分析 --- # Excel报表生成技能 ## 前置条件 - Python 3.10及以上版本 - 已安装 openpyxl 库 - 数据源文件必须为CSV格式，且至少包含 date、channel、orders、sales、margin 五列 ## 执行步骤 1. 先确认数据源文件路径，如果路径含糊，先向用户确认 2. 用 scripts/generate_report.py 生成报表 3. 测试生成的xlsx文件是否可以正常打开 ## 输出规范 - 输出文件名为 report_YYYYMMDD.xlsx - 第一个Sheet名称固定为“汇总” - 表头顺序固定为：日期、渠道、订单数、销售额、毛利率 - 数字列保留两位小数 ## 常见问题处理 - 如果CSV中有空值，统一按0处理并记录到日志 - 如果文件编码不是UTF-8，优先尝试utf-8-sig解码

你可能会发现，这份文档对“人的阅读体验”其实不算特别友好，它更像一份给机器执行的规则声明。这正是SKILL.md该有的样子：它不是给人欣赏的文档，而是给模型看的行为准则。我在实际编写中有一条硬性约束：凡是模型“必须绝对遵守”的内容，放到“输出规范”和“执行步骤”里，用明确的“必须/固定/统一”等词；凡是模型可以灵活处理的内容，才放到描述段落里。这样模型在解析文档时能轻松区别强约束与弱约束。

2.3 scripts和reference怎么配才算顺手

脚本的设计原则可以用一句话概括：做得足够小、足够专、输入输出足够明确。一个技能下可以放多个脚本，但我不建议写一个几百行的“万能脚本”。脚本应该像函数一样，输入是明确命名的参数，输出是确定格式的结果。比如generate_report.py接受一个输入CSV路径、一个可选输出路径，成功时打印生成路径，失败时打印清晰的错误信息并返回非零退出码。这样模型能根据脚本输出自行判断“接下来该干什么”。

reference目录我通常用来放“模型可能需要查但不需要全部读入上下文”的资料。比如一个业务技能涉及十几种内部报表字段的口径定义，一次性全塞给模型会占用大量上下文窗口，影响它对主任务的注意力。正确的做法是：在SKILL.md里写“如果遇到字段口径问题，查阅reference/field_definitions.md”，让模型按需去读。这相当于给模型一个“工具箱里的参考书”，只在需要的时候翻开，而不必从头背到尾。

3. 从零搭建一个报表生成技能：完整实操记录

3.1 需求定义与验收标准先行

我们实际操作时会先写一段“需求定义”，把它当成技能的规格说明书。这里用销售周报生成技能举例。需求定义如下：用户提供一份包含原始销售记录的CSV数据，Agent需要把数据清洗后生成为标准Excel表格，要求格式统一、字段规范、文件可正常打开。验收标准有三条：第一，输出文件名为report_YYYYMMDD.xlsx，日期取当天；第二，Excel中第一个Sheet名是“汇总”，表头依次为日期、渠道、订单数、销售额、毛利率；第三，用测试CSV跑通后，文件用Excel或WPS打开不报错，且每列宽度可读。

很多时候项目做到一半出问题，回头一看都是需求定义阶段没抠细节。比如“输出文件可正常打开”这一条，听上去很基础，但真到CSV带编码问题、字段带小数点精度问题的时候，少一个校验环节就会让模型产出一个打不开或者打开后乱码的文件。所以我把验收标准这一步看得很重，每一项都是后面测试的检查点。

3.2 编写SKILL.md与脚本的技术细节

SKILL.md按照前文的结构写好后，脚本这边我给出了一个精简但足够支撑流程的实现。核心逻辑分成三块：读取并解析CSV、格式化数据、写入Excel并设置基础样式。

#!/usr/bin/env python3 """generate_report.py - 根据CSV数据生成标准Excel报表""" import csv import sys from pathlib import Path from datetime import datetime from openpyxl import Workbook from openpyxl.styles import Font, PatternFill, Alignment from openpyxl.utils import get_column_letter HEADERS = ["日期", "渠道", "订单数", "销售额", "毛利率"] def load_csv(path: Path): rows = [] with open(path, encoding="utf-8-sig") as f: reader = csv.DictReader(f) for row in reader: rows.append(row) return rows def format_rows(rows): result = [] for r in rows: result.append([ r.get("date", ""), r.get("channel", ""), int(float(r.get("orders", 0))), round(float(r.get("sales", 0)), 2), round(float(r.get("margin", 0)), 2) ]) return result def write_excel(rows, output_path): wb = Workbook() ws = wb.active ws.title = "汇总" header_font = Font(bold=True, color="FFFFFF") header_fill = PatternFill("solid", fgColor="4472C4") for col, header in enumerate(HEADERS, 1): cell = ws.cell(row=1, column=col, value=header) cell.font = header_font cell.fill = header_fill cell.alignment = Alignment(horizontal="center") for r, row in enumerate(rows, 2): for c, value in enumerate(row, 1): ws.cell(row=r, column=c, value=value) for i in range(1, len(HEADERS) + 1): ws.column_dimensions[get_column_letter(i)].width = 14 wb.save(output_path) print(f"报表已生成: {output_path}") if __name__ == "__main__": input_csv = sys.argv[1] output_xlsx = sys.argv[2] if len(sys.argv) > 2 else f"report_{datetime.now():%Y%m%d}.xlsx" data_rows = format_rows(load_csv(Path(input_csv))) write_excel(data_rows, output_xlsx)

脚本本身不需要复杂，关键在于它和SKILL.md的约定保持一致。CSV列名date、channel、orders、sales、margin是谁定的？是SKILL.md里约定的。输出表头“日期、渠道、订单数、销售额、毛利率”是谁定的？也是SKILL.md里约定的。这说明脚本不是独立的程序，它是整个技能流程的一个环节，它必须严格遵循技能包内部定义的接口契约。开发过程中，脚本处理的是“确定性逻辑”，而模型处理的是“判断和调度”，两边边界越清晰，整个技能越稳定。

3.3 与Agent框架集成后的实测情况

有了技能包之后，还需要把它注册到Agent的技能列表里。这一步在实现上比较简单，Agent启动时扫描skills/目录，提取每个技能的name和description，生成一份索引交给模型。模型拿到用户请求后，根据描述判断该调用哪个技能；一旦命中，再把完整的SKILL.md内容加载进上下文并指示模型执行。这种“先看列表、后读全文”的设计，是为了避免开头就把所有技能文档灌进上下文，毕竟一个大项目的技能包可能有十几个，全部塞进去会稀释注意力。

我们做了三轮实测。第一轮，给模型一句请求“帮我把今天的销售数据做成周报Excel”，模型正确选择了excel_report技能，并按SKILL.md里的步骤完成了报表生成。第二轮，把请求改成“用数据算出周销售额，发我个总结”，模型判断这是纯汇总分析需求，没有调用Excel技能，直接给出了文字结果。第三轮，故意给一份列名不完整的CSV，模型的处理是先检查到了缺失列，然后按SKILL.md里的“常见问题处理”规则向用户确认，而不是自作聪明地用假数据填充。这三轮正好分别验证了技能命中、技能拒绝、异常处理三个关键行为，整体表现符合预期。

4. 落地过程中遇到的典型问题与排查实录

4.1 SKILL.md写太长，模型反而抓不住重点

我们第一次写技能时，生怕模型看不懂，把背景说明、业务逻辑、历史变更、参考案例全写了进去，成品大约有300行。一测发现，模型经常忽略最后的输出规范，生成的Excel字段顺序是乱的。排查后发现一个规律：模型对文档开头和结尾的内容注意度较高，中间夹着的信息容易被略过。解决办法非常简单：把必须遵守的规则压缩到80行以内，并把“输出规范”和“执行步骤”这两个最强约束的章节放在文档最核心的位置，一大段背景说明挪到reference目录里去，需要时再查。

4.2 输出格式不稳定，生成的Excel在边界条件下打不开

早期我们还遇到过一类问题：脚本逻辑没问题，但测试数据里某些订单数字段为空，int()转换直接抛异常，导致报表生成中断。模型在遇到这类异常时，如果SKILL.md中没有预设处理方案，就会自己“想办法解决”，比如用空字符串替代数字，结果产出的Excel打开后表格样式混乱。后来我们在SKILL.md里明确写了“CSV中有空值时，统一按0处理”，同时在脚本中以容错方式实现，模型和脚本双保险，输出才稳定下来。这类问题本质上不是技术实现难，而是“异常分支没有在技能定义阶段想清楚”。写SKILL.md时，一定要把可能出现的脏数据情况、失败重试方案、无法处理时的用户反馈策略一并写进去。

我用一张表来整理这次排查中比较高频的问题，方便团队查阅：

4.3 技能匹配冲突：最隐蔽的坑

技能多了以后，会出现一个新的问题：用户请求同时命中两个相似技能。比如我们有“销售周报生成”和“运营日报生成”，两个技能的description都包含“生成报表”，模型可能随机选了一个，结果输出格式不符合业务预期。这类问题排查起来很痛苦，因为不是每次必现，是概率性的。

解决思路是给每个技能的SKILL.md补充场景关键词，让描述之间形成明显的区分带。同时要在when_to_use和when_not_to_use里写清楚“排除性”条件。比如销售周报技能里写明“仅当用户明确提到销售、订单、渠道时使用”；运营日报技能里写明“不适用于销售口径数据”。这样一来，模型可以根据用户请求里的业务关键词做出更确定的判断。另一个辅助手段是把高频场景的示例话术直接写到description里，比如“适用于：帮我把今天的销售数据做成周报”，这明显比“生成报表”这类抽象描述更容易让模型命中。

4.4 上下文占用高，多技能连调时注意资源分配

另外还有一个容易被忽视的问题，就是多个技能连续调用时的上下文管理。比如用户先要求生成周报，再要求把报表通过邮件发送出去，这就涉及两个技能。每个技能加载SKILL.md和脚本说明都会占用上下文，连着加载两份文档，主任务的注意力会被分散。我们的做法是在两个技能环节之间增加一个“任务状态摘要”，让模型用一段简短文字记录当前已完成的任务、生成的文件路径、需传递给下个技能的参数，然后释放掉前一个技能的完整文档再加载下一个。这个“摘要切换”的机制，在长链路任务中非常管用。

5. 团队化技能库建设与进阶玩法

5.1 一套可落地的技能评审流程

当技能从一个扩展到十几个之后，就面临和代码库一样的管理问题：谁来维护、怎么保证质量、如何避免别人改坏了你的技能包。我的建议是，把技能当成API来管理。命名规范上，统一用“动词_对象”的结构，比如fetch_user_list、generate_excel_report，避免起一些玄乎的名字。评审流程上，新增技能至少要过三关：第一关是需求确认，确认场景真实且重复度高；第二关是技术评审，看脚本边界是否清晰、SKILL.md的约束是否可执行；第三关是灰度验证，先用20条测试请求跑通过，才允许接入正式环境。

版本管理方面，我们直接在SKILL.md的frontmatter里加了version字段，任何改动都更新版本号，并且保留一份变更记录。这样出问题时能快速回滚。有一点值得强调：技能包的修改影响面比普通代码更大，因为它是直接作用于模型行为的东西。你改一行描述，模型对技能的理解可能就变了，所以技能改动要走单独的测试流程，不要顺手改完就上线。

5.2 多技能协同与更远的编排思路

技能真正发挥威力，是多个技能串成一条流水线的时候。还是以报表加邮件为例：技能A负责从数据库导出CSV，技能B负责把CSV变成Excel，技能C负责把Excel作为附件发送。每个技能保持单一职责，技能之间通过明确的任务状态来衔接。这种设计让单个技能容易测试，也让整个流水线可以灵活调整顺序。我们在实践中还尝试过让一个技能内部引用另一个技能的脚本，效果也不错，但前提是两个技能的接口说明都足够清晰，否则模型容易在中间步骤上“迷路”。

回到这整套思路的起点，我最大的体会是：不要把Agent当成全能执行者，要把它当成一个“会阅读手册并严格执行的老师傅”。你的职责是把老师傅的手册写好、工具备好、边界划好。agent-skills解决的不只是“让模型学会一个新任务”，更是“让一个已经会做很多事的模型，稳定地做对你指定的那件事”。这个转变，比再调多少次Prompt都重要。先把团队里最高频的三个重复流程技能化，跑通一个完整闭环，你就会明显感觉到维护成本和出错率同时降下来了。