从Prompt膨胀到技能库：Agent Skills设计、路由与工程实践

最近半年，我一直在折腾"agent-skills"，也就是智能体技能体系。最开始搭Agent项目时，我的做法和大多数人一样：把所有能力说明、约束规则、执行逻辑全部塞进系统提示词。结果Prompt膨胀到一万多字，模型开始答非所问，该调工具时不调，不该调时瞎调。后来做了好几轮重构，才彻底想明白——问题的根源在于"技能"没有被独立建模，所有知识像一锅粥一样糊在模型面前。

如果你也在做Agent相关开发，或者正准备给现有Agent增加新能力，这篇文章会比较有用。我会把agent-skills的核心理念、技能结构怎么设计、路由和编排怎么做、以及我在生产环境里踩过的坑和优化方案，一次讲清楚。内容不针对某个特定框架，偏向通用方法论，但示例能直接落地。

1. 从"万能提示词"到"技能库"：Agent Skills解决的真问题

1.1 为什么传统Prompt工程在复杂任务前会失效

先说一个我亲历的场景。去年我做一个面向销售团队的助手Agent，需求是：能根据客户对话记录提炼重点、能写跟进邮件、能查询CRM里的客户数据、能自动生成周报、还能在特定场景下调外部API更新商机状态。

一开始我把这五类能力全部写成指令，塞进system prompt。前两周模型表现还行，但一旦任务变复杂——比如"先查一下这个客户上一季度的采购记录，然后结合最近的沟通纪要，生成一封跟进邮件"——模型就开始乱套。它有时会跳过查询步骤直接编数据，有时会用一个过时的邮件模板，有时干脆在回复里输出一大段'我正在处理'的废话。

这类问题的根源有三个：

第一，上下文窗口有限。所有指令、示例、约束全部放在Prompt里，模型真正能用到的"注意力"被稀释了。指令越多，冲突越多，模型越不知道优先级。

第二，职责边界模糊。Prompt里的指令是"描述性的"，不是"程序性的"。模型需要自己理解"什么时候该做什么事"，这对LLM来说是极高的认知负担。

第三，无法单独迭代。想改某个功能，必须动整段Prompt，牵一发动全身，测试和回归的成本都很高。

所以，业界的共识逐渐转向一个更工程化的思路：把Agent的能力拆成一系列独立的"技能"（Skills），每个技能包含自己的描述、输入输出契约、执行逻辑和资源依赖，由Agent在运行时按需加载和调用。这就是agent-skills的起点。

1.2 一个Agent技能到底长什么样

一个技能不是单纯一个函数，也不是一段Prompt。它在实际工程里通常是一个自包含的模块，包含以下几个部分：

• 元信息（Metadata）：技能名字、用途描述、适用场景、不适用场景、触发条件。
• 执行逻辑（Implementation）：一段可执行的代码、脚本或指令模板，负责实际把事情做完。
• 输入输出契约（Contract）：输入参数的schema、输出结果的格式约定。
• 资源依赖（Dependencies）：技能运行需要的外部工具、API、数据文件、模型配置。
• 示例与边界条件（Examples & Edge Cases）：哪些情况该用、哪些情况不该用，给出正反示例。

举个例子，一个"客户信息摘要技能"的目录结构可能是这样：

sales_summarizer/ ├── SKILL.md ├── summarize.py ├── requirements.txt └── assets/ └── summary_template.md

SKILL.md是这个技能的门面，负责让Agent知道"我是什么、我在什么时候有用"。summarize.py是真正的执行体。assets目录存放技能运行所需的模板、静态数据等。

这里的关键点在于：技能是Agent能力的原子单位，但不是最小代码单位。一个技能内部可以调用多个工具、组合多个步骤，对外部只暴露一个清晰的调用接口。

1.3 技能与工具、插件、工作流的边界

很多刚开始接触agent-skills的朋友会把"技能"和"工具""插件""工作流"这几个概念搞混。我花一张表把它们捋清楚：

它们的核心区别在于决策权归属。工具不会思考"该不该调用我"，它只负责执行；技能则自带"使用说明书"，让模型能判断何时调用、如何调用；工作流更进一步，把多个技能的调用顺序也固化下来，减少模型的自由发挥。

