Agent技能体系设计：从提示词堆砌到动态技能调用

在AI代理（Agent）项目里摸爬滚打了快两年，我越来越确定一件事：决定代理上限的不是模型能力，而是它手里到底握着多少把“趁手的工具”。最近团队在重构一个内部项目时，我顺手把沉淀下来的技能调用逻辑做成了独立模块，起了个名字就叫“agent-skills”。这个项目本身不是银弹，但它解决了一个特别实在的问题——怎么让一个大模型驱动的代理，像老员工一样熟练掌握企业内部的几十个系统操作流程，而不是每次对话都从零开始“猜”。

这篇文章我想把agent-skills的设计思路、核心实现逻辑和实操中踩过的坑都摊开讲清楚。适合正在搭建Agent应用、或者被“提示词越来越长但效果越来越差”困扰的开发者参考。我会尽量说人话，把那些文档里不写的东西也聊一聊。

1. 项目整体设计与思路拆解

1.1 为什么Agent需要“技能”而不是一堆提示词

最早做Agent应用的时候，我和很多人一样，喜欢把各种操作说明直接塞进系统提示词里，比如“当用户提到查库存时，你需要调用库存查询接口，参数是商品编码……”等提示词写到上万字，问题就来了：模型注意力会被稀释，真正关键的操作指令经常被无关信息淹没，而且每次改动一个操作流程，整个提示词都要推倒重来。

后来我看到一个说法，大意是“Agent的长期记忆不该是对话记录，而是技能清单”。这句话直接点醒了我。所谓技能，本质上就是把一段明确的操作流程、触发条件、所需参数和预期返回值封装成一个独立的、可被模型动态调用的模块。模型不天然知道你的业务系统怎么对接，但只要你把技能清单喂给它，并且在运行时把技能描述注入适当的位置，它就能像查字典一样找到最合适的处理方式。

agent-skills的核心设计就围绕这个理念：技能是独立单元，模型按需调用，系统负责执行。提示词只负责“表达意图”，技能库负责“落地执行”。

1.2 技能库与模型解耦带来的三个好处

把技能从对话上下文里剥离出来，我实际感受到三个明显变化。

第一个变化是上下文窗口压力骤减。以前那种把所有操作说明都塞进系统提示词的做法，动辄占掉几千token，现在只需要给模型一个技能清单——每个技能一句话简介，加上触发场景说明，整体控制在几百token以内，模型反而更清楚自己有什么牌可用。

第二个变化是技能复用性大幅提升。同一个“查询订单状态”的技能，可以在售前咨询、售后处理、内部对账三个场景里复用，只需要在技能描述里写清楚适用场景，模型自己会判断怎么调用。

第三个变化是调试效率翻了不止一倍。以前排查“为什么代理没调用库存接口”这种问题，得去看完整提示词里的哪一行起了冲突；现在直接检查技能命中逻辑就行——是描述没写清导致模型没识别出来，还是参数类型对不上导致执行失败，问题边界清晰很多。

某种意义上，agent-skills做的事，就是把“模型会说话”和“系统能干活”这两件事彻底分开。

1.3 从功能模块到技能单元的设计迁移

做技能设计时，我犯过很多次错，最典型的是思维惯性——还是把技能当作传统的函数来写。比如一开始我把“获取天气信息”直接定义成一个函数，参数只有城市名，返回值是温度。但Agent真正需要的是一个“技能”，它包含的东西远不止函数签名。

以“查询天气预报”为例，传统函数只需要定义参数和返回结构。但作为Agent技能，我需要额外提供：

• 描述：用于模型判断何时调用，比如“当用户想了解未来几天的天气情况时调用”
• 参数说明：城市名需要是中文全称，比如“深圳市”而不是“深圳”或“SZ”
• 返回值定义：包含当前温度、天气状态、未来三天的天气预报等

这样一来，模型在面对“明天适不适合去爬山”这种模糊问题时，才能自行判断是否需要先调天气接口，再结合返回做建议。模式的转变，意味着函数维度从“怎么实现”上升到了“何时被使用、使用后如何处理结果”的层面，这正是agent-skills这个项目最有价值的地方。

2. 核心技能解析与实操要点

2.1 技能的类型拆解：信息获取型、操作执行型、推理辅助型

在实际落地过程中，我发现不同业务场景下的技能其实可以粗略分为三种类型，三种类型的实现方向和实操重点有着比较大的差异。

