上一期把 Agent Skills 的概念、适用场景和基础搭建方案讲完了，评论区不少朋友都在问同一件事：技能包到底怎么设计才不翻车？多技能之间会不会打架？为什么我写的技能包 AI 就是不调用？这些问题说实话比入门更值得聊。

这篇不铺垫，直接上硬货。我会从架构设计的底层逻辑讲起，然后带着你手写一个完整的技能包，再往上走一步，聊多技能协同、状态管理、版本迭代这些进阶话题。全程用我实际踩坑换来的经验说话，能复现的直接给方案，不能复现的也把原因讲透。

1. 先想清楚：Agent Skills 到底在解决什么

1.1 单体 Prompt 的天花板，你迟早会撞到

很多人是从“给 Prompt 塞更多指令”这条路走过来的。一开始把系统提示词写得越来越长，把各种能力要求、工具说明、输出格式全部堆在一起，结果模型表现反而越来越差。我之前带过一个项目，Prompt 从小 1000 字膨胀到 5000 字之后，每次调用都出现明显的问题：指令互相覆盖、格式要求互相冲突，模型开始遗漏关键执行步骤，输出还偶尔出现幻觉内容。

这里面的底层原因是，大语言模型的注意力是有限资源。你把所有技能说明平铺在一个上下文里，模型根本不知道哪个指令是当前任务优先的。好比一个人同时被三五个领导布置任务，谁都觉得自己说的是重点，结果他只能乱干一通。

技能包的核心思路，就是把“AI 能做什么”这件事从单一大 Prompt 里拆出来，变成一个个自包含、可声明、可插拔的模块。每个技能包负责一个明确的能力域，带上自己的描述、参数定义和执行逻辑。Agent 只需要知道“当前用户意图匹配哪个技能包的描述”，然后把这个模块加载进来用就够了。

1.2 技能包的思维模型：不是装更多，是安开关

一个容易误解的点是，技能包不是给 AI 增加知识库，也不是把更多工具塞进去。它的本质是给 AI “按需启用”能力的一种机制。

我自己常用的一个类比：普通 Prompt 像是给员工发了一本厚厚的规章制度手册，员工要么懒得翻，要么翻错页。技能包则是把每项工作单独做成带开关的流程卡片，上面写清楚“这张卡是干什么的、需要什么材料输入、按下后会执行什么动作”。员工只需要判断当前接到的活儿属于哪张卡，抽出来执行就行。

这种模块化设计带来了三个直接的好处：

1. 上下文瘦身。每个技能包的描述控制在几十到几百字，按需加载，不会长期占据模型注意力。

2. 能力可扩展。加一个新的能力域，不需要改动已有 Prompt 结构，新增一个技能包文件即可。

3. 故障隔离。某个技能包执行报错，不会连累核心对话逻辑，Agent 可以降级处理或转交给其他模块。

从工程实践角度讲，Agent Skills 是把复杂的智能体应用拆解成“核心大脑 + 能力插件”的架构模式。核心大脑负责理解意图、决定调用顺序、做结果归纳；能力插件负责具体的动作执行，比如调用外部 API、处理表格、发送消息、查数据库，什么领域都可以封装。

1.3 我的三条设计原则

踩过几次坑之后，我做技能包基本都遵循这三条规则：

第一，描述大于实现。技能包最重要的部分不是里面代码写了多复杂，而是描述文案写得准不准。描述决定 AI 什么时候会想起它，描述写得模糊，代码写得再好也没用。

第二，参数越严越好。技能包对外接收的参数越明确、越窄，AI 越容易正确填充。一个参数定义得过于灵活，AI 就会各种自由发挥，序列化失败和误传数据的情况会直线上升。

第三，执行必须有兜底。技能包内部要将输入解析失败、依赖服务不可用、结果格式异常全部纳入控制范围，任何一步都可能出问题。Agent 不应该因为一个技能包异常就整体崩溃。

这三条后面会有具体案例支撑，先记住结论。

2. 技能包的核心架构，比你想的更简单也更严格

2.1 一个技能包到底长什么样

标准化的技能包一般由四层构成：

第一层是元信息。包括技能包名字、版本号、功能描述、触发场景示例。这一层的作用是让 Agent 判断“什么时候该用我”，本质上是一个给模型看的路标。

第二层是参数模式。它定义调用技能包时模型必须提供的所有参数。什么参数名、什么类型、是否必填、取值范围。这一层是给解析器用的，保证 AI 传进来的数据能被代码完整接收。

第三层是执行逻辑。真正干活的函数，接收参数模式里定义好的数据，执行具体的操作，然后返回结果。它必须处理异常，并且总是返回结构化的结果。