理解这个边界很重要。我见过不少团队把工具直接当技能用，结果Agent不知道什么时候该调，或者调用后缺少必要的上下文校验，错误率居高不下。工具是零件，技能是组件，工作流是流水线。

2. 技能设计的核心架构：输入契约、执行逻辑与观测反馈

2.1 技能定义的统一Schema

既然要让Agent在运行时动态判断"要不要加载某个技能"，技能的定义就必须结构化、可解析。这里我推荐一个通用的Schema设计，不管底层用哪种Agent框架，都能套用。本质是一个YAML或JSON文件加上对应的执行目录：

name: sales_summarizer description: > 根据客户对话记录和交易数据生成结构化摘要。 适用于销售对客户进行全面回顾、准备跟进或交接场景。 不适用于生成营销文案、对客户进行情感分析。 triggers: conditions: - "用户要求总结客户沟通历史" - "进入客户详情页需要概览" - "周报中需要提取客户关键事件" forbidden_conditions: - "只涉及单次简短回复，不需要长期上下文汇总" - "用户明确要求原文翻译" inputs: customer_id: type: string required: true description: "CRM系统中的客户唯一标识" include_metrics: type: boolean required: false default: false description: "是否包含交易金额、成交周期等指标" outputs: summary: type: string description: "结构化摘要文本，含客户阶段、近期动态、下一步建议" execution: runtime: python3 entrypoint: summarize.py timeout_seconds: 30 dependencies: tools: - crm_query_api - embedding_search models: - type: llm name: default_main_model max_tokens: 2000

这套Schema有几个设计细节值得注意：

• description要写"什么时候有用"，更要写"什么时候别用"。很多技能失效就是因为描述写得太大太泛，模型什么都往上靠。
• triggers.conditions可以给模型一个启发式列表，但不应该被当作硬性规则。它的作用是降低模型的判断成本。
• execution.timeout_seconds必须有。生产环境里技能可能因为外部API慢、模型响应长而卡住，没有超时机制会拖垮整个Agent任务。
• dependencies.tools是显式声明清单，建议在框架层做依赖预检查，技能加载前就确认所有工具可用，避免运行时才报错。

这个Schema风格参考了目前业界比较流行的SKILL.md组织方式，但做了一点整合。核心原则是：一个技能要能够让一个"没有读过代码的人"（或者模型）仅凭元信息就准确判断出它的能力边界。

2.2 技能内外的状态管理

技能不是无状态的纯函数，尤其在Agent场景里，技能的运行通常依赖会话上下文、业务数据和外部系统的状态。我习惯把状态分成三类：

• 技能内部状态：技能执行过程中产生的临时变量、中间结果、缓存。例如摘要技能在分析过程中生成的关键词列表。这类状态生命周期短，技能结束就应该释放，不要污染外部。
• Agent运行状态：整个会话的上下文、用户目标、已执行步骤的记录。技能作为Agent的一部分运行，需要能读取这部分状态，但原则上只读，不能随意改写人设和目标。
• 业务系统状态：CRM里的客户数据、订单状态、工单流转节点等。技能通常会通过API去操作这些数据，这里的关键是操作要有审计和回滚语义。

我踩过的坑是：早期设计"销售周报技能"时，把周报模板和客户阶段判定逻辑直接放进了技能的全局配置里，结果A客户的周报生成后状态残留，B客户接着生成时，"当前周报"还是A的。后来规范了状态管理——

• 技能内可变的中间数据，统一放在临时目录或内存对象中，技能结束即销毁；
• 涉及外部系统的写入操作，必须在执行前做权限校验，执行后写审计日志；
• 会话级上下文只通过显式参数传入技能，不靠隐式全局变量。

这么做以后，多轮对话中的技能复用稳定了很多。特别是并行场景，多个技能实例同时运行，状态隔离做不好会出一堆莫名其妙的bug。

2.3 技能的失败处理与重试语义

任何技能都会失败。我在设计技能时必问自己一个问题：这个技能失败后，Agent应该怎么办？常见情况有三种：

