先别急着给Agent写代码如果你正打算磕“agent-skills”我强烈建议你先停下来把几个关键思路理清。这个概念的圈内热度已经持续了不短的时间很多人把它理解为“给Agent塞几十个工具函数就完事”但真正做落地的时候你会发现技能的定义方式、描述质量、参数设计和加载机制每一条都足以让你的智能体在可用和不可用之间反复横跳。今天这篇不打算做教程式的罗列而是顺着我实操了一套售后智能体技能库的过程把设计思路、踩坑细节和排障技巧完整拆出来讲。读下去之前先说明一下它适合谁。如果你正在做LLM Agent应用或者准备把现有的服务改造成Agent可调用的能力单元这篇文章能帮你少走不少弯路。即使你暂时只是感兴趣理解技能体系对后续学习Agent开发也有很大帮助。我会尽量把每个决策背后的原因讲透因为技能系统的成败往往就隐藏在“为什么这样设计”里。1. 从一场“技能混乱”说起为什么Agent需要技能化1.1 踩过的坑单体提示词为什么不靠谱先讲一个我实际遇到的案例。早前一个模拟的智能售后客服项目里产品同学要求Agent能同时处理退换货、物流查询、订单修改和运费计算。当时为了赶工期我选择了一条“最省事”的路把上述所有业务的参数说明、操作步骤、注意事项全部塞进一条系统提示词里然后让模型直接生成最终回复或调用接口。刚开始demo效果还不错简单问题都能答。但当用户问了一句“我昨天买的那个蓝色毛衣能换成灰色吗”模型先是调用了订单查询接着又尝试调用退换货申请然后在中间自行臆想了一个“换货”接口最后返回的售后服务单号居然是个根本不存在的格式。我细看日志发现模型在前几轮已经产生了上下文幻觉面对一大段混杂着规则和工具的提示词它根本分不清哪条指令对应哪个动作。这就是单体提示词的典型问题。人看起来信息很全但模型是个概率引擎它更倾向于在相似语义中挑选最顺滑的那条路径。功能越堆越重上下文越长互相干扰越严重出错率呈指数上升。当时我在日志里看到模型多次把“查询运费”和“计算运费”混为一谈比如传参时把包裹重量填进订单金额字段。那一刻我意识到真正的问题不是提示词写得不够清楚而是能力的表达方式不适合模型理解。后来我把每个能力拆成独立技能问题立刻开始好转。拆分的核心原则很简单一个技能只负责一件事。查询归查询换货归换货计算归计算。模型每次只需要根据用户请求选择一个最匹配的技能然后按照技能描述传参即可不再需要从上百行规则里猜答案。1.2 技能化到底是什么以及设计原则那么agent-skills中的“技能”到底指什么我的理解是一个可被模型动态发现、按需调用的原子化能力单元。它不只是一个函数接口而是一整套包含名称、用途描述、参数约束、业务逻辑边界、失败处理方式的语义包。这个设计背后有几个原则我觉得比写代码本身更重要。第一是高内聚低耦合。每个技能内部可以很复杂比如“创建退换货工单”可能涉及库存锁定、审核规则、物流单号生成但对Agent来说它只需要知道输入哪些参数、输出什么结果。技能作为一个黑盒外部无需关心内部实现。这能有效降低模型理解和调用的难度。第二是描述面向模型而不是面向人。我们写函数注释时习惯面向同事写“此函数用于处理换货申请注意不要用于退货”但模型读到这种描述并不会有清晰的触发边界。更合适的写法是“当用户要求更换已购商品颜色、尺码、款式不同时调用本技能如果用户要求退款或取消订单请勿调用本技能。”只有描述足够具体模型才不容易出现语义漂移。第三是单一责任、可测试。一个技能只做一件事便于单测也便于后续调优。如果技能内部逻辑过于广泛出了问题很难定位模型也容易在调用边界上犯错。我后来把原来的“订单处理”技能拆成了五个独立技能整体调用成功率不降反升因为模型每次都能锁定唯一的操作不再犹豫。1.3 技能与工具、插件、工作流的边界很多朋友容易把Agent技能、工具、插件和工作流混在一起实际上它们确实有重叠但侧重点不同需要理清。工具是一个比较宽泛的概念任何可被调用的外部能力都算工具比如一个HTTP API、一个数据库查询接口。技能则是在工具之上增加了一层面向模型的语义封装。换句话说同一个工具可能对应多个技能同一个技能也可能调用多个底层工具来完成一件事。插件在更多时候指运行平台上的一组扩展功能可以包含页面、权限、运行时环境不一定是面向LLM的。而工作流的重点是将多个技能和逻辑节点按特定顺序编排使其完成一个较长的业务过程。技能是工作流的积木单独存在随时可被复用。我在设计技能系统时会先梳理所有底层API对应关系然后把API封装成基础技能再把基础技能通过工作流组合成复杂操作。例如“自动赔偿”技能就串联了订单查询、运费计算、退款申请三个基础技能。这样做的好处是任何一层替换掉都不会影响其他部分模型看到的技能列表始终是经过梳理的、边界清晰的集合。2. 技能的核心细节命名、描述、参数与语义绑定2.1 一份靠谱的技能描述长什么样在技能系统中名称和描述是模型决策的主要依据这直接决定了调用准确率。我一度以为描述写得越长越好后来发现完全不是这么回事。太长的描述会发散模型注意力太短则造成误调关键是做到“何时用、何时不用、输入输出是什么、有哪些注意点”。我这里有一个比较通用的描述模板技能名称create_exchange_order 技能用途当用户希望对已购买的商品进行换货申请如更换颜色、尺码、款式时调用。 不适用场景用户要求退货退款、取消订单、重新购买此时不要调用本技能应使用对应技能。 输入参数用户订单号、需更换的商品SKU、更换原因可选。 输出售后换货工单号以及预计处理时间。 注意事项订单必须处于已完成状态未发货或已超过售后期的订单无法换货。你会发现这里的描述用了大量的“当”、“如果”、“不要”这类条件句。原因是模型在函数调用决策时本质上在做二分类这个技能适合当前场景还是不适合。给它越清晰的边界条件分类准确率越高。我还习惯在描述里加上一些“负面标记”也就是明确告诉模型什么情况下不要使用该技能。很多文档不会写这一点但实践证明它能显著减少误调用。比如物流查询技能的“不适用场景”写的是“当用户询问预计送达时间时如有承运商官方承诺时间请直接回复不要调用物流查询”。这条约束看着反直觉却有效避免了模型为了一个简单信息去查库白白增加耗时。2.2 参数约束与Schema设计少踩坑的关键模型调用技能时最可怕的不是调用错而是传错参数。很多错误的来源都在Schema设计上。早期的技能参数只写了必要的字段名没有给类型、取值范围、格式说明模型就经常把“今天”转成字符串“今日”把订单编号填成用户昵称。我强烈建议所有技能参数都使用JSON Schema结构并且充分使用description、enum、pattern这些字段。举例来说日期参数如果让模型自由输入它可能给出“3/12”或“三月十二日”等不同格式导致后端解析失败。你可以在schema里加上pattern“^\d{4}-\d{2}-\d{2}$”并且配套说明“日期格式必须为YYYY-MM-DD今天是2025-04-03请根据用户表述换算成标准日期。”更关键的技巧是尽量使用枚举替代开放式输入。比如售后原因尽量提供“质量问题 / 7天无理由 / 发错货 / 不喜欢”等几个枚举值让模型做选择题而不是填空题。模型在选择题上的准确率远高于填空题这是自然语言处理中很常见的一个现象。同时每个字段都要配一个“用于大模型提示”的描述。不要只写“order_id 是订单编号”而应该写“用户提到的订单号通常为15位数字带字母前缀表示海外订单”。这样模型才会自动提取准确信息。2.3 技能注册、加载与版本管理技能设计好之后还必须让它能顺畅地进入Agent的运行环境。我自己构建技能库时目录结构是这么规划的skills/ order_management/ __init__.py query_order.py create_exchange_order.py calculate_refund.py skill.yaml logistics/ query_logistics.py skill.yaml每个技能目录会有一个“skill.yaml”文件里面保存技能ID、名称、描述、入口函数、参数schema、权限等级等元信息。启动服务时系统会扫描这个目录把技能动态注册到Agent的函数调用列表里。这样新技能上线不用重启会话只要重新加载配置即可。版本管理同样重要。技能代码是会迭代的但模型可能已经学会了旧技能的描述方式。如果直接覆盖旧版本一些进行中的会话可能会调用失败。我在实践中会给技能增加版本号并且保留历史版本。新的对话默认使用最新版已经开始的会话则继续绑定调用时的版本避免中途能力变化导致错误。另外灰度发布也很有用先让一定比例流量使用新版本观察真实调用成功率后再全量切换。这样即使新版的描述有问题影响面也不会太大。3. 把技能组装成Agent一个可落地的实操案例3.1 案例背景一个“智能售后助手”的技能栈为了把抽象的概念落到实际我设计了一个模拟的“智能售后助手”它面向一个模拟电商项目的用户售后场景。业务诉求包括查询订单、查看物流、申请换货、申请退货、计算补偿金额、查看售后进度。这六个核心需求构成了一个完整的技能栈。技能ID技能名称底层API核心输入query_order查询订单详情订单服务API订单号query_logistics查询物流轨迹物流服务API订单号、物流公司可选create_exchange创建换货工单售后系统API订单号、新SKU、原因create_return创建退货工单售后系统API订单号、退款金额、原因calculate_compensation计算补偿金额规则引擎API订单号、补偿类型query_after_sale查询售后进度工单服务API售后单号这里每个技能都对应一个真实存在的底层API。Agent本身不直接处理业务逻辑只负责理解用户意图把自然语言转成结构化参数然后调用技能再把技能返回的结果转述给用户。这个过程说起来简单但编排起来相当讲究。3.2 从0到1编写技能退换货处理技能示例我以其中的“create_exchange”技能为例看一下技能代码在结构上应该怎么组织。技能核心是一个标准的Python函数但需要额外挂载一份schema描述。# skills/order_management/create_exchange.py import json from typing import Optional from pydantic import BaseModel, Field class ExchangeOrderParams(BaseModel): order_id: str Field( description用户的订单号通常为15位数字海外订单含字母前缀, patternr^[A-Za-z]?\d{8,20}$ ) new_sku_id: str Field( description用户希望更换到的商品SKU编号必须是已上架的SKU, patternr^SKU-\d{6}$ ) reason: Optional[str] Field( defaultNone, enum[size_change, color_change, quality_issue, not_like, other], description换货原因尽量从枚举中选择, ) def create_exchange(params: dict) - dict: # 实际业务可在这里调用售后系统的HTTP接口 # 这里仅作结构示例 body { order_id: params[order_id], new_sku_id: params[new_sku_id], reason: params.get(reason, other), } # response requests.post(http://after-sale-service/api/exchange, jsonbody) # 返回值统一为 {success: bool, result: {...}, error: str|None} return { success: True, result: { exchange_id: EX20250403001, status: pending_approval, expected_days: 3, }, error: None, }这段代码有三个值得留意的点。第一我用了pydantic模型来做参数校验这能保证在进入业务逻辑之前非法参数就已经被拦截。第二schema里的description与我之前提到的技巧一致字段描述尽量带上识别特征。第三返回结构统一固定为success, result, error三段式让后续Agent处理结果时非常简单。技能代码编写完成后还需要在skill.yaml里注册描述信息这样Agent运行时才会看到它。下面是一个真实使用过的描述片段。skill_id: create_exchange name: 创建换货工单 description: 当用户表达“想换”、“换颜色”、“换尺码”等意图时调用。 注意用户如果要求退货退钱请调用create_return技能 如果用户还没有下单请先调用query_order确认。 input_schema: schema/create_exchange.json entry_point: skills.order_management.create_exchange:create_exchange permission_level: user看到这里你可能会问既然技能代码里已经有schema为什么还要在yaml里重复描述因为这两者作用对象不同。代码里的pydantic model用于运行时的数据校验yaml里的description用于给模型生成调用决策。前者是给机器读的后者是给模型“读”的两者缺一不可。3.3 调用流程编排与多技能协同技能各自独立之后Agent的调用流程依然需要好好设计。一次真实的用户请求可能涉及多个技能例如“我这个订单想换货顺便看看现在到哪一步了”这里既需要订单查询又需要创建换货工单还可能涉及售后进度查询。我采用的方法是先让Agent分析整体用户意图作出一个粗粒度的“计划”再逐步执行。这个计划不需要单独建复杂框架而是依赖系统提示词里的路由指令。系统里先注册所有技能然后给Agent一条硬性要求多步操作必须分步执行前一步的成功结果是后一步的前置条件如果某一步失败立即停止并告知用户。举个实际调用的例子用户发送“订单ORD20250403180蓝色尺码不要了换成红色的。”Agent内部会先选择“query_order”确认该订单存在且处于允许换货的状态。接着调用“create_exchange”参数自动填充为order_idORD20250403180new_sku_idSKU-301288reasoncolor_change。这时因为换货申请必须锁定原库存所以Agent还需要再调用一次“query_after_sale”来检查工单状态。最终把“换货成功工单EX20250403001已生成预计3天审核”反馈给用户。这个过程中技能之间没有硬编码调用链而是由模型动态决定顺序。只要描述清楚模型大多数时候能做出正确顺序。为了保证可靠性我还会在服务端记录每个技能调用的完整链路一旦发现某一步的调用顺序频繁出现逆向问题就会在其中加入提示词限制例如“在调用create_exchange之前必须先完成query_order并确认订单状态”。3.4 运行效果与实测数据模拟我搭建这个技能系统后做了一个小规模的对比测试同样一万条模拟用户消息分别用旧的单体提示词方案和新的技能化方案跑了一遍。在旧方案里售后意图识别的准确率约为85%但技能参数错误率接近20%很多用户反馈服务单号对不上。换成技能化方案后因为每个技能描述清晰、参数约束明确配合后端校验逻辑准确率提升到了96%左右参数错误率降到了5%以下。平均响应时间也明显缩短。旧方案面对复杂查询时模型要反复回忆规则平均需要3.2秒完成一次完整调用新方案因为每个技能只有局部上下文模型很快能定位到相关函数平均响应时间降到了2.1秒。当然这个数据只代表模拟场景但它反映了一个普遍规律上下文更短、结构更清晰的技能比一个大而全的提示词更容易让模型高效工作。我还是要提醒不要盲目追求技能数量。技能化之后如果你一股脑注册上百个技能模型同样会在顺序选择上蒙圈。我后面的经验是技能粒度先粗一点比如先把“物流查询”做成一个技能等遇到大量用户分不清顺丰和圆通时的差异化需求再拆成“查询顺丰物流”和“查询圆通物流”。这个“先粗后细”的策略能降低维护成本。4. 常见故障与排障实操4.1 技能不生效排查注册与加载链技能系统上线后最常遇到的故障就是你在代码里写了一个新技能但Agent就是不调用它。第一条排查思路是确认技能是否被正常扫描注册。我通常会在本地环境直接调技能管理接口查一下当前注册的技能列表。如果列表里没有新技能说明目录扫描环节出了问题往往是yaml文件写法有误或者文件名没按约定命名。如果技能列表里有但模型就是不使用那就需要继续排查Agent拿到的函数列表。很多框架在初始化时会缓存一份工具列表新技能如果未触发reload模型永远不会感知到它存在。我会在系统日志里打印Agent每次可用的技能清单确认模型实际上看到了哪些技能。有一次我发现某个技能已经注册但模型看不到原因是我把权限级别设成了admin而当前的测试用户是普通用户技能被权限过滤掉了。这类问题不会报错但非常隐蔽建议你在设计权限体系时给每个角色列一个“可见技能”的清单方便对照检查。最后一定要确认技能函数本身能不能跑通。如果函数内部有异常Agent调用时会收到错误信息这个错误信息可能被模型吞掉表现为“不执行”。所以技能代码要单独写单元测试再挂到Agent上。4.2 参数错乱与幻觉——如何让Agent正确选参参数问题是高频头疼点。某次在测试里我让模型调用“calculate_compensation”结果它在“补偿类型”参数上传入了“退款金额”这四个字而不是枚举值“refund_amount”。这种情况多半是因为schema缺少枚举描述模型只能自由发挥。解决方法是把所有参数都尽量收敛到有限集合里。另一类幻觉是模型在调用前自行修改参数值。比如用户说“上周买的”模型自作主张把日期换算成本周日期导致查询为空。办法是在schema的参数描述里追加一句“请直接使用用户提供的原始信息不要转换格式或推测时间除非系统当前日期与用户表述明显矛盾”。当模型连续两次调用同一技能失败时通常会陷入自我修正的循环。我建议在Agent层设置最大重试次数默认一次最多两次。第二次失败后就不再调用直接返回一个“服务暂时不可用”的回答并且把失败日志推送出来。这样能避免模型在错误的参数上反复尝试空耗时间和预算。4.3 技能冲突、重复与调用顺序问题随着技能数量增多冲突问题会浮出水面。典型情况是“查询订单”、“查看订单详情”、“订单状态查询”这三个技能描述高度相似模型经常随机选一个。我的处理策略很粗暴如果多个技能面向同一个底层API就只保留一个如果必须保留多个那么在描述里要明确写出差异点比如“查询订单详情返回全部字段查询订单状态只返回状态字段适合快速确认是否发货”。调用顺序问题则往往出现在复杂任务中。比如售后助手应当先确认订单状态再创建换货单但模型偶尔会反过来。我在实践中会把这些“先后关系”固化在系统提示词的少量示例里而不是给模型自由发挥。一个简单的做法是在技能描述中显式加上预处理请求例如在“create_exchange”的“不适用场景”里写“如果订单状态未知请先调用query_order”这样模型在决策时会把这些约束当作硬性规则来参考。如果这些文字约束还不够可以引入一个轻量的“检查器”在技能调用前对前置条件做代码判断。一旦前置条件不满足直接返回“前置条件未满足订单已取消无法换货”这样模型就不会继续错误调用。4.4 性能与成本减少无效调用的技巧每次技能调用都会消耗模型token。尤其是多步骤对话中Agent可能会因为疑心而连续调用多个技能哪怕最终并不需要。我在项目中统计过大约有30%的技能调用其实是冗余的可以避免。一个很管用的技巧是设置“技能调用门槛”。比如物流查询如果用户只是随口问“我的货应该快到了吧”Agent完全可以先用系统当前时间加上正常的物流时效来推断不需要立刻调库。在技能描述里写明“实在无法判断时再调用”能大幅降低调用频率。我甚至在某些技能上加了“缓存优先”策略把相同请求的结果存起来五分钟内的重复请求直接返回缓存不再触发模型深度推理。另一个成本控制手段是使用小型意图模型做前置路由。一个轻量级的文本分类器先判断用户问题属于查询单号、退款、换货还是闲聊只有识别为“需要技能”的分类才把请求交给大模型完整推理。这样也让大模型专注于真正复杂的能力调用实测能让token消耗降低25%左右同时因为过滤掉大量无关请求整体响应速度也变快了。5. 技能系统的进阶设计从单Agent到多Agent协作5.1 技能共享库与权限隔离当你的项目从单Agent升级为多Agent时技能系统就会从“工具区”变成“基础设施”。比如一个公司可能有售后Agent、订单分析Agent、内部流程Agent它们都需要各自的技能其中一部分技能是可以共享的比如用户身份校验、订单基础查询。共享能显著减少重复开发但也会带来权限问题。我建议把技能库按照命名空间和层级来组织。基础技能放在common命名空间只允许只读引用业务技能放在各自Agent的命名空间内允许对应Agent修改。每个技能配置中增加owners和allowed_callers字段校验通过后才允许加载到某个Agent的工具列表。这样既保证了业务隔离又避免了误操作导致的全域污染。权限隔离还有一层意思不能随便让Agent直接感知其他Agent的技能。否则模型在对话中可能会调用超过其职责范围的能力造成信息泄露或误操作。所以在加载技能时要严格按Agent角色进行绑定而不是一次性把所有技能塞给一个Agent。5.2 技能的动态编译与自我修正手工维护技能总归有些累。进阶一点的玩法是让系统根据用户的真实问题自动发现缺失的技能需求然后半自动生成技能草案。比如分析发现大量用户都在询问“包裹破损怎么赔偿”可是当前技能库里没有对应的赔偿技能系统就可以基于规则引擎生成一个简单的“破损赔偿咨询”技能先提供给Agent试用测试通过后再发布为正式技能。这个过程我建议做“人机协同”。让模型生成代码和描述但必须通过沙箱测试由人工审核后再上线。完全自动发布技能看起来方便实际操作中很容易产生不可控的行为。我见过一个实验里自动生成的技能里包含了过于宽泛的“执行任意SQL”能力幸好有测试拦截否则后果不堪设想。所以自动化要克制让机器负责初稿人负责把关收敛。自我修正则是指根据线上调用失败率自动调整技能描述或参数模板。比如系统发现某技能因为日期格式错误导致失败率高自动把schema中的pattern修改为标准格式并推送一条优化描述给开发者审核。这类持续优化能力能让技能库在使用中逐渐变得更贴合实际场景而不是永远停留在原始设计。5.3 技能度量与持续优化技能到底好不好不能靠感觉必须有数据。我为自己搭建的技能体系设计了一套指标重点看四个维度调用成功率、参数错误率、二次调用率、用户反馈满意度。调用成功率是基础参数错误率反映schema是否足够清晰二次调用率指在一次对话中同一个技能被重复调用的比例过高说明技能可能没一次性解决用户问题用户满意度可以从对话后的评分间接获得。我会定期拉取这些指标每个月做一次技能盘点。调用量低的技能看看描述是不是被其他技能覆盖了调用失败率高的技能优先优化参数约束二次调用率高的技能可能需要把输出结果做得更完整。优化技能这件事就像整理工具箱不是一次性工作而是持续迭代的过程。还有一个值得留意的细节技能并不是越多越好。每次增加技能都会增加模型做选择时的干扰项。我在项目里经历过从60个技能精简到24个技能后整体意图识别准确率反而提升了五个百分点。所以在技能库实现“瘦身”也是一项重要任务。删掉冗余合并重复比盲目添加新技能价值更高。最后再分享一个小技巧在做技能设计的时候多想想描述里可能被模型误读的词。比如“订单状态”就比“订单信息”更具体“订单是否已发货”又比“订单状态”更明确。技能之间要保持的是可区分的、靠近业务结果的语义边界。别怕一开始设计得不完美实际跑起来之后不断调整技能库会慢慢长成你想要的样子。
先别急着给Agent写代码如果你正打算磕“agent-skills”我强烈建议你先停下来把几个关键思路理清。这个概念的圈内热度已经持续了不短的时间很多人把它理解为“给Agent塞几十个工具函数就完事”但真正做落地的时候你会发现技能的定义方式、描述质量、参数设计和加载机制每一条都足以让你的智能体在可用和不可用之间反复横跳。今天这篇不打算做教程式的罗列而是顺着我实操了一套售后智能体技能库的过程把设计思路、踩坑细节和排障技巧完整拆出来讲。读下去之前先说明一下它适合谁。如果你正在做LLM Agent应用或者准备把现有的服务改造成Agent可调用的能力单元这篇文章能帮你少走不少弯路。即使你暂时只是感兴趣理解技能体系对后续学习Agent开发也有很大帮助。我会尽量把每个决策背后的原因讲透因为技能系统的成败往往就隐藏在“为什么这样设计”里。1. 从一场“技能混乱”说起为什么Agent需要技能化1.1 踩过的坑单体提示词为什么不靠谱先讲一个我实际遇到的案例。早前一个模拟的智能售后客服项目里产品同学要求Agent能同时处理退换货、物流查询、订单修改和运费计算。当时为了赶工期我选择了一条“最省事”的路把上述所有业务的参数说明、操作步骤、注意事项全部塞进一条系统提示词里然后让模型直接生成最终回复或调用接口。刚开始demo效果还不错简单问题都能答。但当用户问了一句“我昨天买的那个蓝色毛衣能换成灰色吗”模型先是调用了订单查询接着又尝试调用退换货申请然后在中间自行臆想了一个“换货”接口最后返回的售后服务单号居然是个根本不存在的格式。我细看日志发现模型在前几轮已经产生了上下文幻觉面对一大段混杂着规则和工具的提示词它根本分不清哪条指令对应哪个动作。这就是单体提示词的典型问题。人看起来信息很全但模型是个概率引擎它更倾向于在相似语义中挑选最顺滑的那条路径。功能越堆越重上下文越长互相干扰越严重出错率呈指数上升。当时我在日志里看到模型多次把“查询运费”和“计算运费”混为一谈比如传参时把包裹重量填进订单金额字段。那一刻我意识到真正的问题不是提示词写得不够清楚而是能力的表达方式不适合模型理解。后来我把每个能力拆成独立技能问题立刻开始好转。拆分的核心原则很简单一个技能只负责一件事。查询归查询换货归换货计算归计算。模型每次只需要根据用户请求选择一个最匹配的技能然后按照技能描述传参即可不再需要从上百行规则里猜答案。1.2 技能化到底是什么以及设计原则那么agent-skills中的“技能”到底指什么我的理解是一个可被模型动态发现、按需调用的原子化能力单元。它不只是一个函数接口而是一整套包含名称、用途描述、参数约束、业务逻辑边界、失败处理方式的语义包。这个设计背后有几个原则我觉得比写代码本身更重要。第一是高内聚低耦合。每个技能内部可以很复杂比如“创建退换货工单”可能涉及库存锁定、审核规则、物流单号生成但对Agent来说它只需要知道输入哪些参数、输出什么结果。技能作为一个黑盒外部无需关心内部实现。这能有效降低模型理解和调用的难度。第二是描述面向模型而不是面向人。我们写函数注释时习惯面向同事写“此函数用于处理换货申请注意不要用于退货”但模型读到这种描述并不会有清晰的触发边界。更合适的写法是“当用户要求更换已购商品颜色、尺码、款式不同时调用本技能如果用户要求退款或取消订单请勿调用本技能。”只有描述足够具体模型才不容易出现语义漂移。第三是单一责任、可测试。一个技能只做一件事便于单测也便于后续调优。如果技能内部逻辑过于广泛出了问题很难定位模型也容易在调用边界上犯错。我后来把原来的“订单处理”技能拆成了五个独立技能整体调用成功率不降反升因为模型每次都能锁定唯一的操作不再犹豫。1.3 技能与工具、插件、工作流的边界很多朋友容易把Agent技能、工具、插件和工作流混在一起实际上它们确实有重叠但侧重点不同需要理清。工具是一个比较宽泛的概念任何可被调用的外部能力都算工具比如一个HTTP API、一个数据库查询接口。技能则是在工具之上增加了一层面向模型的语义封装。换句话说同一个工具可能对应多个技能同一个技能也可能调用多个底层工具来完成一件事。插件在更多时候指运行平台上的一组扩展功能可以包含页面、权限、运行时环境不一定是面向LLM的。而工作流的重点是将多个技能和逻辑节点按特定顺序编排使其完成一个较长的业务过程。技能是工作流的积木单独存在随时可被复用。我在设计技能系统时会先梳理所有底层API对应关系然后把API封装成基础技能再把基础技能通过工作流组合成复杂操作。例如“自动赔偿”技能就串联了订单查询、运费计算、退款申请三个基础技能。这样做的好处是任何一层替换掉都不会影响其他部分模型看到的技能列表始终是经过梳理的、边界清晰的集合。2. 技能的核心细节命名、描述、参数与语义绑定2.1 一份靠谱的技能描述长什么样在技能系统中名称和描述是模型决策的主要依据这直接决定了调用准确率。我一度以为描述写得越长越好后来发现完全不是这么回事。太长的描述会发散模型注意力太短则造成误调关键是做到“何时用、何时不用、输入输出是什么、有哪些注意点”。我这里有一个比较通用的描述模板技能名称create_exchange_order 技能用途当用户希望对已购买的商品进行换货申请如更换颜色、尺码、款式时调用。 不适用场景用户要求退货退款、取消订单、重新购买此时不要调用本技能应使用对应技能。 输入参数用户订单号、需更换的商品SKU、更换原因可选。 输出售后换货工单号以及预计处理时间。 注意事项订单必须处于已完成状态未发货或已超过售后期的订单无法换货。你会发现这里的描述用了大量的“当”、“如果”、“不要”这类条件句。原因是模型在函数调用决策时本质上在做二分类这个技能适合当前场景还是不适合。给它越清晰的边界条件分类准确率越高。我还习惯在描述里加上一些“负面标记”也就是明确告诉模型什么情况下不要使用该技能。很多文档不会写这一点但实践证明它能显著减少误调用。比如物流查询技能的“不适用场景”写的是“当用户询问预计送达时间时如有承运商官方承诺时间请直接回复不要调用物流查询”。这条约束看着反直觉却有效避免了模型为了一个简单信息去查库白白增加耗时。2.2 参数约束与Schema设计少踩坑的关键模型调用技能时最可怕的不是调用错而是传错参数。很多错误的来源都在Schema设计上。早期的技能参数只写了必要的字段名没有给类型、取值范围、格式说明模型就经常把“今天”转成字符串“今日”把订单编号填成用户昵称。我强烈建议所有技能参数都使用JSON Schema结构并且充分使用description、enum、pattern这些字段。举例来说日期参数如果让模型自由输入它可能给出“3/12”或“三月十二日”等不同格式导致后端解析失败。你可以在schema里加上pattern“^\d{4}-\d{2}-\d{2}$”并且配套说明“日期格式必须为YYYY-MM-DD今天是2025-04-03请根据用户表述换算成标准日期。”更关键的技巧是尽量使用枚举替代开放式输入。比如售后原因尽量提供“质量问题 / 7天无理由 / 发错货 / 不喜欢”等几个枚举值让模型做选择题而不是填空题。模型在选择题上的准确率远高于填空题这是自然语言处理中很常见的一个现象。同时每个字段都要配一个“用于大模型提示”的描述。不要只写“order_id 是订单编号”而应该写“用户提到的订单号通常为15位数字带字母前缀表示海外订单”。这样模型才会自动提取准确信息。2.3 技能注册、加载与版本管理技能设计好之后还必须让它能顺畅地进入Agent的运行环境。我自己构建技能库时目录结构是这么规划的skills/ order_management/ __init__.py query_order.py create_exchange_order.py calculate_refund.py skill.yaml logistics/ query_logistics.py skill.yaml每个技能目录会有一个“skill.yaml”文件里面保存技能ID、名称、描述、入口函数、参数schema、权限等级等元信息。启动服务时系统会扫描这个目录把技能动态注册到Agent的函数调用列表里。这样新技能上线不用重启会话只要重新加载配置即可。版本管理同样重要。技能代码是会迭代的但模型可能已经学会了旧技能的描述方式。如果直接覆盖旧版本一些进行中的会话可能会调用失败。我在实践中会给技能增加版本号并且保留历史版本。新的对话默认使用最新版已经开始的会话则继续绑定调用时的版本避免中途能力变化导致错误。另外灰度发布也很有用先让一定比例流量使用新版本观察真实调用成功率后再全量切换。这样即使新版的描述有问题影响面也不会太大。3. 把技能组装成Agent一个可落地的实操案例3.1 案例背景一个“智能售后助手”的技能栈为了把抽象的概念落到实际我设计了一个模拟的“智能售后助手”它面向一个模拟电商项目的用户售后场景。业务诉求包括查询订单、查看物流、申请换货、申请退货、计算补偿金额、查看售后进度。这六个核心需求构成了一个完整的技能栈。技能ID技能名称底层API核心输入query_order查询订单详情订单服务API订单号query_logistics查询物流轨迹物流服务API订单号、物流公司可选create_exchange创建换货工单售后系统API订单号、新SKU、原因create_return创建退货工单售后系统API订单号、退款金额、原因calculate_compensation计算补偿金额规则引擎API订单号、补偿类型query_after_sale查询售后进度工单服务API售后单号这里每个技能都对应一个真实存在的底层API。Agent本身不直接处理业务逻辑只负责理解用户意图把自然语言转成结构化参数然后调用技能再把技能返回的结果转述给用户。这个过程说起来简单但编排起来相当讲究。3.2 从0到1编写技能退换货处理技能示例我以其中的“create_exchange”技能为例看一下技能代码在结构上应该怎么组织。技能核心是一个标准的Python函数但需要额外挂载一份schema描述。# skills/order_management/create_exchange.py import json from typing import Optional from pydantic import BaseModel, Field class ExchangeOrderParams(BaseModel): order_id: str Field( description用户的订单号通常为15位数字海外订单含字母前缀, patternr^[A-Za-z]?\d{8,20}$ ) new_sku_id: str Field( description用户希望更换到的商品SKU编号必须是已上架的SKU, patternr^SKU-\d{6}$ ) reason: Optional[str] Field( defaultNone, enum[size_change, color_change, quality_issue, not_like, other], description换货原因尽量从枚举中选择, ) def create_exchange(params: dict) - dict: # 实际业务可在这里调用售后系统的HTTP接口 # 这里仅作结构示例 body { order_id: params[order_id], new_sku_id: params[new_sku_id], reason: params.get(reason, other), } # response requests.post(http://after-sale-service/api/exchange, jsonbody) # 返回值统一为 {success: bool, result: {...}, error: str|None} return { success: True, result: { exchange_id: EX20250403001, status: pending_approval, expected_days: 3, }, error: None, }这段代码有三个值得留意的点。第一我用了pydantic模型来做参数校验这能保证在进入业务逻辑之前非法参数就已经被拦截。第二schema里的description与我之前提到的技巧一致字段描述尽量带上识别特征。第三返回结构统一固定为success, result, error三段式让后续Agent处理结果时非常简单。技能代码编写完成后还需要在skill.yaml里注册描述信息这样Agent运行时才会看到它。下面是一个真实使用过的描述片段。skill_id: create_exchange name: 创建换货工单 description: 当用户表达“想换”、“换颜色”、“换尺码”等意图时调用。 注意用户如果要求退货退钱请调用create_return技能 如果用户还没有下单请先调用query_order确认。 input_schema: schema/create_exchange.json entry_point: skills.order_management.create_exchange:create_exchange permission_level: user看到这里你可能会问既然技能代码里已经有schema为什么还要在yaml里重复描述因为这两者作用对象不同。代码里的pydantic model用于运行时的数据校验yaml里的description用于给模型生成调用决策。前者是给机器读的后者是给模型“读”的两者缺一不可。3.3 调用流程编排与多技能协同技能各自独立之后Agent的调用流程依然需要好好设计。一次真实的用户请求可能涉及多个技能例如“我这个订单想换货顺便看看现在到哪一步了”这里既需要订单查询又需要创建换货工单还可能涉及售后进度查询。我采用的方法是先让Agent分析整体用户意图作出一个粗粒度的“计划”再逐步执行。这个计划不需要单独建复杂框架而是依赖系统提示词里的路由指令。系统里先注册所有技能然后给Agent一条硬性要求多步操作必须分步执行前一步的成功结果是后一步的前置条件如果某一步失败立即停止并告知用户。举个实际调用的例子用户发送“订单ORD20250403180蓝色尺码不要了换成红色的。”Agent内部会先选择“query_order”确认该订单存在且处于允许换货的状态。接着调用“create_exchange”参数自动填充为order_idORD20250403180new_sku_idSKU-301288reasoncolor_change。这时因为换货申请必须锁定原库存所以Agent还需要再调用一次“query_after_sale”来检查工单状态。最终把“换货成功工单EX20250403001已生成预计3天审核”反馈给用户。这个过程中技能之间没有硬编码调用链而是由模型动态决定顺序。只要描述清楚模型大多数时候能做出正确顺序。为了保证可靠性我还会在服务端记录每个技能调用的完整链路一旦发现某一步的调用顺序频繁出现逆向问题就会在其中加入提示词限制例如“在调用create_exchange之前必须先完成query_order并确认订单状态”。3.4 运行效果与实测数据模拟我搭建这个技能系统后做了一个小规模的对比测试同样一万条模拟用户消息分别用旧的单体提示词方案和新的技能化方案跑了一遍。在旧方案里售后意图识别的准确率约为85%但技能参数错误率接近20%很多用户反馈服务单号对不上。换成技能化方案后因为每个技能描述清晰、参数约束明确配合后端校验逻辑准确率提升到了96%左右参数错误率降到了5%以下。平均响应时间也明显缩短。旧方案面对复杂查询时模型要反复回忆规则平均需要3.2秒完成一次完整调用新方案因为每个技能只有局部上下文模型很快能定位到相关函数平均响应时间降到了2.1秒。当然这个数据只代表模拟场景但它反映了一个普遍规律上下文更短、结构更清晰的技能比一个大而全的提示词更容易让模型高效工作。我还是要提醒不要盲目追求技能数量。技能化之后如果你一股脑注册上百个技能模型同样会在顺序选择上蒙圈。我后面的经验是技能粒度先粗一点比如先把“物流查询”做成一个技能等遇到大量用户分不清顺丰和圆通时的差异化需求再拆成“查询顺丰物流”和“查询圆通物流”。这个“先粗后细”的策略能降低维护成本。4. 常见故障与排障实操4.1 技能不生效排查注册与加载链技能系统上线后最常遇到的故障就是你在代码里写了一个新技能但Agent就是不调用它。第一条排查思路是确认技能是否被正常扫描注册。我通常会在本地环境直接调技能管理接口查一下当前注册的技能列表。如果列表里没有新技能说明目录扫描环节出了问题往往是yaml文件写法有误或者文件名没按约定命名。如果技能列表里有但模型就是不使用那就需要继续排查Agent拿到的函数列表。很多框架在初始化时会缓存一份工具列表新技能如果未触发reload模型永远不会感知到它存在。我会在系统日志里打印Agent每次可用的技能清单确认模型实际上看到了哪些技能。有一次我发现某个技能已经注册但模型看不到原因是我把权限级别设成了admin而当前的测试用户是普通用户技能被权限过滤掉了。这类问题不会报错但非常隐蔽建议你在设计权限体系时给每个角色列一个“可见技能”的清单方便对照检查。最后一定要确认技能函数本身能不能跑通。如果函数内部有异常Agent调用时会收到错误信息这个错误信息可能被模型吞掉表现为“不执行”。所以技能代码要单独写单元测试再挂到Agent上。4.2 参数错乱与幻觉——如何让Agent正确选参参数问题是高频头疼点。某次在测试里我让模型调用“calculate_compensation”结果它在“补偿类型”参数上传入了“退款金额”这四个字而不是枚举值“refund_amount”。这种情况多半是因为schema缺少枚举描述模型只能自由发挥。解决方法是把所有参数都尽量收敛到有限集合里。另一类幻觉是模型在调用前自行修改参数值。比如用户说“上周买的”模型自作主张把日期换算成本周日期导致查询为空。办法是在schema的参数描述里追加一句“请直接使用用户提供的原始信息不要转换格式或推测时间除非系统当前日期与用户表述明显矛盾”。当模型连续两次调用同一技能失败时通常会陷入自我修正的循环。我建议在Agent层设置最大重试次数默认一次最多两次。第二次失败后就不再调用直接返回一个“服务暂时不可用”的回答并且把失败日志推送出来。这样能避免模型在错误的参数上反复尝试空耗时间和预算。4.3 技能冲突、重复与调用顺序问题随着技能数量增多冲突问题会浮出水面。典型情况是“查询订单”、“查看订单详情”、“订单状态查询”这三个技能描述高度相似模型经常随机选一个。我的处理策略很粗暴如果多个技能面向同一个底层API就只保留一个如果必须保留多个那么在描述里要明确写出差异点比如“查询订单详情返回全部字段查询订单状态只返回状态字段适合快速确认是否发货”。调用顺序问题则往往出现在复杂任务中。比如售后助手应当先确认订单状态再创建换货单但模型偶尔会反过来。我在实践中会把这些“先后关系”固化在系统提示词的少量示例里而不是给模型自由发挥。一个简单的做法是在技能描述中显式加上预处理请求例如在“create_exchange”的“不适用场景”里写“如果订单状态未知请先调用query_order”这样模型在决策时会把这些约束当作硬性规则来参考。如果这些文字约束还不够可以引入一个轻量的“检查器”在技能调用前对前置条件做代码判断。一旦前置条件不满足直接返回“前置条件未满足订单已取消无法换货”这样模型就不会继续错误调用。4.4 性能与成本减少无效调用的技巧每次技能调用都会消耗模型token。尤其是多步骤对话中Agent可能会因为疑心而连续调用多个技能哪怕最终并不需要。我在项目中统计过大约有30%的技能调用其实是冗余的可以避免。一个很管用的技巧是设置“技能调用门槛”。比如物流查询如果用户只是随口问“我的货应该快到了吧”Agent完全可以先用系统当前时间加上正常的物流时效来推断不需要立刻调库。在技能描述里写明“实在无法判断时再调用”能大幅降低调用频率。我甚至在某些技能上加了“缓存优先”策略把相同请求的结果存起来五分钟内的重复请求直接返回缓存不再触发模型深度推理。另一个成本控制手段是使用小型意图模型做前置路由。一个轻量级的文本分类器先判断用户问题属于查询单号、退款、换货还是闲聊只有识别为“需要技能”的分类才把请求交给大模型完整推理。这样也让大模型专注于真正复杂的能力调用实测能让token消耗降低25%左右同时因为过滤掉大量无关请求整体响应速度也变快了。5. 技能系统的进阶设计从单Agent到多Agent协作5.1 技能共享库与权限隔离当你的项目从单Agent升级为多Agent时技能系统就会从“工具区”变成“基础设施”。比如一个公司可能有售后Agent、订单分析Agent、内部流程Agent它们都需要各自的技能其中一部分技能是可以共享的比如用户身份校验、订单基础查询。共享能显著减少重复开发但也会带来权限问题。我建议把技能库按照命名空间和层级来组织。基础技能放在common命名空间只允许只读引用业务技能放在各自Agent的命名空间内允许对应Agent修改。每个技能配置中增加owners和allowed_callers字段校验通过后才允许加载到某个Agent的工具列表。这样既保证了业务隔离又避免了误操作导致的全域污染。权限隔离还有一层意思不能随便让Agent直接感知其他Agent的技能。否则模型在对话中可能会调用超过其职责范围的能力造成信息泄露或误操作。所以在加载技能时要严格按Agent角色进行绑定而不是一次性把所有技能塞给一个Agent。5.2 技能的动态编译与自我修正手工维护技能总归有些累。进阶一点的玩法是让系统根据用户的真实问题自动发现缺失的技能需求然后半自动生成技能草案。比如分析发现大量用户都在询问“包裹破损怎么赔偿”可是当前技能库里没有对应的赔偿技能系统就可以基于规则引擎生成一个简单的“破损赔偿咨询”技能先提供给Agent试用测试通过后再发布为正式技能。这个过程我建议做“人机协同”。让模型生成代码和描述但必须通过沙箱测试由人工审核后再上线。完全自动发布技能看起来方便实际操作中很容易产生不可控的行为。我见过一个实验里自动生成的技能里包含了过于宽泛的“执行任意SQL”能力幸好有测试拦截否则后果不堪设想。所以自动化要克制让机器负责初稿人负责把关收敛。自我修正则是指根据线上调用失败率自动调整技能描述或参数模板。比如系统发现某技能因为日期格式错误导致失败率高自动把schema中的pattern修改为标准格式并推送一条优化描述给开发者审核。这类持续优化能力能让技能库在使用中逐渐变得更贴合实际场景而不是永远停留在原始设计。5.3 技能度量与持续优化技能到底好不好不能靠感觉必须有数据。我为自己搭建的技能体系设计了一套指标重点看四个维度调用成功率、参数错误率、二次调用率、用户反馈满意度。调用成功率是基础参数错误率反映schema是否足够清晰二次调用率指在一次对话中同一个技能被重复调用的比例过高说明技能可能没一次性解决用户问题用户满意度可以从对话后的评分间接获得。我会定期拉取这些指标每个月做一次技能盘点。调用量低的技能看看描述是不是被其他技能覆盖了调用失败率高的技能优先优化参数约束二次调用率高的技能可能需要把输出结果做得更完整。优化技能这件事就像整理工具箱不是一次性工作而是持续迭代的过程。还有一个值得留意的细节技能并不是越多越好。每次增加技能都会增加模型做选择时的干扰项。我在项目里经历过从60个技能精简到24个技能后整体意图识别准确率反而提升了五个百分点。所以在技能库实现“瘦身”也是一项重要任务。删掉冗余合并重复比盲目添加新技能价值更高。最后再分享一个小技巧在做技能设计的时候多想想描述里可能被模型误读的词。比如“订单状态”就比“订单信息”更具体“订单是否已发货”又比“订单状态”更明确。技能之间要保持的是可区分的、靠近业务结果的语义边界。别怕一开始设计得不完美实际跑起来之后不断调整技能库会慢慢长成你想要的样子。