第四层是注册信息。告诉框架这个技能包声明了哪些权限、需要哪些依赖、能被谁使用。这一层不是运行必需的，但往上走做多技能协同、安全性控制的时候，它是关键。

每一层都有对应的基础结构，下面逐个展开。

2.2 描述即入口：决定 AI “想不想用”你的技能包

技能包的描述文本是模型进行意图匹配的唯一依据，写得好不好直接影响触发率。刚开始写技能包我犯过这个错误：描述写得太宽泛，比如“用于处理数据分析相关任务”，结果 AI 几乎从来不调用它，因为在模型眼里所有对话都可以算数据分析相关，反而失去了指向性。

真正的描述写法，要让模型能直接等价于“用户意图 + 条件匹配”。我的写法模板是：

这个技能包用于：在 [特定条件或者场景] 下，完成 [具体的动作]。

同时提供 3 到 5 个典型触发示例，用自然语言写成：“当用户说‘帮我统计上个月的销售额’时”，“当用户上传了一个 Excel 文件并要求整理时”。这些示例相当于给模型提供了几个瞄点，命中率提升非常明显。

描述还有一个细节要注意：不能把自己能做到的事情描述得超过实际能力。如果你写的描述是“可以完成任意报表制作”，但代码其实只能处理 CSV 文件，模型就会拿着一堆它无法处理的文件来调用技能包，最后全面报错。描述范围宁窄勿宽。

2.3 参数 Schema：AI 和代码之间的合同

参数 Schema 是技能包最容易出错的地方，也是价值被低估的部分。它本质上是你和模型之间的约定：它决定 AI 从对话里抽取什么内容、以什么格式传给执行函数。

以 JSON Schema 为例，设计参数时要遵守四件事：

第一，属性名用清晰名词，不要用缩写。模型拿到一个简称为uid的参数，它会猜测是“用户 ID”还是“任务唯一标识”。直接写user_id就永远不会猜错。

第二，每个字段写描述。很多人在 Schema 里只写类型，不写描述。正确做法是每个字段下面给模型一句话说明，例如“用户想要查询的日期范围，格式为 YYYY-MM-DD 到 YYYY-MM-DD”。模型生成 JSON 时描述会参与，准确率大幅提升。

第三，必填字段要克制。非关键信息全部 optional，必填太多，模型稍不留神就传不齐，执行时频繁报缺参，反而打断流程。

第四，枚举值优先。如果某个字段取值有限，直接列枚举。比如“报告格式只能是 csv、xlsx、json 三选一”，模型在枚举限制下几乎不会传错。

参数 Schema 定义得越严格，后续执行代码越轻松。把时间花在 Schema 设计上，是性价比最高的事情。

2.4 执行器：可靠比花哨重要

执行函数是整个技能包最不性感的模块，却是保障用户体验的核心。一个可靠执行器必须做到这几点：

输入永远假设不可信。即使有 Schema 在前面拦了一道，代码内部依然要校验一次。这属于双保险，因为框架版本升级、模型输出异常都可能把坏数据送到你的代码门口。

错误要被抓干净。API 超时、文件不存在、数据格式非法，每类错误都要有对应的异常处理，最终输出一个可读的错误信息。

返回结构统一。返回值至少包含状态字段和内容字段，状态用来标记成功还是失败，内容承载实际数据。这样 Agent 拿到结果后可以直接判断后续动作，不用做多余的解析分析。

执行器里不要做递归调用。有些技能包执行过程中还想去调用 Agent 本身的能力，比如跑到一半让 Agent 理解一下某个文本再回来，这个一定要避免。技能包写完之后，超时问题会很难排查。

3. 实操：手把手做一个可用的技能包

3.1 先定场景，再写代码

这次我以一个很常见的场景为例：做一个报表生成技能包，功能是接收原始数据文件路径和报表类型，生成对应的 Excel 报表并落盘。

这个场景覆盖了技能包的典型要素：文件输入需要参数定义、数据处理需要执行逻辑、结果返回需要状态判断，还能顺便聊文件权限和路径安全。

整个技能包的一体设计如下：

技能包名称：report_builder
功能描述：当用户提供数据文件并指定报表类型时，生成 Excel 报表
参数定义：

• data_path：必填，字符串，输入数据文件路径
• report_type：必填，枚举，支持“summary、detail、trend”
• title：选填，字符串，报表标题
• output_dir：选填，字符串，输出目录，默认/tmp/reports

3.2 写描述：这一步直接决定技能包命

给这个技术包写描述的时候，我会写成这样：