• 可重试型：上游API超时、网络抖动、模型限流。这种情况适合指数退避重试，通常重试2-3次即可。
• 可降级型：技能依赖的核心服务不可用，但有一个简化替代方案。比如实时CRM查询失败，可以用本地的缓存副本，但要在结果里明确标注"数据可能不是最新"。
• 不可恢复型：输入参数错误、技能逻辑缺陷、依赖服务明确返回业务错误。这种情况不要傻重试，应该把错误信息完整返回给Agent，让它决定是换一个技能还是直接回应用户。

我在技能Schema里增加了一个failure_policy字段，用来告诉Agent如何处理错误：

failure_policy: retry: max_attempts: 2 backoff_seconds: 5 fallback: skill: customer_data_cached_reader on_failure_message: "实时数据暂时不可用，已使用本地缓存，数据更新时间：{cache_time}"

多说一句：对LLM来说，"技能失败"不是一个异常，而是它决策链路上的一个分支。不要把失败信息藏着掖着，更不要为了好看而包装成成功。透明地告诉模型"这次技能调用失败了，原因是……，提供了降级数据"，模型往往会做出更合理的下一步判断。

3. 技能路由与组合：让Agent学会在正确时机调用正确技能

3.1 从LLM函数调用到技能路由的演进

技能体系能不能发挥价值，很大程度上取决于Agent能不能在正确的时机选择正确的技能。最早的方案是单纯依赖LLM的function calling——定义一堆函数，让模型选出要调用的那个。这个方案在小规模场景里能跑通，但规模一大就出现几个问题：

第一，函数名和描述是唯一的线索，当技能库超过几十个，模型的选择准确率会明显下降。第二，函数参数必须提前定义好，动态能力弱。第三，模型经常"自作主张"给函数加参数，参数校验非常痛苦。

后来我转向了"技能注册表 + 语义匹配"的路子。思路是：把每个技能的结构化描述全部存入向量数据库，当Agent收到任务时，先做一次语义检索，找出Top K个候选技能，再把它们的完整描述注入给模型，让模型做最终决策。这比把几十个技能描述全塞给模型要省token，准确率也更高。

再往后，我意识到实际生产里还需要一层前置路由规则。有些调用关系是确定的、不应该交给模型去"猜"。比如用户输入敏感词时应该直接走安全审查技能，这属于规则强约束。于是我的最终架构变成了三层：

1. 规则层：固定逻辑强制路由，比如敏感词、法律法规要求、固定业务流程节点。
2. 语义层：向量检索+相关度排序，把候选技能范围缩小到5个以内。
3. 模型层：让主LLM基于技能完整描述做最终调用决策，并生成参数。

这三层配合下来，"技能幻觉"（模型在不该调用的时候调用）的概率大大降低。一个生产可用的Agent，不能纯靠模型自己发挥，也不能纯靠机械规则，两层或三层的混合路由是目前我觉得最踏实的方案。

3.2 技能组合的编排模式

单个技能只能解决单一问题，真实的用户任务往往是多个技能协同的结果。我在项目里总结了几种常用的编排模式：

• 顺序执行（Pipelining）：上一个技能的输出是下一个技能的输入。比如"数据清洗技能"做完后，把清洗结果传给"数据校验技能"，通过后再交给"报表生成技能"。这个模式最直观，但需要处理好中间结果的传递格式。
• 并行扇出（Fan-out）：一个任务分解成多个独立子任务，同时调用多个技能，最后汇聚结果。比如"客户画像分析"可能同时调用"交易数据分析技能""沟通纪摘要技能""舆情监控技能"，三个技能互不依赖，并行执行，最后把三份输出汇总成一份画像。
• 条件分支（Branching）：根据前序输出决定后续走哪条路。比如"客服工单分类技能"把工单分为"技术问题"和"财务问题"，不同分类走不同的处理技能。
• 错误回退（Fallback）：主技能失败时，切换备用技能。这和前面讲的失败策略挂钩。

编排时最需要注意的，是每个技能的输入输出都要有稳定的Schema。我见过很多项目在单技能上做得很好，但组合时因为两个技能的"接缝"对不上，跑一次改一次。解决方案有三种：

• 定义统一的中间数据格式（比如统一的JSON结构），所有技能都遵守；
• 在编排引擎里加一个"适配层"，负责转换不同技能之间的输入输出；
• 靠Agent模型自己"翻译"，但成本高且不稳定，只建议在复杂宽泛的任务里用。