信息获取型技能是最常见的，核心是查询、检索、聚合信息。典型代表是查库存、查订单物流、查数据库记录。这类技能通常实现简单，但需要重点关注返回数据的结构化程度。数据如果原样返回给模型，往往噪音太大。我在实现时就专门加了一层“结果裁剪层”，把业务字段重命名为模型容易理解的描述性字段，例如后端接口返回的“st”表示仓库库存数，经过裁剪层转换为“库存数量（件）”，模型直接就能用。

操作执行型技能则是真正完成“代理代替人来操作”这一目标的技能，比如提交审批单、创建订单、群发通知等。这类技能的安全级别要求很高，必须在技能定义时显式声明确认步骤。agent-skills里专门有一个参数叫confirmation_policy，可以设定为“never（不要求确认）”“always（每次都要确认）”“on_risk（风险操作才确认）”三档。涉及资金、权限变更的操作，我基本都会设置成“always”模式。

推理辅助型技能比较隐性，容易被忽略，但它确实在复杂任务中起到了关键作用。比如让模型先调用“提取合同关键信息”技能，再调用“比对两个合同版本的差异”技能，最后调用“判断是否有风险条款”技能，这几种技能合起来就完成了一次推理闭环。这种技能不直接对接外部系统，而是对模型内部能力做结构化包装，让中间推理过程可以根据业务标准“检查”。

2.2 技能描述该如何写出“模型一眼就懂”的效果

这个心得是我反复试出来的：技能描述写得好，模型调用准确率直接上一个台阶。所谓好，既不是因为描述写得多，恰恰相反，要精准去掉冗余信息。

写过技能描述的开发者往往会有一种失落感——自己辛辛苦苦写的说明，模型就是视而不见。原因大多可归结为两点：设置不当的触发条件没说清楚，或者描述内容与技能实际能做的事对不上。

给技能写一个“帮助中心式”的一句话描述，用“当...时，用于...”句型。比如：“当用户询问某个商品是否有库存时，用于查询指定仓库中某商品的实时库存数量。”模型对这种条件句式的识别远比孤立的名词短语要准。

参数说明的写法也很有讲究。建议写清楚三件事：参数含义、格式要求、边界示例。比如：

{ "warehouse_id": { "description": "仓库编号，四位数字，如1001", "required": true }, "sku_code": { "description": "商品编码，通用商品条码格式", "required": true } }

这段描述能让模型非常清楚地理解该传什么格式的值。曾经有个技能，我没写清楚“仓库编号是四位数字”，模型就一直把用户口中的“华东仓”原样传进来，导致执行层解析失败，后来在描述里加了格式说明和示例，问题才解决。

2.3 技能调用的参数校验与容错处理

在agent-skills项目里，参数校验优先级相当高。因为模型的输出本质上基于概率，偶尔会产生参数幻觉——编造出一个用户根本没提到的值。

一个真实的例子：用户问“帮我查一下上个月总共充了多少话费”，模型在调用“查询话费账单”技能时，可能会把“上个月”猜测成具体日期“2025-01-01”到“2025-01-31”，这个时间段如果和业务口径不一致，返回结果就会错。

我的处理方式是加一层“参数预检器”：所有模型输出的参数先经过规则校验，比如枚举范围、字段格式、必须非空，不满足就直接拒绝，而不是传给下游。校验规则里还支持设置“你需要询问用户”的字段，模型如果缺少该项参数，就不会硬猜，而是生成补充提问。

举一个极端的例子，在调用“创建报销单”技能时，报销类型、金额、所属部门是三个必填参数。模型但凡缺了其中任何一个，预检器直接让模型必须询问用户，不允许带入guess值。流程闭环了，幻觉参数基本就堵死了。

3. 实操过程与核心环节实现

3.1 基础工程结构与目录规划

agent-skills建议按领域拆分技能目录，用三层结构顶层/领域层/具体技能层。一个精简版的目录结构如下：

agent-skills/ ├── skills/ │ ├── order_query/ │ │ ├── SKILL.md │ │ ├── schema.json │ │ └── executor.py │ ├── warehouse_inventory/ │ │ ├── SKILL.md │ │ ├── schema.json │ │ └── executor.py │ └── common/ │ ├── parameter_validator.py │ └── response_clipper.py ├── registry/ │ └── skill_registry.py └── config.yaml

SKILL.md记录自然语言描述，schema.json定义参数规则，executor.py才是真正的执行逻辑。这样设计的好处是：描述与实现分离，模型只需要读SKILL.md，执行层只看schema和executor，前后端互不干扰。

3.2 技能注册与动态发现机制

agent-skills里有一个核心模块叫技能注册中心。所有技能启动时都会向注册中心注册自己的SKILL.md摘要信息，注册中心把这些摘要汇总成一张技能清单表。运行时，这张表会随系统提示词发给模型。