技能包用于生成 Excel 统计分析报表。当用户提到“做报表”“生成统计表”“汇总数据”等动作，并且能够提供数据文件路径时，优先使用该技能包。 适用场景示例： - “帮我根据 /data/sales.csv 生成一个汇总报表” - “把这份数据做成趋势分析表” - “对销售明细做一个 summary 报表” 不适用场景：用户只是口头描述数据，没有给出实际文件路径时，请先向用户获取文件地址再调用。

注意最后加了一行“不适用场景”，这是很多人忽略但非常有用的技巧。模型判断意图时，能看到正面示例帮你增加触发概率，反面示例帮你排除误触发，整体效果非常明显。

3.3 参数 Schema 和代码实现

参数 Schema 我直接用 JSON Schema 标准，看起来像这样：

{ "type": "object", "properties": { "data_path": { "type": "string", "description": "输入数据文件的绝对路径，支持 CSV 格式" }, "report_type": { "type": "string", "enum": ["summary", "detail", "trend"], "description": "报表类型：汇总报表、明细报表、趋势报表" }, "title": { "type": "string", "description": "报表标题，如未提供则使用文件名作为标题" }, "output_dir": { "type": "string", "description": "输出目录，默认 /tmp/reports" } }, "required": ["data_path", "report_type"] }

Schema 定了之后，执行器代码实现不能简化成几行代码就完了。真实环境里至少要做到数据校验、路径处理、核心逻辑、结果返回四步。框架代码大概长这样：

import os import pandas as pd def execute(params): data_path = params.get("data_path") report_type = params.get("report_type") title = params.get("title", os.path.basename(data_path)) output_dir = params.get("output_dir", "/tmp/reports") if not os.path.exists(data_path): return {"status": "error", "message": f"文件不存在: {data_path}"} if report_type not in ("summary", "detail", "trend"): return {"status": "error", "message": f"未知报表类型: {report_type}"} os.makedirs(output_dir, exist_ok=True) df = pd.read_csv(data_path) if report_type == "summary": result = df.describe() elif report_type == "detail": result = df elif report_type == "trend": result = df.copy() numeric_cols = df.select_dtypes(include="number").columns if len(numeric_cols) > 0: col = numeric_cols[0] result = result.sort_values(col) out_path = os.path.join(output_dir, f"{title}_{report_type}.xlsx") result.to_excel(out_path, index=False) return {"status": "success", "file_path": out_path}

这段代码已经是完善后的版本。很多初学者写的执行器会直接假设参数传进来就有效，文件一定存在、格式一定正确。实际上，模型抽取数据时可能把路径抽错，可能把枚举值写成别的格式，文件可能存在但没有读权限，这些都必须处理。不要以为外面框架做了校验，内部就可以省略。

3.4 注册与测试：一次通过的优化要点

技能包写完会注册到智能体的技能列表里。注册时要注意，不要让技能包互相覆盖。很多框架里技能列表是一个大数组，如果两个技能包 names 相同，后者会覆盖前者，而且这种覆盖没有任何日志警告。

注册后测试，我的习惯是从三个层级各跑一轮：

第一层参数级测试。先绕过 AI，直接调用执行器函数，传入正常参数、缺少必填参数、坏路径，确认返回结构稳定。这层能过滤掉 80% 的问题。

第二层意图级测试。跟 Agent 说各种变体的触发命令，比如“帮我生成一个趋势表，文件在 /data/sales.csv”和“销售数据帮我汇总输出一下”，确认技能包能被触发。这层测的是描述质量。

第三层黑盒测试。模拟用户完整操作，从对话开始到拿到报表文件，确认整个流程的体验顺畅。这层最接近真实使用场景。

实测下来，这个技术包的意图级触发率在第一版就能达到 80% 以上。多数问题出现在参数级测试：模型把枚举值传成了“趋势分析”而不是“trend”。后来我在枚举字段的描述里加了一句“trend 代表趋势分析表”，问题立即消失。这个小事说明，参数 Schema 里每个字段的描述确实直接参与模型推理，值得多写几句。

3.5 排错思路：模型说什么先信一半

调试技能包时，我的判断顺序永远是：先查参数对没对，再查执行器代码，最后才怀疑模型理解错了。

很多人在 Agent 调用技能包失败后，第一反应是去改 Prompt 或者提升模型能力。但实际做下来，80% 以上的问题出在参数和代码的衔接：要么是参数类型不对，要么是执行器自己对格式的假设太严格。

给你一个排查技巧：打开技能包的执行日志，看模型实际传进来的 JSON 长什么样。如果你看到data_path的值是“/data/sales.csv”这种带上下文描述的字符串（比如“用户提供的 /data/sales.csv 文件”），说明模型的参数抽取结果加进了多余的面板文本，这时不用改 Prompt，在参数描述里写明“仅填写路径本身，不要附加说明”，效果立竿见影。