3.3 上下文记忆与技能调用的配合

技能调用不应该是"断头操作"——调完就完，什么都不留。一个好的Agent应该把每次技能调用的上下文、中间结果、以及最终结论都沉淀下来，供后续技能复用。

比如，用户问"帮我分析下这个客户的续费风险，然后写一封挽留邮件"。这个任务会涉及两个技能："续费风险评估技能"和"邮件撰写技能"。第二个技能天然需要第一个技能的分析结果。如果两个技能各自为政，第二个技能还得重新去CRM拉一遍数据，浪费不说，还可能因为口径不一致生成内容错误。

我会用"会话临时记忆库"来解决这个问题。具体做法是：每个技能在执行后，把产出物（结构化数据、文本摘要、图表路径）追加到Session Memory中，并打上语义标签。后一个技能调用时，可以先用语义检索从记忆库里捞相关上下文，作为自己的输入补充。

这个过程看似多了一次检索成本，但换来的好处是——技能之间第一次有了"递进"感。用户会觉得这个Agent确实"记得"上一步在干什么，而不是每次都在失忆状态下重新开始。

4. 实战落地中的坑与优化

4.1 频繁出现的"技能幻觉"问题

"技能幻觉"是我在agent-skills落地过程里最头疼的问题，没有之一。它的表现有三种形态：

• 误调用：不需要某个技能时，模型调用了它。比如用户只是闲聊问"你觉得这个功能怎么样"，模型却调用了"情感分析技能"。
• 漏调用：该调用的没调用。比如用户明确要求"生成一份PDF格式的报告"，模型却直接输出了一段Markdown文本。
• 错调用：需要A技能，模型却调了同类的B技能。比如技能库里同时有"英文邮件润色"和"中文邮件润色"，模型把中文邮件丢给了英文润色技能。

排查根因后，我发现大多数技能幻觉问题出在技能描述质量太差，而不是模型能力不行。描述写得太宽泛，是所有技能幻觉的源头。像"分析用户情绪"这种描述，几乎可以在任何对话场景里被触发；但如果你写成"仅当用户文本长度超过100字且包含明显的正面/负面情绪词时调用，用于客服质检场景"，误调用率立刻降低一大截。

所以我给团队的硬性要求是：每个技能的description必须包含两部分——"何时使用"和"何时禁止使用"。并且要做"对抗测试"，专门准备一批不该触发该技能的对话样本，定期回归验证，一旦发现模型误调用，优先检查描述是否需要收紧。这个过程必须像写单元测试一样日常化。

4.2 技能复用与版本管理

技能库扩大之后，版本问题开始让人头大。最典型的冲突是：同一个技能，A项目依赖v1，B项目已经升级到v2，两者接口不兼容；结果你升级了技能文件，A项目第二天就报错。截图里那种"更新了一个技能导致三个Agent崩溃"的场面，我经历过不止一次。

我现在的做法是：

• 技能目录里的SKILL.md头部增加version字段，遵循语义化版本号（MAJOR.MINOR.PATCH）。接口不兼容时必须升MAJOR版本。
• 引入技能注册中心，统一管理技能元信息和版本索引。Agent启动时按注册中心里的"锁版本"，不会直接用最新的未验证版本。
• 每个技能配一个回归测试集，包含10-20个典型输入，覆盖成功路径、边界路径、失败路径。CI/CD里任何技能改动必须跑通测试集才能发布。

关于"技能该不该复用"，我也有个反直觉的经验：在技能库前期，宁可多做一些重复的小技能，也不要一开始就设计"万能技能"。通用性越强的技能，描述越难写得精确，越容易被误调用。先做针对特定场景的窄技能，跑通、测试、沉淀，等积累了足够的模式和抽象之后，再回头做整合。过早抽象是技能库项目最大的内耗来源。

4.3 性能与成本的平衡

技能化改造一开始注定会更烧钱、更慢，这点要有心理准备。每次技能调用，本质上多了一次函数调用+可能的语义检索+模型推理的开销。我的优化思路分几个层面：