技能清单表里每项只保留几个关键字段：技能ID、一句话描述、适用场景标签。比如：

这里有两个容易忽略的经验。第一，技能清单表必须定期更新，新增技能后没注册，模型根本不知道可用，再好的技能也是无效的；第二，描述里一定要有场景标签字段，模型做意图分类时，这个标签比描述正文的命中率还高。

3.3 用配置中心管理技能版本与开关

技能上线之后，绝不能直接全员强制。我习惯用配置中心做灰度发布。

在config.yaml里，每个技能支持配置enabled状态和version版本号：

skills: order_query: enabled: true version: "2.1.0" allowlist: ["default_agent", "customer_service_agent"] expense_create: enabled: false

灰度策略简单讲就是“先让小流量代理用起来，验证无问题再开放全量”。这个机制避免了技能回滚引发的大范围线上事故。有一次我更新了“订单查询”技能的执行逻辑，导致部分单号前缀识别异常，因为设置了灰度一半流量，问题影响面被直接限制住，原本的一线上的“事故”变成了安静的回归测试。

3.4 构建工具调用链路的依赖管理

单个技能实现简单，但多个技能按顺序组合起来的链路，才是实际业务中真正的拦路虎。

我做过一个“售后自动判责”的链路：先调“订单查询”技能拿订单信息，再调“物流轨迹查询”技能确认包裹状态，最后调“退款规则引擎”技能输出可退款金额。三个技能链路中任何一个卡住，或者上游参数在下游格式不齐，整个任务就断了。

agent-skills在设计上引入了一个简单的链路描述结构，用workflow描述一个组合技能：

{ "workflow_id": "after_sales_refund_assess", "steps": [ {"skill": "order_query", "output_mapping": {"order_id": "order_id"}}, {"skill": "logistics_track", "input_mapping": {"order_id": "order_id"}, "output_mapping": {"track_status": "status"}}, {"skill": "refund_rule_engine", "input_mapping": {"order_id": "order_id", "track_status": "status"}} ] }

每一步的input_mapping和output_mapping是核心，它把上一步技能返回的字段名跟下一步需要传入的参数名建立映射关系。实际写下来你会发现，真正让多技能链路稳定的，其实不是模型，而是这一层明确的字段映射规则。

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

4.1 模型始终不调用某个技能，该怎么办？

这是被问最多的一个问题。排查思路按优先级排序，基本能定位九成问题：

第一查技能开关是否生效。配置里enabled是否为true，注册中心是否能看到该技能。经常有人改了配置忘了重启或者强制刷新缓存，导致模型侧一直拿不到这个技能。

第二查技能描述是否和触发场景匹配。描述过于笼统、没写触发条件，模型确实可能不路由。比如“查订单”和“当用户想知道商品什么时候送到时，用订单查询技能获取物流节点”这两个描述，模型对后者的路由准确率明显高很多。

第三查技能清单表是否超长。如果同时注入了几十甚至上百个技能，模型会“迷失在选择海洋里”。一个实测可参考的经验是，单次会话注入技能清单的数量尽量控制在20到30个以内，多于这个数量就需要加一层预筛逻辑，比如根据会话意图标签做初步分类，只给模型注入相关领域的技能。

4.2 技能返回结果太冗余，模型被“噪音”带偏怎么处理？

技能执行后返回的原始数据往往包含大量无关字段。比如查询订单接口可能会返回渠道来源、商品条码、运营备注标签等字段，而模型真正需要判断的只有订单状态和物流节点。

一个快速有效的办法是在schema.json里增加output_fields白名单配置：

{ "output_fields": ["order_id", "status", "track_list"] }

执行器返回前只保留这几个字段。这个方案比在提示词里写“忽略无关字段”可靠得多，属于结构层面的规避，而不是让模型自行理解业务中哪些字段重要。实际做完之后，原本模型偶尔会被“渠道来源”带偏、莫名其妙追问“要不要修改渠道”，这种问题就再没出现过。

4.3 支持模型并行调用多个技能吗？如何降低冲突？

部分任务天然可以拆成多个独立子查询，比如用户问“帮我查一下A商品和B商品各有多少库存”，完全可以并行调两个inv_check技能。但并行会带来一个副作用：多个技能同时调用时，模型可能混淆参数归属，A商品的编号传给了B商品。

我的做法是给每个技能调用分配一个独立的调用上下文ID，执行结果返回时携带上下文ID，再由编排层按上下文ID把结果归位。这样每个技能调用都是“各回各家”，参数混淆问题基本解决。