另一个经常出现的是枚举值不一致。模型有时候会传中文、有时候会传英文、有时候会传全角符号。别指望模型自己保持一致，最好在执行器里加一个归一化过程：

report_type_map = { "summary": "summary", "汇总": "summary", "汇总报表": "summary", "detail": "detail", "明细": "detail", "明细报表": "detail", "trend": "trend", "趋势": "trend", "趋势报表": "trend" } report_type = report_type_map.get(str(params.get("report_type", "")).strip().lower())

这个映射表是廉价但可靠的双保险。

4. 进阶玩法：多技能协同和状态管理

4.1 多个技能包一起用时，顺序比并行重要

单技能跑通后，下一个瓶颈很快出现：当 Agent 同时挂了三五个技能包，怎么保证它不乱套？

我的建议：不要过度依赖模型自己选，直接把工作流拆成“管道式”的。你可以在 Prompt 里明确任务流程，让它第一步调用哪个技能包、拿到输出后再传个哪个技能包处理。这样技能包两两之间的输入输出就形成了一条明确的流水线。

举个例子。我有一个数据看板系统，同时挂了数据清洗、图表生成、报表导出三个技能包。模型需要先用清洗包处理原始文件，把清洗后的新文件路径作为参数传给图表生成包，再让图表包把图表路径传给导出包。这一步帮助显著，三个技能包之间的互传参数问题大幅减少。

这里面有个技能包设计上的关键点：每个技能包的输出要“可被下一个技能包消费”。也就是说，输出里面至少包含路径、状态、内容摘要这些标准化字段，使得下一个技能包能进到参数里。

4.2 技能包之间的依赖与冲突处理

技能包之间有可能发生资源竞争，最典型的是文件路径冲突和临时目录抢占。两个技能包同时向同一目录写同名文件，后写者会覆盖先写者，而且没有任何报错。这类问题排查起来极其隐蔽。

我的解决方案是强制每个技能包在执行时生成唯一子目录，用执行时间戳加随机后缀作为目录名。比如：

import time import uuid run_id = f"{time.strftime('%Y%m%d%H%M%S')}_{uuid.uuid4().hex[:8]}" safe_dir = os.path.join(output_dir, run_id) os.makedirs(safe_dir, exist_ok=True)

按实际使用体验来看，这个方案直接消灭了文件覆盖类问题。代价是输出目录变得分散，但我们可以靠统一的索引表去维护每个 run_id 对应的产物路径，够用。

另一种依赖冲突是技能包之间的逻辑前置关系。比如数据清洗包没跑完，图表生成包就拿到脏数据开始画图。这种情况只用描述是管不住的，需要在编排层增加前置条件校验：让图表技能包在执行前检查输入文件是否属于清洗包输出的格式，如果不是则直接返回错误，让 Agent 调整顺序。

4.3 状态管理：技能包不是无状态的，也无所谓

早期我以为技能包应该尽量无状态，每一调用独立处理。做到后面发现，很多真实任务天然需要跨调用状态，比如长时间运行的数据处理、多轮对话里需要记住上一步的中间结果、用户要求“上次那个报表加上环比列再出一版”。

我的做法是引入一个轻量级状态桶：在 Agent 的上下文里固定一个状态区域，用 JSON 结构存储中间变量。技能包执行后可以把需要跨调用保留的关键数据写入这个状态区，后续技能包可以从里面读取。

{ "current_task": { "source_file": "/data/sales.csv", "cleaned_file": "/tmp/cleaned_sales.csv", "last_report_path": "/tmp/reports/sales_trend.xlsx" } }

这种方案的好处是没有引入任何外部存储，不增加架构复杂度，只需要约定所有技能包执行读写状态区的接口。实际上，当前主流 Agent 框架在运行时也会维护类似的执行上下文，我们做的只是把这种约定显式化。如果任务规模再大，执行上下文进一步膨胀，这时候就值得考虑把状态外置到数据库或者对象存储了。但绝大多数场景，一个 JSON 状态桶就足够了。

4.4 版本管理：技能包也要做迭代

技能包不是写完就一劳永逸的。模型一升级，原本触发率很高的技术包可能就踩不着点了；业务逻辑变了，技能包需要跟着改。不做版本管理，改出问题没法回退，排查时成本非常高。

我在自己的项目里用过一套简单但管用的版本方案：

技能包目录结构直接以版本号分层：

skills/ report_builder/ v1/ v2/ data_cleaner/ v1/

