这两年做大模型应用，一个感受越来越强烈：决定Agent上限的，往往不是模型本身，而是它身边那套“技能系统”设计得怎么样。
我见过不少团队，模型换了一版又一版，效果却一直卡在及格线。后来把精力挪到技能库建设上，同一个模型，任务完成率直接翻了一番。这里说的“agent-skills”，本质上就是给智能体装上一套可注册、可检索、可调用的能力中枢——把模型不会做、做不好的事，拆成它用起来顺手、执行起来可靠的标准件。这篇文章我会围绕技能系统的核心机制、构建路径和真实场景里的坑，把从零到一的设计思路完整过一遍。适合正在做Agent应用、或者准备把业务接入智能体的团队参考。
1. Agent Skills到底解决什么问题：从“会接话”到“能办事”
先聊一个基本问题：模型本身已经很能打了，为什么还要单独搞一套技能系统？这个想不清楚，后面所有设计都会跑偏。
1.1 模型的“知道”和系统的“做到”之间隔着一条鸿沟
大语言模型擅长的是文本生成、语义理解、逻辑推理，它“知道”很多事，但不代表它能“做到”那些事。比如让它查一下你公司上季度的营收数据，模型可以回答出“需要查询财务系统”，但它自己连不上数据库，拿不到token，更不会调用内部API。这时候就需要一套机制，把“模型意图”翻译成“真实动作”，再把“动作结果”反馈回给模型。这套机制就是技能系统。
另一个被很多人忽略的点：模型的推理是概率性的，同一个问题换个问法，它可能给出不一样的中间判断。但业务执行是确定性的——你不可能让订单系统“也许”创建订单、“大概”扣款。技能系统本质上是在模型的概率世界和业务的确定性世界之间，加了一层可控制的缓冲带。它把那些必须精确、稳定、可审计的操作，从模型的语言生成里剥离出来，固化成代码逻辑。这正是“agent-skills”这套设计理念存在的根本理由。
1.2 Skill、Tool、Workflow三者到底有什么区别
很多刚接触Agent的读者会把技能（Skill）、工具（Tool）、工作流（Workflow）混为一谈，这里先把边界划清楚。
Tool是最小可执行单元，比如“发送HTTP请求”“读取文件内容”“发送邮件”。它通常是无状态的，输入参数、调用执行、返回结果，一次完成。Tool本身不带业务判断，像一把螺丝刀，你告诉它拧哪颗螺丝它就拧哪颗。
Skill是围绕某个能力域的Tool集合加编排逻辑。比如“客户信息查询技能”，可能包含“搜索客户”“查询订单”“获取售后记录”三个Tool，并且定义了“先查客户、再关联订单、最后补售后信息”的调用顺序。Skill有状态，有内部逻辑，像一个工具箱加一份使用说明。
Workflow则是面向完整业务场景的流程编排，往往跨多个Skill，包含条件分支、人工审批、异常回退等。比如“客户投诉处理工作流”，会先调用“客户信息查询技能”定位客户，再用“工单管理技能”建单，必要时触发“退款技能”走审批流程。
一句话总结：Tool管动作，Skill管能力域，Workflow管业务流程。技能系统处在中间层，向上承接流程编排，向下调度工具执行，是Agent架构里承上启下的核心关节。
1.3 技能系统如何决定Agent的实际能力边界
有一个判断我越来越确信：评测Agent的能力，不如去数它注册了多少个高质量技能。技能库的丰富度直接决定了Agent能处理多少种任务，而技能的设计质量决定了任务完成的可靠度。
实际跑业务的时候你会发现，模型的上下文窗口再大，也没法装下所有操作细节。技能系统相当于给Agent外挂了一个“能力外脑”——模型只需要知道“遇到什么问题去找哪个技能”，具体的执行步骤、参数规则、异常处理都被封装在技能内部。这既节省了模型有限的注意力资源，也降低了业务操作的出错概率。换个角度，如果把模型比作一个人的大脑，技能系统就是他的双手和工具箱，没有后者，想法永远只是想法。
2. 技能的形式化定义与注册机制：让模型“看得懂”还能“用得好”
既然技能这么关键，第一步就是把技能本身设计成一种既规范、又对模型友好的形态。这块做得不好，后面检索再先进也白搭。
2.1 一个技能的基本组成：描述、参数Schema、执行体
我通常把一个技能拆成三个组成部分，缺一不可。
技能描述（Description）：用自然语言说明这个技能“是干什么的、在什么场景下用、有什么注意事项”。这段文字不是写给人看的文档，而是写给模型看的“使用说明书”。模型靠它决定“当前这个任务要不要调用该技能”，所以描述里必须说清楚适用条件和边界。比如一个“天气查询”技能，描述里就要写“用于查询中国任意城市未来3-7天的天气预报，支持按城市名称定位，不适合查询历史天气”。
参数Schema（Parameter Schema）：定义调用技能需要传入哪些参数、每个参数的类型和约束。这是技能和模型之间的“接口契约”。设计得越严谨，模型越不容易传错参数。比如天气查询技能，参数可以定义为城市名称（string）、日期范围（string，格式YYYY-MM-DD）、可选单位（enum: celsius/fahrenheit）。Schema不仅约束参数格式，还隐含了调用方式的引导——模型读到清晰的Schema，会自然按部就班地组织参数。
执行体（Executor）：实际跑逻辑的代码。它接收Schema定义的参数，完成真实操作，返回结构化结果。执行体可以是一个Python函数、一个API封装、一段SQL查询、甚至一个命令行脚本。唯一要求是：输入输出都必须是结构化、可序列化的，方便模型理解和继续处理。
2.2 描述工程：为什么模型总是“看不懂”你写的技能说明
我见过太多团队，技能逻辑写得很扎实，但模型就是调不对。后来一排查，问题出在描述上——要么太笼统，要么太技术化，模型根本没法把“用户需求”和“技能描述”对上号。
举一个真实案例。有个团队做了一个“商品比价技能”，描述写成“比较各大电商平台同类商品的价格差异并输出对比结果”。看起来没毛病，实际测试发现模型经常在用户问“这个手机哪家买便宜”时不触发该技能，反而自己去编答案。后来把描述改成“当用户希望比较同一商品在不同电商平台（如京东、天猫、拼多多）的价格高低时使用本技能。注意：必须先通过商品名称或型号精确锁定商品，再执行比价；若用户未指定具体商品，应主动询问商品名称后再调用。”效果立刻改善。核心差异在于：好描述是从“模型决策视角”出发写的，而不是从“功能视角”出发写的。它告诉模型“什么时候该用、用之前要满足什么前提、有哪些坑要注意”，而不是干巴巴地描述“我能做什么”。
2.3 参数Schema的设计原则：把“模型的自由发挥”关进笼子
关于参数Schema，三条经验值得分享：
第一，尽量减少必填参数的数量。每一个必填参数都是模型的一次“犯错机会”。能通过默认值解决的，就别设计成必填。比如超时时间、返回条数，这类可以给默认值；真正必填的，通常只有定位任务核心的那一两个参数。
第二，用枚举值代替自由文本，用正则约束格式。比如结果排序方式，与其让模型传任意字符串，不如定义成枚举：popular，price_asc，price_desc，price_asc。这样模型的选择空间被限制在可控范围内，执行体收到非法参数的概率大大降低。日期、手机号这类格式明确的字段，配上正则校验，提前拦截脏数据。
第三，参数之间的依赖关系要在Schema里说清楚。比如“查询订单必须传订单号或手机号二选一”这种约束，最好在描述里用For Example写出正确和错误的调用示例。模型对“示例”的遵循能力远高于对“规则”的遵循能力，多给几个正例和反例，参数调用准确率能提升不少。
2.4 技能注册的完整流程：从定义到上线的规范化步骤
技能的注册流程看起来简单，实际跑起来有很多细节。我建议按下面这条链路走：
- 需求分析：跟业务方确认这个技能要覆盖哪些场景、支持哪些输入形态、输出给谁看。
- 形式化定义：按照上面说的三件套，写出描述、参数Schema，评审通过后冻结第一版。
- 执行体开发：先实现一个最小可用版本，用Mock数据自测，保证单次调用逻辑正确、异常路径可控。
- 单技能评测：用一批“真实用户问题”跑一遍，重点看模型能不能正确触发技能、参数传得对不对、返回值是否满足需求。这一步最容易暴露描述和Schema的问题。
- 联调与灰度：把技能接入完整的Agent链路，先用小流量测试，确认不影响其他技能的正常调用。
- 上线与监控：技能上线不是终点，要持续看调用成功率、参数错误率、用户反馈，形成迭代闭环。
3. 技能的检索与路由：怎么让Agent在关键时刻选对技能
技能库一旦上了规模（几十个、上百个），一个新的问题浮出水面：面对用户五花八门的需求，模型怎么知道该调哪个技能？这就涉及技能的检索与路由机制。
3.1 路由的三种主流策略：规则路由、向量检索、模型直选
规则路由是最朴素的方式，适合技能数量少、边界清晰的场景。通过关键词匹配或固定规则，把用户请求映射到特定技能。比如用户问题里包含“天气”，就路由到天气查询技能。优点是确定性强、可控性好、执行速度快；缺点是规则维护成本高，覆盖不了长尾需求，用户换个说法规则可能就失效了。
向量检索是把用户请求和所有技能的描述都做嵌入（Embedding），算相似度，取top-k个候选技能。这种方式对模糊表达、同义改写有较好的容忍度，适合技能数量多、边界模糊的场景。但它有个问题：相似度高的技能不一定就是用户需要的，检索结果只能做“候选”，后面还得靠模型精排。
模型直选是把“用户请求+候选技能列表”交给模型，让模型直接输出要调用哪个技能及其参数。这是目前主流方案。模型理解复杂指令的能力强，能结合上下文做综合判断。但模型直选对候选列表的质量很敏感——如果候选列表里没有正确技能，模型再聪明也无能为力。
实际工程里，三种策略不是互斥的，而是分层配合：规则路由做第一层粗筛（拦截明显的关键词触发），向量检索做第二层候选扩充，模型直选做最后决策。三层配合能把技能选择准确率做到比较理想的水平。
3.2 技能目录的组织方式：分类、标签与索引的三层结构
技能多了之后，目录管理就成了刚需。我之前踩过“平铺列表”的坑：150多个技能平铺在一起，光是维护描述都让人崩溃，模型每次要在一堆候选里大海捞针。后来规范成三层结构，路由准确率和维护效率都明显改善。
- 技能分类（Category）：按业务域划分，比如“客户管理”“订单交易”“营销活动”“数据报表”，每个技能归属唯一分类。模型路由时先定分类，缩小候选范围。
- 技能标签（Tag）：跨分类的灵活标记，比如“只读”“高权限”“第三方依赖”“实验性”。标签用于辅助筛选，比如高权限类技能在非授权场景下直接过滤掉。
- 技能索引（Index）：指向技能文档、测试用例、版本记录、负责人信息。索引不参与在线路由，但支撑离线评测和排查问题。
这套三层结构，本质上是在为模型建立一个“先粗后细”的检索漏斗。分类缩小范围，标签过滤掉不合规选项，最终进入模型决策视野的候选技能数量控制在个位数，决策质量自然就上来了。
3.3 路由冲突消解：两个技能都说“我能做”怎么办
技能规模大了，一个常见问题是：同一个用户需求，多个技能都声称自己可以处理。比如“查询订单物流”和“查询订单详情”两个技能，用户问“我的快递到哪了”，两者的描述可能都会命中。这时候如果选错，轻则返回内容不对，重则调用出错。
三个实用的消解策略：
第一，细化描述，划清边界。在技能描述里明确写出“本技能不处理什么”。比如订单物流技能写明“仅提供物流轨迹查询，不包含订单金额、商品列表等订单详情信息”，模型读到边界后，取舍就清晰了。
第二，定义技能优先级和互斥关系。在技能元信息里标注Priority字段，当多个技能都满足触发条件时，优先选高优先级技能；同时可以配置Exclusive列表，声明哪些技能不能同时被选中。比如“创建订单”和“查询订单”可以共存，但“创建订单”和“修改订单”在同一会话里互斥，因为业务上不允许先建再改的混乱逻辑。
第三，引入用户确认机制。当候选技能得分非常接近、模型难以决策时，不要硬猜，直接反问用户。比如“您是想查询物流进度，还是查看完整的订单信息？”让用户来做最终决策。这虽然是“笨办法”，却是准确率最高的兜底方案。
3.4 上下文增强路由：让历史对话参与技能选择
在一次多轮对话里，用户的需求往往是渐进清晰的。比如用户先说“帮我查个东西”，模型无法判断查什么；下一句“上次买的那双鞋发货了没”，结合历史才知道是要查订单物流。所以技能路由不能只分析当前这一句，要把对话历史一并纳入决策上下文。
工程实现上，一般把最近几轮对话、当前用户的身份信息、当前页面/场景标识拼接到路由输入里。比如客服场景中，用户已登录，可以直接拿到用户ID；用户在商品详情页发起咨询，就优先路由商品咨询类技能。场景信息（Intent Context）本身就能过滤掉大量无关技能，是路由效果最容易被忽视的杠杆。
4. 从零构建一个技能库：选型、开发与测试的完整路径
理论聊了不少，这一章直接给一套可落地的实操路径。从需求梳理到上线监控，每一步该做什么、用什么工具、怎么验证，一次说清楚。
4.1 第一步：需求盘点——哪些场景真正值得做成技能
不是所有功能都值得封装成技能。开发技能是有成本的：描述要设计、执行体要维护、路由要调优。所以第一步是给需求排优先级。我的筛选标准有三个：
- 高频：这个功能用户经常触发。一天用不到几次的，不值得做成技能。
- 确定性：输入输出边界清晰，结果可预期。太开放的任务，比如“帮我想个方案”，不适合做成技能。
- 复用性：多个业务场景都能用，不是一次性需求。比如“发送短信验证码”可以在注册、登录、找回密码等多个流程复用，价值就很高。
按这三个标准把需求过一遍，能做成技能的需求自然浮出水面。不要贪多，先做10个高质量技能，好过做50个半吊子技能。
4.2 第二步：技术选型——技能框架和运行环境怎么选
技能系统的技术选型，核心是解决两件事：技能怎么描述和技能怎么执行。
描述层面，业界主流做法是采用类似OpenAPI的规范来定义技能接口，同时用自然语言描述补充模型的语义理解。也有团队直接用纯Python装饰器把函数暴露成技能，运行时自动生成描述和参数Schema。这条路对开发效率友好，适合内部快速验证。
执行层面，一个值得认真考虑的问题是：技能和Agent主进程跑在一起还是分离部署。小规模场景跑在一起最简单，但技能多了以后，单个技能的异常（内存溢出、死循环）可能拖垮整个Agent。专业一点的做法是把技能做成独立服务，通过RPC或HTTP调用，每个技能有独立的进程隔离和资源限制。这个取舍没有标准答案，关键看团队的运维能力。
额外提醒一个容易忽略的选型点：技能的版本管理和平滑升级。技能描述和参数Schema一旦被模型“记住”，变更可能影响路由效果。所以要用类似DAG（有向无环图）的方式管理技能版本，线上调用稳定版本，新版本在灰度验证通过后再全量切换。
4.3 第三步：技能开发——“最小可用”到“稳定可靠”的迭代节奏
单个技能的开发，我推荐按“最小可用版本 → 真实场景打磨 → 异常加固”三步走。
最小可用版本的目标是快速跑通链路，不要一开始就追求功能全面。先覆盖最核心的调用路径，把技能挂到Agent上，用真实用户问题验证“模型能不能找到它、描述有没有歧义、参数传得对不对”。这个阶段发现的描述问题、Schema问题，比执行体的bug影响更大，一定要优先修。
跑通之后进入真实场景打磨。一方面补充边界输入：空参数、超长文本、特殊字符；另一方面补充边界场景：数据不存在、接口超时、权限不足。这时候你会发现，真正的工程量不在于“正常路径”，而在于“异常路径”的处理设计。
最后是异常加固。给技能的执行体套上统一的异常捕获和重试机制，返回稳定的错误码和错误信息。每个技能都要回答一个问题：当它失败时，Agent下一步该怎么做？是换个技能重试，还是向用户解释原因，还是转人工？这条“失败路径”设计得越好，用户体验越稳。
4.4 第四步：技能测试——除了“正确性”还要测“可发现性”
技能测试比普通代码测试多一个维度——不仅要测执行体的逻辑正确性，还要测模型的“可发现性”。也就是说，在大量真实用户问题下，模型能不能稳定触发该技能、能不能准确传参。
我自己常用的评测方法是构建一个“技能需求测试集”，每条样本包含：用户问题（含多种表达方式）、期望调用的技能、期望的参数。跑评测时，加载Agent对测试集逐条执行，统计三个指标：
- 触发准确率：应该调该技能的问题里，有多少比例正确调用了。
- 参数准确率：正确触发的调用中，有多少比例参数传得完全正确。
- 误触率：不该调该技能的问题里，有多少比例被错误调用了。
这三个指标分别对应描述质量、Schema质量和边界划分质量。每次迭代描述或Schema后，用同一套测试集回归，就能直观看到改动是否有效。这个测试集要持续扩充，把用户真实反馈里的失败样本吸收进来，避免问题二次发生。
5. 实战中的坑与解法：我在技能系统上踩过的那些“看不见的地雷”
这章写点更实在的东西——那些文档里不写、网上案例也少、只有自己趟过才知道的细节问题。每一条都是用真实时间换来的教训。
5.1 描述与实现不一致：模型按“描述”行事，你却按“代码”交付
技能描述写得很美好，执行体实现跟不上，这是最常见也最隐蔽的坑。比如描述里写“支持查询任意城市的天气”，执行体接第三方接口实际只覆盖了国内城市，用户问“纽约天气”时，模型照常触发技能，返回结果却是“暂不支持该城市”。用户的感受就是：这Agent能力不行。
解法没什么技巧：建立描述与实现的一致性校验机制。技能注册时必须附带一份“能力自查清单”，逐条确认描述里的每个承诺都有实际实现支撑。每次执行体变更，同步检查描述是否需要修订。宁可让描述更保守，也别让描述超出实现。
5.2 参数语义理解偏差：模型把“事件时间”理解成了“当前时间”
在参数提取时，模型经常犯一类语义错误：把用户在自然语言里表达的相对时间，错误地理解成绝对时间。比如用户说“查一下上周的销售数据”，模型可能提取出一个错误的时间参数，直接查了本周数据，返回结果用户一眼就能看出不对劲，但问题出在参数理解上，而且极难在常规测试里发现。
解决思路是：“相对时间”问题尽量不在模型层解决，而在执行体层解决。参数Schema只接收标准格式的绝对时间；执行体内部可以对“相对时间”做二次解析或校验。或者更简单：当模型识别出时间类参数时，强制要求它输出“参考日期”字段，执行体基于参考日期做相对时间计算，减少歧义。这类“语义归位”的细节设计，往往比调模型prompt更有效。
5.3 技能间的隐式依赖：单个技能都正常，连起来就翻车
每个技能单独测试都通过，但Agent在真实链路里却频繁出错，这种情况多半是技能之间存在隐式依赖。最常见的例子：技能A返回的数据格式是技能B的输入Schema不兼容的。比如A返回“userId”，B的参数名叫“customerId”，模型把值填进去没问题，但语义上这两个是否一致？如果不一致，B拿到的就是错误ID，查出来的结果是别人的数据——这种错误最危险，因为它表面看起来“成功了”。
解法是设计一个统一的数据契约层，技能间的数据传递都走标准化的数据格式，字段名、类型、精度全局统一。每个技能在注册时声明自己的“输入数据依赖”，Agent在编排时自动做格式转换或校验，而不是把转换责任丢给模型临场发挥。
5.4 状态管理混乱：技能记不住上下文，多轮对话断片
多轮对话场景中，一个高频痛点：用户第一轮让Agent查了订单，第二轮说“帮我退款”，Agent却不知道“这个订单”指的是哪个订单。这是因为技能系统默认是无状态的，每次调用都从零开始，没有把上一轮的上下文带入下一轮。
稳妥的方案是引入会话级状态管理。在对话上下文中显式存入关键状态字段，比如当前选中的订单ID、当前用户身份、当前操作对象。Agent编排时优先读取状态字段，而不是让模型每轮重新理解一遍。状态字段的生命周期要明确：会话内有效、会话结束清理、敏感信息加密存储。记住：让状态管理显式化，比让模型“隐含记住”可靠得多。
6. 技能的质量评估与持续迭代：怎么证明你的技能库在变好
到这一步，技能库已经有了一定规模，能跑通不少业务。但一个躲不开的问题是：如何证明它确实在变好？评估体系和迭代机制缺一不可。
6.1 从“调用量”到“任务完成率”：找到正确的北极星指标
很多人一开始用“技能调用次数”来衡量技能的价值，这个指标会骗人。调用次数多，可能只是说明技能被频繁触发，并不代表用户的任务被顺利解决。
我建议把核心指标定在任务完成率上，也就是：用户发起一个需求，Agent在整段对话里是否最终实现了用户目标。具体到技能层，拆解为四个细分指标：
- 触发准确率：该用某个技能的问题里，正确触发比例。
- 参数有效调用率：触发的调用里，参数合法且执行成功的比例。
- 结果采纳率：执行成功后，返回结果被用户认可并按需使用的比例（可以用用户反馈、点击行为等代理指标）。
- 技能失败恢复率：技能执行失败后，Agent还能通过其他方式完成同一目标的比例。
这四个指标合在一起，才算是完整刻画了技能在真实业务中的价值。单独看任何一个，都容易产生错觉。
6.2 线上监控与链路追踪：技能出问题时，怎么快速定位
技能规模变大之后，排障效率会成为新的瓶颈。我的经验是要建立一套从“用户会话”到“技能调用”的可追踪链路。
每次技能调用，至少要记录以下信息：
- 会话ID和用户ID
- 触发时的用户原始问题（完整原文）
- 模型选中的技能名称和置信度
- 传入参数的完整快照
- 执行体的返回结果或错误信息
- 单次调用的耗时和资源消耗
这些日志统一沉淀到检索系统里，支持按会话ID查全链路，按技能名称查调用分布。排查问题时，最有效的起手式通常都是：把失败会话的原始日志拉出来，看模型是怎么理解用户意图的、为什么选了某个技能、参数在哪个环节出了问题。这一步不需要多高深的技术，但能把排查时间从小时级降到分钟级。
6.3 从反馈闭环到技能演进：把每一次失败变成技能升级的燃料
评估体系建立的最终目的，是驱动技能持续演进。我把这个闭环总结成四步：
- 收集失败样本：从线上日志里把任务完成失败的会话捞出来，按失败原因打标签（描述歧义、参数错误、执行异常、路由误选）。
- 聚类分析根因：把相似失败样本归成一类，找到共性原因。通常80%的失败集中在少数几个根因上，优先处理Top类目。
- 针对性优化：根据根因调整技能描述、Schema、执行体或路由策略。每次改动要小，以便评估效果。
- 批量回归验证：把修改后的技能放回评测集里全量跑一遍，确保修复了旧问题、没有引入新问题。
我见过最高效的团队，几乎把“失败样本→根因分析→技能迭代”跑成了日常机制，每周都有版本更新，技能库在持续迭代中变得越来越厚实。反观那些上线后就不动的技能库，三个月后基本就沦为“演示环境能跑、生产环境没法用”的花架子。
自己做完这套体系后的体会是：Agent类项目拼到最后，拼的不是谁家模型参数大，而是谁的技能库更厚、更稳、更能抗真实业务的杂音。模型是发动机，技能库才是底盘和悬挂。发动机决定极速，底盘决定你到底能开多快而不翻车。希望这篇文章能帮正准备建技能库、或者已经在路上被各种问题困扰的团队，少走几段弯路。
