1. 为什么Agent需要一套"技能体系"
1.1 从"装进提示词"到"装进技能库"的转变
先说个很直观的现象。早期大家做Agent，基本都是把工具说明、调用方式、返回格式一股脑塞进系统提示词，然后让大模型自己看着办。这种做法在小规模Demo里确实能跑通，但一旦业务场景复杂起来，比如要做多轮客服、要操作多个内部系统、要处理几十种任务类型，提示词里塞的内容会迅速膨胀到离谱的程度。我见过不少团队的系统提示词动辄几千甚至上万token，光是维护这段提示词就够呛，更别提每次修改工具定义都要跟着改一遍。
这时候你需要的不是继续往提示词里堆内容，而是一套能够独立管理、按需加载、可复用、可测试的"技能体系"。这也是"agent-skills"这类思路最近特别受关注的根本原因——它把Agent的能力从"模型记忆"里释放出来，放到了外部可维护的模块里。
我理解一个Agent技能，本质上就是对某一类任务处理能力的封装。它既包含模型需要知道的"这个技能是干什么的、什么时候该用"，也包含执行层面需要的具体逻辑、依赖、参数定义和返回规范。说得通俗一点，如果把大模型比作一个能力很强但记忆力有限的新员工，技能库就是一个按需翻阅的标准化操作手册，而不是把整本手册背在脑子里。
1.2 技能体系到底解决了什么核心问题
我总结了一下，一套好的技能体系主要解决四个核心问题。
第一是上下文长度与调用精准度的矛盾。模型上下文窗口虽然在不断变大，但塞得越满，注意力分散越严重，对单次调用的理解精度反而会下降。技能体系可以做到"按需注入"——模型先判断该用哪个技能，系统再把对应的描述和参数schema动态加载进来，而不是所有技能常驻在上下文里。
第二是能力复用与产品迭代的问题。如果每次做新业务都要重新写一套工具调用逻辑，那Agent的能力就永远是项目私有资产，沉淀不下来。有了统一的技能描述和注册机制，不同项目之间可以共享技能库，新增业务只需要做技能的重新编排和组合，效率高很多。
第三是测试与调试的复杂度。提示词式的Agent调试起来非常痛苦，因为改一句话可能影响所有任务的表现。技能模块化之后，每个技能可以单独测试、单独设计验证用例，甚至可以做A/B对比。我在实际项目中感受特别深：未模块化之前，线上问题定位基本靠猜；模块化之后，问题可以被精准定位到某个技能模块，定位和修复的效率完全不在一个量级上。
第四是权限和模型能力的安全边界。技能可以做粒度级别的权限控制，什么角色能调用什么技能、技能默认是否允许操作外部系统，都能在体系层面统一管控，而不是靠模型自觉。
如果你只是做一个小玩具Demo，那确实直接用提示词就够了，没必要引入技能体系的复杂度。但只要是准备上生产的项目，我建议从第一天就把技能体系这个架构方向定下来。
1.3 技能模块的核心要素构成
一个标准化的Agent技能模块，在我目前的工程实践中通常包含这么几个要素。
首先是职责说明，也就是这个技能做什么、不做什么，接收什么类型的输入，常见的使用场景是什么。这部分是给模型看的，帮助它做技能选择。
其次是触发条件，包括显式触发和隐式触发。比如"查询天气"这个技能，用户直接说"今天北京天气怎么样"是显式触发；用户说"帮我安排明天出差行程"时，Agent需要推理出"可能需要查天气、查航班、查酒店"等技能的组合调用，这就是隐式触发。触发条件设计得好不好，直接决定了Agent的调度灵敏度和误调用率。
第三是调用接口，即技能对外暴露的输入输出格式。配套的还有参数说明、必填和可选字段、枚举值的范围等。这里的接口设计越规范，大模型做参数填充的成功率越高。
第四是依赖项，比如技能需要哪些环境变量、需要调用哪些外部API、有没有需要预加载的数据或模型。依赖项做得清晰，技能的跨环境可迁移性就强。
第五是失败反馈与扩展信息，即技能执行失败时返回什么样的错误结构，以及是否允许模型针对错误做重试或降级处理。
这五个要素缺一不可。我接下来会在实操章节里给出一个可以直接参考的JSON结构示例。
2. 设计Agent技能体系的关键思路
2.1 先分清技能、工具、工作流的边界
很多人在设计技能体系时遇到的第一个困惑是：技能（Skill）、工具（Tool）、工作流（Workflow）到底有什么区别？
我自己的划分方式是看"能力复用"和"组合复杂度"这两个维度。单个工具是最细粒度的原子能力，比如"发送HTTP请求""查询数据库""调用某个API"。技能则是围绕某一任务目标封装的能力单元，它内部可能会用到多个工具，并且带有一定的决策和反馈逻辑。工作流更偏重固定流程的编排，比如"新用户注册流程"由身份校验、信息采集、权限分配三个步骤串起来，流程基本固定，不需要模型实时参与决策。
技能处于中间层，这个定位非常关键。
拿做饭来类比：工具是锅、铲、刀、砧板，技能是"红烧肉的做法"，工作流是"今天晚餐全流程"。"红烧肉的做法"这个技能，需要用到刀、锅、调料等多个工具，而执行过程有一定的步骤，但又允许根据实际情况调整。
在设计Agent技能时，如果你发现一个"技能"里只包了一个API调用，那它应该直接下沉为工具；如果发现一个"技能"里写了大量固定步骤且不允许模型变通，那它更像工作流。把这个边界划清楚，后面就不会出现体系设计过重或过乱的问题。
2.2 技能编排的三种基础模式
技能体系确定之后，下一个问题就是多个技能怎么组合。我在实际项目中最常用的是三种编排模式。
第一种是条件路由，即不同技能之间的选择关系。模型根据用户意图的判断结果，把任务分配给不同的技能执行。这种模式对触发条件定义的要求很高，否则容易出现两个技能边界重叠、互相抢任务的情况。
第二种是串行流水线，即上一个技能的输出，作为下一个技能的输入。这种模式需要格外注意输出结构的稳定性，因为模型生成的技能输出偶尔会格式漂移，如果下游解析太严格，整条流水线很容易断。我的做法是在技能间的数据传递里统一走一个中间结构，并允许一定程度的字段缺失补默认值。
第三种是并行扇出，即一个任务同时交给多个独立技能执行，最后把结果汇总。这种模式最典型的场景就是市场调研类任务，比如"分析竞品时同时获取价格、评价、销量三个维度的数据"。并行模式需要注意技能之间的资源竞争，比如共享的API配额、数据库连接池，在Agent已经跑起来之后这些都会被放大。
除了这三种基础模式之外，比较前沿的做法是让Agent自己做动态规划，模型自主决定技能的拆分和编排，但这种模式对模型的推理能力要求很高，也需要极其完善的容错机制。我的建议是从前三种模式开始，把基础打扎实，再去追求动态编排。
2.3 一套可落地的技能描述规范
这里给出一套我比较推荐的技术中立型技能描述结构，用JSON承载，不绑定具体框架。
{ "name": "fetch_competitor_report", "version": "1.3.0", "description": "抓取指定竞品在目标电商平台上的价格、评价数及热销SKU信息并汇总为对比报告", "scenarios": [ "用户要求对比分析竞品价格", "用户要求调研某品类Top商品的销量表现" ], "not_for": [ "用户要求的是非电商平台数据", "用户只想要单个商品详情而非竞品对比" ], "input_schema": { "type": "object", "properties": { "competitor_names": { "type": "array", "items": { "type": "string" }, "description": "竞品品牌或店铺名称，最多不超过5个" }, "category": { "type": "string", "enum": ["3C", "home_appliance", "beauty"], "description": "目标品类" }, "platform": { "type": "string", "enum": ["tmall", "jd", "douyin"], "default": "tmall" } }, "required": ["competitor_names", "category"] }, "output_schema": { ... }, "dependencies": ["PRICE_SERVICE_API_KEY", "RATE_LIMIT_CFG"], "failure_strategy": "retry_once_then_degrade" }这里最关键的不是字段定义得多么花哨，而是"scenarios"和"not_for"这两个字段。这两个字段是帮助模型做技能选择的锚点，写得好能大幅降低技能误触发的概率。我发现很多团队的技能描述里只有一句description，模型在多个相似技能之间做选择时就容易飘，加上了典型场景和反例场景之后，准确率提升非常明显。
2.4 技能生命周期管理要点
技能不是写完就完事的，它有创建、调用、监控、更新、下线这样一个完整生命周期。
创建阶段要重点关注技能描述与实际行为的一致性。很多技能是"描述得很美，执行得稀碎"，模型根据描述选了它，结果干出来的活完全不是那么回事。所以我建议每个技能在注册上线前，都要做至少一轮"描述-行为一致性评审"，就是拿描述去要求另一个Agent根据它执行几个用例，看能不能跑出预期结果。
监控阶段要关注的是技能的调用成功率、平均执行时长、返回结构异常率。技能毕竟是给模型用的，模型在调用时会产出各种各样的参数组合，有些组合是你的schema里根本没定义过的，这些情况都要被记录下来。
更新阶段最重要的是做版本管理。技能的更新不能直接覆盖，因为模型上下文中可能还缓存着旧版本的描述和参数schema，直接替换会导致模型按旧的理解来调用新接口，很容易出兼容性问题。正确的做法是保留版本历史，并在技能注册中心里做灰度切换。
最后是下线阶段，要确保没有正在执行的会话还引用旧技能，最好在做完下线通告之后隔一个完整会话周期再物理删除。
3. 从零搭建一套Agent技能模块（实操环节）
3.1 明确技能边界与依赖清单
我先说说技能边界怎么梳理。实操中的第一步，是从历史对话和任务日志里拉出所有用户请求，按任务目标聚类。比如"查天气"和"查空气质量"看起来是两件事，但从用户视角都是天气相关的信息查询，可以统一到一个技能里做意图内分流；而"查天气"和"根据天气规划出行"虽然相关，但后者涉及行程编排逻辑，就应该拆成两个技能。
边界划完之后，要做依赖清单。依赖不只是外部的API和密钥，还包括运行时依赖。比如技能执行需要Python 3.10以上的环境，需要安装某个第三方库，需要在当前机器上有可用的GPU资源。依赖清单做得越完整，这个技能在别的团队、别的项目里复用时踩的坑就越少。
这里我强烈建议给每个技能配一个"环境自检脚本"，技能加载时先跑一遍自检，确认依赖可用再往下走。我在一些生产项目里看到过很惨的案例：技能在测试环境一切正常，上线之后连接数据库的账号没有权限，导致Agent一连几天返回固定错误。如果有自检脚本，这个问题第一分钟就会被发现。
3.2 技能注册中心的实现思路
技能注册中心是整个技能体系中基础设施中的基础设施。它的核心职责是保存所有技能的定义、版本、依赖信息和启用状态，并提供按需查询能力。
实现上不一定要搞得特别复杂，我的建议是先用一个独立的内存索引加定时同步，然后是带持久化能力的中央注册中心。如果你的团队已经有了配置中心或服务注册中心，把它们扩展一下就能用。
注册中心里存储的每条技能记录应该包含：
- 技能名、版本号、注册时间
- 技能描述、触发场景、反例场景
- 输入输出Schema
- 依赖项清单和环境要求
- 当前启用状态和灰度策略
- 历史版本列表及回滚点
注册中心还要提供按"语义相似度"搜索的能力。这一步很关键，因为Agent技能选择的本质不是精确匹配，而是基于模型embedding向量的相似度搜索。我通常的做法是给每个技能预先计算一个描述向量，在模型需要技能选择时，先通过向量检索召回前5个候选技能，然后把这5个候选技能的完整描述交给模型做最终决策。这样既能控制上下文注入量，又能保证候选集的质量上限。
3.3 模型与技能模块之间的语义匹配
这是整个技能体系中最核心、也最容易翻车的一环，值得详细说说。
模型在接到用户任务之后，需要自己决定要不要调用技能、调用哪个技能、用什么参数调用。这个过程本质上是一个语义匹配加参数填充的双重任务。
第一阶段语义匹配，是把用户请求向量化之后，在技能注册中心里搜索最相似的技能描述集合。这里我学到的一个教训是：不要只靠一个embedding模型，最好准备两个互补的检索策略。一个用语义向量，另一个用关键词和近义词扩展，然后把两个召回结果做融合排序。如果你的场景里有很多用户习惯说法跟技能描述措辞差异大，比如用户说"帮我盯着点竞品"，而技能描述里写的是"定时抓取竞品价格"，那么向量检索召回率可能不稳，加上关键词共现的召回结果会更稳。
第二阶段参数填充，是把用户请求中的相关信息映射到技能的输入schema上。这一阶段最大的坑是模型的参数幻觉，即它可能会自己编造schema里不存在的参数。我在后面的常见问题章节里会展开讲。
一个比较直接的建议是：不要把所有的参数填充都交给模型。对于枚举值、数值范围、正则格式有明显约束的参数，可以在技能描述中把约束条件说得更详细之外，还需要在执行层再补一层参数校验逻辑。模型给过来的参数，先过了校验器再走执行逻辑，不合法就返回一个结构化错误让模型自行修正。这手"双层保险"能极大降低脏数据进入业务系统的概率。
3.4 完整技能加载流程
我总结了一套比较成熟的技能加载流程，每一步都有明确的产出物和校验节点。
第一步，接收任务并进行意图初判。系统先决定这是一个需要技能的任务，还是一个模型可以直接回答的问题。这个判定通常可以由一个轻量级分类器完成。
第二步，候选技能召回。通过向量检索和关键词检索组合的方式，召回top K候选技能。
第三步，系统提示词组装。把当前任务相关的候选技能描述动态注入到系统提示词里。我倾向于同时注入候选技能的输入输出schema，给模型的参考做得越具体，后面出错概率越低。
第四步，模型决策与参数生成。模型输出技能选择结果和JSON格式的参数。
第五步，参数解析和合法性校验。这一步由独立的参数校验器完成，校验不通过就返回错误代码和修正建议给模型，让模型重新生成参数，最多重试两次。
第六步，技能执行引擎调度。技能被拉起后，按技能内部定义好的逻辑运行，可能是调外部API、查数据库、执行本地脚本等。
第七步，执行结果反馈。结果回到模型上下文，由模型组织语言生成对用户的最终回答。这一步要格外注意防止模型在转述结果时瞎发挥，能直接引用结构化结果的最佳。
这七步我建议做成一个可观测的流水线，每一站都输出日志。实际排障时有没有这一整套日志，排查效率是天壤之别。
3.5 技能执行后的反馈链路
反馈链路是整个体系里容易被忽视、但极其重要的一环。一个技能执行完成之后，返回的不仅仅是执行结果，还应包括执行元信息：调用耗时、依赖资源消耗情况、是否有降级行为发生、返回结构是否完整。
这些元信息有两个去向。
一个去向是模型上下文。模型需要知道自己刚才的技能调用是否成功，是否需要进一步追问用户或补跑其他技能。比如技能执行成功但数据为空，模型需要据此判断是"真的没有数据"还是"需要引导用户换个关键词再试一次"。
另一个去向是监控遥测系统。技能调用成功率、失败原因分布、参数校验拒绝率，这些指标直接指导后续的优化方向，同时也要作为告警检测的核心指标。比如某个技能连续五分钟调用失败率超过50%，应该立即触发告警并考虑自动熔断降级。
我在实践中还会给反馈链路加一层"用户信号"追踪。当技能执行完成并输出结果之后，观察用户是表示满意、继续追问还是直接结束会话。这个信号可以用来评估技能描述和用户期望的匹配度，是一个非常隐蔽但好用的效果指标。
4. 常见问题与排查技巧实录
4.1 参数幻觉：模型编造了schema里不存在的参数
这绝对是我在Agent技能体系上遇到过的第一大坑。现象是：模型输出的JSON参数里，出现了技能schema里完全没有定义的字段；或者是给了错误类型，比如schema里规定category是枚举值，模型传了"tmall_and_jd"这种组合值。
这个问题的根源在于模型在做参数填充时，会依赖自己对文本的理解进行补全与联想，而不是死板地照搬schema。当你给了模型足够长的上下文，它填充参数的自由度就越大，幻觉概率也随之上升。
排查和应对我分三招。
第一招，是给参数schema提供更严密的描述。不只是枚举值列表，还要把每个枚举值的准确含义写清楚。比如"category: tmall"是什么意思，"tmall_and_jd"为什么不是合法值，都可以写在description里。模型理解了约束边界，幻觉率就会降下来。
第二招，是设参数白名单校验。所有模型生成的参数必须在执行前过一遍JSON Schema校验器。不合法参数绝不直接执行，而是把校验错误消息返回给模型，让它基于错误提示进行自我修正。这里关键是错误消息要写清楚"哪个字段不合法、期望的类型/枚举值是什么、当前给了什么"，模型根据这个信息修正的成功率能到八成以上。
第三招，是限制参数自由度。如果某个参数在一定条件下有唯一推导规则，就不要交给模型生成。比如平台参数，如果当前用户的IP已经能判定来源区域，那平台参数完全可以由系统侧填充，不需要模型决策。所有能由规则决定的东西，尽量不要交给模型。
4.2 技能膨胀：技能库越来越多，召回越来越飘
第二个常见问题，是随着业务发展技能数量越加越多，多到两三百个甚至上千个技能，随之而来的是召回准确率明显下降。
这背后有两层原因。第一层是向量检索在高相似度技能增多之后，召回结果的区分度变差。第二层是技能描述之间有互相污染，比如"价格查询"和"历史价格查询"两个技能描述高度重叠，模型在做最终选择时也会更犹豫。
我的处理办法是分三层缓解。
第一层是缩维度，就是做技能分类目录。每个技能在注册时都要挂载到一个分类节点下，模型先选分类，再在分类内部选技能，把一次大范围选择拆成两级小范围选择。这能显著缩小候选集。
第二层是做技能描述差异化。同类技能的描述避免共用模板，要为每个技能提炼真正独特的触发场景和边界条件，并明确"not_for"的场景，这样模型才有足够的信息做区分。
第三层是定期做技能合并与下线。如果两个技能的实际命中重叠度持续超过某个阈值，比如连续两周都在70%以上，应该考虑合并或者做同一技能的不同分支。技能数量不是越多越好，保持精简比堆积数量更重要，我一直用这个判断标准。
4.3 版本冲突与灰度切换的坑
技能做了版本更新之后，最容易出现的问题是：模型调用技能时的行为与新版本不兼容，但模型拿到的还是旧版技能的描述。出现这类问题通常是你调整了接口schema，但模型上下文里缓存的信息没有同步刷新。
我为此专门规范了技能更新的流程。技能发新版本，先引入"兼容校验"逻辑。新版本的schema要能够兼容旧版本的调用输出，如果做不到兼容，那么旧版本的调用应该在注册中心被标记为"停用"而不是"已更新"。
灰度切换方面，我不会硬编码指定某版本生效，而是引入一个version-probe的参数，在新版本号后面加上一个环境标记，让不同会话上下文拿到不同版本的技能描述。等新版本的各项指标稳定跑满一段时间之后，再把流量全部切到新版本。
版本号的语义规则也要事先定义清楚，我的习惯是遵循语义化版本规范。大版本是指接口不兼容的变更，中版本是行为调整但接口兼容，小版本是描述性文字更新。因为技能描述参与模型决策，所以小版本的更新本身也会影响模型的调用行为，这一点和普通软件版本更新的影响面不同。
4.4 上下文被技能描述撑爆
第三个实际问题是——技能体系做完了，每个技能描述都很完备，但如果你把所有候选技能的完整描述都塞进上下文，那上下文体积会非常大，几轮会话之后就可能撑爆窗口。
我实测下来，一个技能的基础描述加输入输出schema，通常需要800到2000个字符，如果是更复杂的技能加上详细说明，三四千个字符都挡不住。如果一次会话要管理8到10个候选技能，光技能描述这一块就要消耗一两万token，再叠加多轮历史对话和中转信息，上下文很容易顶着上限跑。
解决方案是给技能描述做分层存储。注册中心里保存的是完整详细版，但在模型上下文里注入的是经过压缩的摘要版。
摘要版只包含这样几部分：技能名、一句话职责、主要触发场景、输入参数的必填字段和关键约束、输出结构简要说明。如果模型在摘要版里无法完成选择，它可以选择"展开技能详情"来获取更多信息，这时才把完整版加载进来。这个机制能有效控制上下文占用，把更多空间留给历史对话和结果推理。
4.5 技能层面的权限与安全设计
最后是安全，我把安全话题放到了排查章节里讲，因为大多数团队都是出事之后回头补的。
技能体系里最典型的安全隐患是技能权限过大。比如一个"查询数据库"的技能，如果它的执行账号对所有库表都有读权限，模型就有可能在参数填充时把一些不该被查询的表名给传进来。这种问题的可怕之处在于它不是黑客攻击，而是模型的无心之失，但后果可能很严重。
我的应对思路是"技能最小权限原则"。每个技能在注册时都要申报自己需要的权限范围，执行引擎在拉起技能做具体操作之前，先做一次权限校验，确保技能的实际行为和申报能力一致。数据库访问的场景要追加行级和列级权限控制，外部API调用要确保调用密钥指到专用的隔离账号。
另外，凡是涉及下单、删除、转账、推送这类高影响的技能，强制设计二级确认机制。Agent可以先执行"预计算"并展示结果给用户，用户确认后再正式执行，同时稽核接口留痕。这一设计没有任何负面作用，只是让高危操作多了一道保险阀门。
5. 结尾：一点实操体会
整个技能体系搭建过程中，我最大的体感变化是，从"调模型"变成了"设计能力库"。模型的能力是一个已知量，能变的是外部技能模块的边界、质量和配合方式。每次新业务进来，我不再焦虑要不要改提示词，而是思考该沉淀一个什么样的新技能。
如果你现在刚起步，我的建议是不要急着把体系建得特别重。挑一个你实际业务中最高频、最痛的任务，把它封装成第一个技能，跑通"描述-选择-执行-反馈"的闭环，然后把中间遇到的问题记录下来，再迭代下一版设计。技能体系这件事，是在一次次真实任务的打磨中慢慢长出来的，不是照搬一个框架就能一步到位的。
最后分享一个小技巧：给技能描述写完之后，试着扔给一个大模型看，让它不看你的业务代码，只看描述来判断这个技能什么时候该用、什么时候不该用。如果它能准确判断，这个技能描述就合格了；如果它犹豫或出错，你就有机会在真实用户遇到同样困惑之前，把描述修得更准。