注册列表里默认加载最新版本。每次改动技能包，不去原地修改旧版本，而是新建一个 v2 目录。 Agent 跑完一轮完整测试后如果发现问题，改回注册列表里的 v1 就行，全部操作一秒完成。

版本说明文件也建议加。每个版本目录里放一个 CHANGELOG，写清楚这次改了什么、为什么改。这对长期维护非常有帮助，尤其是过两三个月回头调技能包的时候，你会需要的。

5. 常见问题与排查技巧实录

5.1 技能包没被触发的三种“正常”原因

遇到“技能包根本不被调用”的情况，先别怀疑框架，大多数时候原因在于技术包自身。

描述太泛，触发条件不清晰。前面说过，描述的作用是让模型精确匹配。如果你写“用于数据分析”，模型每个对话都能联想到它，反而不触发。把描述收窄到特定场景加示例，会好很多。

描述里带了说明文字，例如“当用户提出需要帮助时使用”，这种近乎万能的条件反而会让模型犹豫。要让模型匹配的是具体条件，比如“当用户提供数据文件路径并要求生成报表时使用”，指向性更强。

与其他技能包描述重叠。两个技术包都响应“做报表”这个意图，模型不知道选哪个，最后可能一个都不选。办法是在各自描述里写清楚分工：一个负责汇总报表，一个负责趋势报表，条件互斥。

5.2 参数传错导致执行失败，看日志而不是猜

参数传错是运行时最常见的一类报错。我见过几种情况：模型把路径字符串里带上了引号；模型把枚举值传成中文；模型把文件名和路径合并传错。

我的建议是：执行日志里把模型传来的完整 JSON 打印出来。第一次跑技能包之前，先准备一个小工具脚本，模拟各种对话输入，专门用来打印模型生成的参数。我在项目里就是这么干的：

python debug_calls.py --input "帮我生成 /data/sales.csv 的趋势报表"

脚本只会打印参数解析结果和注册匹配结果。配合这个工具，我可以快速判断问题出在“参数抽取”还是“代码执行”环节，然后把修复动作精确到对应关卡，而不是盲目改 Prompt。

5.3 技能执行成功但返回结果不符合预期，怎么处理

报错最好排查，最难受的是结果能出来但不对。比如报表生成了，但图表内容明显有问题。这里要区分是模型理解错需求，还是技能包逻辑本身有 bug。

想区分这两者，有一个简单办法：手动调用执行器函数一次，传入你确认正确的参数，看返回值是否正确。如果手动调用正常，说明技能包逻辑没问题，则是模型理解错了需求，此时要优化参数 Schema 描述，把需求的约束条件写清楚；如果手动调用都不对，说明是代码逻辑的问题，直接在执行器里调。

这个办法虽然基础，但现在很多初学者跳过了手动测试，直接对着 Agent 对话排错，非常浪费时间。

5.4 多技能并发时资源竞争和超时的处理

当 Agent 在一轮任务里连续调用多个技能包时，最容易遇到超时和资源竞争。单个技术包执行超过几秒，整体对话体验就会大幅变差。原因往往不是模型变慢了，而是技能包之间在抢文件锁或者共享临时目录。

我建议给每个技能包的执行加上超时控制，比如单次执行最长 10 秒。超过后内部主动返回超时错误，避免长时间无响应。同时把所有临时目录按 run_id 隔离，从根本上避免并发读写冲突。

如果技能包本身需要长时间运行，比如处理一个大文件，建议拆成两步：第一步技能包只做任务登记，立即返回“任务已启动，任务ID 为 xxx”；第二步让 Agent 轮询任务状态接口，拿到完成通知后再继续。这套异步模式在复杂场景下基本没有替代方案。

5.5 高频问题速查表

最后整理一个高频问题速查表，基本涵盖了技能包开发过程中最常见的坑：

我自己做技能包实际跑下来，这些表里的前四类问题占了绝大部分排查工作量。提前把描描述写精准、参数 schema 设计严格，能省掉大半个下午的调试时间。

最后再分享一个小技巧。技能包迭代多了以后，建议定期做一次“描述体检”：把某个技能包的描述文本单独抽出来，让一个陌生的模型只看描述，问它“什么情况下会用这个技能包”。如果它的回答和你设计的触发条件一致，说明描述合格；如果相差较远，说明描述还没有写透。这个体检方法我每隔一两个版本就会做一次，每次都能挖出一些看似没问题、实则语义有偏差的描述段落。

技能包真正成熟的标志，不是技能包数量多，而是每个技能包能被稳定、精准地调用。做到这个水平之后，你会发现智能体的能力扩展变成了一种可预期、可交付的工程能力。