• 技能描述瘦身：SKILL.md里description控制在150字以内，只保留决策关键信息。长解释性内容放进内部的docs，不参与模型路由决策。
• 局部用小模型：技能内部如果只是做分类、抽取、格式化这类任务，不必调主模型。用一个7B/14B的小模型完全够。我实测过，某些结构化抽取任务，小模型+良好提示词的准确率和大模型差距在2%以内，但成本和延迟只有大模型的五分之一。
• 冷热技能分层：不把全部技能丢给语义检索。将高频技能做"热加载"，常驻内存或预先注入；低频技能才走向量检索。这样能显著降低检索耗时。
• 结果缓存：对幂等的技能调用结果做缓存。比如"分析某客户上一季度订单结构"这类查询，数据本身不常变，可以缓存30分钟。注意缓存必须带参数哈希和时间戳，避免串数据。

有一次我把一个周报生成任务从纯Prompt方案改造成技能方案，单次任务的token消耗反而下降了40%。原因是Prompt方案需要把大量的规则和背景知识反复塞进上下文，而技能方案把这些知识固化在技能内部，上下文里只需要传递关键参数。这是技能化改造被低估的一个收益：用结构化换token。

5. 走向技能生态：从私有技能库到共享技能市场

5.1 技能的可移植性与标准化

如果所有技能只能在某个框架内部运行，那技能库的价值就打折了。我心里一直有一个目标：把技能当作可以流动的资产——在A框架里写的技能，稍微改改就能在B框架里用；团队里开发好的技能，能力认可能复制到另一个业务线。

目前行业里还没有统一的强制标准，但已经出现了通用模式的雏形。核心做法是：

• 技能的主定义文件用Markdown描述（SKILL.md），用YAML front matter承载元信息，这样既能人读、又能机读；
• 技能的输入输出用JSON Schema定义，不绑定任何编程语言；
• 技能的执行代码尽量做成纯函数式，对外依赖通过环境变量注入；
• 技能的资源文件（模板、数据集）统一放在assets目录下。

只要遵守这几条，同一个技能目录结构就能被不同框架的加载器识别。我在内部做了一个简单的转换器，能把通用格式的技能自动转成LangChain、AutoGen和自研框架三种格式，虽然还不是全自动，但已经把迁移成本降低了80%。

这里有个很现实的取舍：过度标准化会拖累灵活性，完全不标准化则是死路一条。我的标准是"结构松、接口严"——内部实现随便写，但描述格式、输入输出契约、依赖声明这类的边界接口必须严格遵守固定规范。

5.2 技能质量评估维度

当技能数量超过20个，就需要一套量化指标管理系统质量，否则整个技能库会慢慢腐化。我跟踪这几个指标：

每周我会跑一遍指标巡检，重点看那些调用准确率掉到85%以下的技能，大概率是描述与线上话术脱节了，需要更新示例或收紧触发条件。

技能质量不是一劳永逸的，它应该像产品一样有迭代节奏。每次业务话术变化、每次模型升级、每次外部API变更，都是一次技能回归测试的触发点。

5.3 个人实操体会

最后聊点掏心窝的话。过去大半年，我从"写提示词"转向"设计技能体系"，最大的感触是：技能化不是把Prompt拆开，而是把"知识"和"执行"彻底分离。Prompt里的知识会随着模型升级而过时，但技能里的执行逻辑和契约可以长期稳定运行。模型替换之后，技能基本不用改，只需要重新跑一遍回归测试。

如果你现在正准备给Agent升级成技能架构，我的建议很简单：别贪多，选一个出错率最高、用户抱怨最多的业务功能，把它做成第一个技能，跑通全链路（描述、执行、回退、观测、回归测试），再复制这套模式横向扩展。技能库的价值不是"数量大"，而是"每一个都好用、都有人维护、都有数据证明它有效"。

技能生态这条路的下一步，必然是技能市场的出现——团队内部沉淀优质技能、跨团队复用、甚至外部开发者持续供给新技能。而标准化的统一数据格式，是这个市场能够活起来的地基。

我目前也还在持续碰壁中，比如技能自动生成、技能间依赖冲突的跨版本解决、语义路由在更大规模技能库上的衰减问题等等。这些坑以后有机会再慢慢写。但可以确定的是，agent-skills这个方向，值得每一个做Agent的人认真投入。