使用支持结构化输出的模型时，还可以在schema定义里设置strict_mode，让模型严格按照给定的参数结构输出，不额外追加字段。实操下来，配合上下文ID切分，并行调用的成功率可以做到95%以上。

4.4 技能调用超时与下游接口抖动

Agent技能执行背后一定是真实的下游系统，任何一个接口超时都会让整个链路卡住。要把这类问题处理妥善，不能只靠等待。

我习惯给每个技能执行器统一设置超时控制：

import asyncio async def call_with_timeout(executor, params, timeout=5.0): try: return await asyncio.wait_for(executor.run(params), timeout=timeout) except asyncio.TimeoutError: return {"error": "SKILL_TIMEOUT", "fallback_message": "系统繁忙，请您稍后再试"}

返回超时标识后，编排层可以决定要不要走降级策略。处理“查物流”技能超时时，降级话术可以定位“物流信息更新相对较慢”，让模型尝试引导用户等待一段时间后重试，而不是干巴巴地报错。这一层设计做完，线上用户体感明显提升。

5. 技能框架与工具的选型分析

5.1 自研技能模块与通用Agent框架的取舍

市面上的通用Agent框架，大多自带工具/技能注册机制，比如支持函数调用、插件机制等等。如果项目时间紧、追求快速验证效果，直接用框架自带的工具注册体系效率最高，没必要另起炉灶。

不过当业务走到一定深度，自研一层技能管理机制反而必要，原因有三个：

通用框架的技能生态面向的都是标准化场景，比如查天气、发邮件、算数学，而企业内部业务技能通常需要对接私有化接口，框架层不一定能理解业务参数之间的约束关系。

技能之间往往存在隐性依赖，比如必须先查订单才能查退款，框架层允许你写代码做编排，但没有一个自然的、让“模型自己看懂依赖关系”的描述体系。

灰度发布、技能版本回滚这类做稳定性的需求，框架层支持一般都有限，自研则可以随时按需实现。

agent-skills的定位定位图，表述为“在通用框架能力之上，做一层面向业务技能的管理层”，是比较稳妥的。

5.2 从零搭建时最该优先做的三件事

如果你打算自研一套Agent技能体系，我的建议是不要贪多，先把三件基础设施做扎实。

第一件事是把技能清单注入机制做好，也就是如何把技能描述稳定传给模型。这个机制的好坏决定了后面所有技能的一致性和可控性。推荐用动态模板拼接，在每次对话请求前，从注册中心拉取当前可用的技能列表，渲染成文本块放入系统提示词。

第二件事是参数预检器必须做成独立模块。不要散落写在各技能执行器里，而是统一由注册中心管理规则。这样新增技能时，只需要在schema里声明字段规则，预检器自动生效，不需要重复造轮子。

第三件事是搭建技能调用日志体系，每次调用记录下“模型输出的原始参数”“预检结果”“执行结果”三个关键信息。日志不仅能实际用于排查线上问题，更能够积累数据回喂给技能描述迭代。你对描述的调整到底有没有提升命中率，完全靠日志数据说话，而不是靠感觉。

5.3 Agent技能和微调模式之间的协同

提到技能方案后，总有人问“为什么不直接微调模型？”这两种模式并不是竞争关系，而是一种配合关系。

微调让模型学会“如何表现”，技能让模型学会“能够做什么”。微调可以训练模型的说话风格、输出格式、对某个行业术语的敏感度，但涉及频繁变化的业务接口、配置规则，靠微调更新周期长、成本高，完全不如靠技能配置动态调整来得快。

所以我的口径是：遇到高频变化、强规则依赖的场景，优先用技能方案计算；需要修改模型自身的气质风格、专业领域的表达习惯时，再考虑微调。两者共同服务于更精准的意图拆解。

写在最后的一些实操体会

项目做到这个阶段，最大的感触是：Agent开发的核心其实不是模型，模型本身能力差距已经越来越小，活儿好不好干、稳不稳定，全看周围这些配套系统设计得到不到位。它就像给新员工准备一套操作手册和权限体系，不用它背下所有规则，流程清晰、权限明确，工作就能顺利推进。

如果你也打算在自己的项目里构建agent-skills体系，我建议从一个最痛的场景入手，比如客服订单查询，先把一个技能做成样板间，跑通打通整个链路，再大规模铺开。不要急着追求技能数量，先把一个技能的质量打磨到位，你会远比想象中更快更深刻地在实战中体会到模型+技能这套组合的威力。

再分享一个额外小技巧：技能描述版本迭代时，保留历史描述文本作为对照样本，它能让你的“为什么这个新版本描述效果好，到底是哪句话起的作用”不再只是猜测，可以直接对照产出定量结论。