1. 技能系统在智能体架构里的定位1.1 为什么技能是智能体的核心资产做AI应用开发的同行应该都有体会大模型本身是聪明的“大脑”但光有大脑没有手脚它什么都干不了。一个只有对话能力的Agent充其量是个聊天机器人真正能落地解决问题的Agent靠的就是它身上挂载的技能Skills。我在实际项目里经常打一个比方模型负责“想清楚做什么”技能负责“手脚麻利把事办了”。agent-skills简单说就是智能体的“能力插件库”。它把一次具体的业务能力——比如查天气、发邮件、操作数据库、调用内部API——封装成一套机器可读、模型可理解、执行时可调用的标准单元。技能系统的设计水平直接决定了你的Agent在真实业务里能干到什么程度是只能嘴上说说“我可以帮你查库存”还是真能拉出实时的库存数并生成补货单。我见过太多团队在模型选型、Prompt调优上花掉80%的精力结果Agent上线后翻车全翻在技能层技能描述写得模糊模型不知道该调哪个参数Schema定义得太松模型传参时胡编乱造技能执行失败后没有降级逻辑整个任务直接卡死。所以我觉得技能系统才是Agent工程化的核心攻坚点模型是下限的保证技能才是决定上限的变量。1.2 技能与工具、插件、工作流的边界很多刚入门的朋友会把技能、工具、插件、工作流这几个概念混在一起。其实从我的实践理解来看它们是有清晰层级关系的工具Tool最基础的可调用函数单元比如“执行SQL查询”“调用HTTP接口”它不关心业务含义。技能Skill面向任务的可复用能力封装通常会组合一个或多个工具并附带调用逻辑、参数约束、异常处理规则。插件Plugin技能的一种分发形态把一组相关技能打包成可安装的模块解决的是“怎么发布给其他Agent用”的问题。工作流Workflow编排多个技能按顺序或条件执行解决的是“多个技能怎么配合”的问题。这四层里技能是最关键的设计节点。它的粒度比工具大比工作流小刚好是模型在做任务规划时最自然的推理单位。我在项目中一般遵循一个原则一个技能解决一个完整的业务动作。比如“创建客户订单”是一个技能但“计算订单折扣”和“更新客户等级”应该拆成独立技能——前者是主流程动作后两者是子任务或副作用。提示技能粒度过粗模型会“一把梭”整个调用链崩了很难排查粒度过细模型在规划时会生成超长的调用序列既耗费Token又增加失败概率。每个技能控制在“10分钟能完成的一个具体业务动作”这个粒度是我目前经验里比较理想的参考标准。2. 技能定义写清楚“能力说明书”2.1 技能元信息的四个关键字段技能定义是整个系统的地基模型能不能正确调用技能80%要看定义写得怎么样。我经过多轮迭代后总结出一套相对稳定的技能元信息结构核心字段就四个字段名作用我的建议name技能的机器标识用于程序内部寻址用snake_case命名如create_sales_order避免大小写混杂display_name面向调用者的可读名称简短不超过10个中文字符description技能能力描述模型理解技能用途的窗口200字以内写清“能做什么、在什么场景用、不做什么”parameters参数Schema约束模型如何传参定义每个参数的名称、类型、必填性、描述、取值范围这四个字段里name和display_name好写容易踩坑的是description和parameters。后面我单独展开讲。2.2 技能描述写作的三个层次技能描述写给谁看是写给模型的embedding和推理逻辑看的。我用过几百条技能描述最后总结出了“三个层次”的写法这条经验帮我把技能选中的准确率从72%提升到了91%第一层动作与对象。直接说清技能执行什么动作作用于什么对象。比如“查询指定日期区间的销售订单列表”这句话是最基础的定位。第二层场景与上下文。补充这个技能适合在什么业务场景下使用。比如“当用户想查看某段时间内的业绩情况、订单明细或需要基于订单数据做分析时使用”。这层信息对模型判断“当前用户请求是否该走这个技能”非常关键。第三层边界与排除。明确这个技能不适合做什么减少模型误调用。比如“本技能仅支持查询已完成订单不支持创建订单或修改订单状态”。我最初写技能描述时从不写这层结果模型经常在用户想“改订单”时调了“查订单”的技能加了边界描述后这类问题基本绝迹。2.3 参数Schema设计的坑与经验参数Schema是约束模型传参的“紧箍咒”。模型是概率生成不写清约束它就放飞自我。我踩过的坑主要有三类坑一参数类型写得太泛。比如把整型参数写成string模型就会传“已发货”这种状态文本。解决方案是严格定义JSON Schema的类型并附上示例值。坑二参数描述缺少业务约束。比如status参数只说“订单状态”模型不知道该传什么值。正确的写法是“订单状态可选值pending待处理、paid已支付、shipped已发货、cancelled已取消”。枚举型参数一定要列出所有可选值这是最有效的防呆设计。坑三必填参数与非必填混淆。模型对必填参数的遵守度没有开发者想象的高如果某个参数在业务逻辑里是必填的必须在Schema层面标死required否则模型默认“能省则省”。我还建议给每个参数设计合理的默认值并显式说明“若不传该参数系统将使用默认值X”给模型留一条兜底路径。参数Schema我一直在用标准的JSON Schema格式下面是一个示例{ type: object, properties: { start_date: { type: string, format: date, description: 查询起始日期格式YYYY-MM-DD, example: 2025-01-01 }, end_date: { type: string, format: date, description: 查询结束日期格式YYYY-MM-DD不能早于start_date, example: 2025-06-30 }, status: { type: string, enum: [pending, paid, shipped, cancelled], description: 订单状态过滤条件不传则查询全部 } }, required: [start_date, end_date] }注意给模型看的是“参数的业务语义和约束”而不是后端接口的“技术实现细节”。我见过有人把Java的RequestBody注解原样搬进技能参数描述模型根本看不懂。参数描述必须站在模型的语言习惯上写多用业务术语、少用技术黑话。3. 技能注册与调度让智能体“找得到”也“用得好”3.1 技能清单的组织方式技能数量少的时候无所谓十来个技能全部加载进上下文也行。但一旦技能数量超过30个或者说单次任务需要候选的技能超过一定数量全量加载会让上下文爆炸选错率也会飙升。这时候就需要做技能的“目录管理”。我把解决思路上类比成图书馆藏书书多了不能所有书都摊在桌上得有分类书架和索引卡。技能清单的组织方式我用的是三级结构技能域Skill Domain按业务模块划分比如“订单域”“客户域”“库存域”。每个域是一组相关技能的集合。技能标签Skill Tags跨域的横向标签比如“查询类”“写操作类”“高耗时类”“内部系统类”。标签用于快速过滤。技能索引Skill Index每个技能对应一张索引卡记录技能ID、能力摘要、参数结构、依赖域等。索引卡就是上面说的元信息只是落地成可检索的JSON或DB记录。模型在实际决策时会先根据用户请求和业务上下文定位到技能域再在该域内做细粒度的技能匹配。这就像先知道自己要去的书架区域再按索引卡找具体哪本书比全馆翻找高效得多。3.2 调度策略单技能触发与组合编排技能调度是整个系统的“指挥官”它决定在什么时机、用什么逻辑触发哪些技能。我实践的调度策略主要有三种各有用处策略一模型自主触发。把技能清单注入Prompt让模型根据用户意图自行挑选技能并生成调用参数。这是最常见的方式适合技能不多、边界清晰的场景。配合好的技能描述效果很不错缺点是模型偶尔会抽风选错技能或伪造参数。策略二规则前置过滤模型决策。先在代码里用关键词匹配或分类器做一轮过滤把候选技能从50个缩小到5个以内再让模型在这几个候选里做最终选择。这种方式适合技能数量大、且某些技能的触发场景有明确信号词的场景。比如用户消息里出现“订单号”时先锁定订单域技能组。策略三确定性管道编排。对于固定的业务流程比如“客服接待→查询订单→登记退换货”干脆用代码写死流程顺序每个环节直接调用确定的技能。这种方式完全不依赖模型做规划稳定性最高适合对准确率要求苛刻的核心链路。我一般建议“核心链路走策略三非核心扩展走策略二探索性场景走策略一”。三者混用才能既稳又活。3.3 技能冲突的处理经验做Agent开发迟早会碰到一个问题多个技能都能响应同一个请求到底该选哪个我归纳了三类常见冲突和对应处理方案语义重叠冲突比如“查订单”和“查订单详情”在功能上有交集。处理方案是给两个技能都补充边界描述并在描述中明确“若要获取订单列表使用前者若要获取某个订单的明细字段使用后者”。优先级冲突两个技能都有倾向被选中但业务上有一个是更优解。我的做法是给技能元信息里加一个priority字段调度时优先选高优先级技能。注意这个字段是给后台调度代码用的不用暴露给模型。依赖顺序冲突技能A需要技能B的产出作为输入但模型可能先调A再调B。处理方案是在A的Description里显式写明“该技能依赖技能B执行结果请先调用技能B再调用本技能”同时在调度层增加依赖检查发现乱序时自动调整执行顺序。4. 技能执行引擎从发起调用到结果回传的完整链路4.1 执行上下文与状态管理技能不是孤立运行的它必须能感知当前任务的状态、访问必要的数据、把结果回传给上层的Agent任务管理器。这一整套机制我称之为“执行上下文”。一个完整的技能执行上下文至少包含四部分会话信息当前对话的任务ID、用户身份、租户信息、业务对象ID。任务状态当前Agent任务执行到哪一步、需要技能输出什么数据给下一步。技能参数模型生成并校验过的调用参数。外部资源句柄数据库连接、缓存引用、HTTP客户端、第三方SDK实例。状态管理上我强烈建议使用“无状态技能有状态编排层”的组合技能本身不保存任何状态所有需要的数据通过参数传入状态集中在编排层比如任务会话缓存或状态机模块维护。这样做的最大好处是技能可以随意复制、并行执行、失败重试不会因为状态混乱导致连锁错误。提示如果你发现技能执行中常常出现“上次调用留下的脏数据影响本次调用”或者“两个技能并发执行时互相覆盖数据”基本可以断定是没做无状态化改造。把所有状态挪到编排层、技能只通过参数和返回值交互这类问题能消掉大半。4.2 失败重试与降级策略技能执行不可能永远成功网络抖动、数据库锁、接口限流都可能让调用失败。我最初的项目里技能失败后Agent就是简单返回一句“操作失败”用户体验很差。后来我设计了一套“三级已备降级链”第一级参数修正后重试。当技能执行失败且错误原因指向参数不合理比如日期格式不对、ID不存在让模型重新理解错误信息、修正参数后重试一次。这一级的成功率很高因为很多失败是模型传参时的小误差造成的。第二级降级到替代技能。当技能本身报错比如上游接口挂掉尝试调用替代能力。比如“查库存量”失败时尝试降级到“查最近一次库存同步记录”至少给用户提供一个可用的近似结果。第三级规则化默认兜底。当前两级都失败且业务允许时返回配置好的默认答案。比如“价格查询失败时返回最近一次快照价格并标注数据时间”而不是直白地告诉用户“查不到”。每次降级都必须记录日志我在日志里会保存原始错误、重试参数、降级路径、最终结果。这两点对整个系统的可观测性和后续优化非常关键。4.3 安全边界与权限校验技能一旦能调用真实系统安全就变得非常重要了。我不止一次看到团队把技能权限做成“能调就能全调”结果任何话题都可能触发危险操作。我实践的安全措施有三条硬性要求第一每个技能必须声明所需权限级别。我在技能元信息里增加required_permissions字段取值如read_only、write_limited、write_full。调度层在触发技能前先校验当前用户会话的授权范围无权则直接拦截。第二技能执行过程全程审计。谁在什么任务里、用什么参数、调了哪个技能、结果是什么全部写入审计日志。出问题一查一个准。第三高危技能“双校验”。凡涉及资金变动、数据删除、权限修改等敏感操作必须在模型生成调用参数后加一道代码层确认——比如爬虫校验、二次确认、业务规则拦截器。我项目里有个实际案例一次模型把“删除客户档案”和“停用客户账号”弄混了如果没有规则拦截器就会造成严重误操作。后来我给这类技能增加了触发条件校验只有符合特定状态流转规则才允许执行。5. 技能扩展与复用把一次技能沉淀成组织资产5.1 技能版本管理与迁移技能不是写完就固定的业务规则变、接口升级、参数调整都要求技能版本能平滑演进。我给技能引入的版本管理模型是参考API版本管理的经验调整的核心有三个要点语义化版本号技能版本用major.minor.patch三段式major变更表示技能行为不兼容比如参数要求变了minor变更表示向后兼容的新增能力patch表示修复缺陷。旧版本灰度保留新版本技能发布后旧版本至少保留两个发布周期线上Agent可以配置指向某个固定版本避免所有调用方同一天被强制升级。变更清单留痕每次版本变更强制填写变更清单写明“为什么变、变了什么、谁受影响”。这个习惯在排查“上周还能用、这周为什么挂了”时特别救命。版本迁移的实操路径我一般这样走先在小流量买卖灰度观察技能执行成功率、参数合法性、结果质量三个核心指标确认无误后再全量放开。千万不要在周五下午直接全量替换核心技能我上过这个当。5.2 跨场景复用技能包一个团队沉淀的技能其他团队能不能直接用场景差异怎么办我的经验是打包成“技能包”并附带适配层。一个可复用的技能包含三部分技能定义文件即前面说的元信息参数Schema执行逻辑代码独立可部署的微服务或函数适配层配置不同业务域的认证方式、接口地址、字段映射规则比如“订单查询”这个技能订单中心团队实现了它电商团队和分销团队要复用他们不需要改技能内部的查询逻辑只需要在适配层配置自己的API地址和鉴权方式。这套做法极大减少了重复开发量。我在团队里实际推进后新业务接入一个成熟技能的时间从原来的3天压缩到半天。5.3 建立技能评估反馈闭环没有评估就没有改进。技能上线后我会持续追踪下面几个指标它们是技能健康度的晴雨表指标看什么我设的预警线技能命中率该技能是否在用户请求对应的比例下被正确选中低于80%就要优化描述或调度参数合法率模型生成的参数通过Schema校验的比例低于90%就要检查参数描述的清晰度执行成功率技能调用后成功完成业务动作的比例低于95%要排查执行逻辑和依赖系统任务贡献度技能在完整Agent任务中被调用的频次与位置占比持续为0的技能考虑下线我的评估做法是每次Agent任务结束后让任务结果回传给技能管理平台平台自动聚合这些可观测数据每周生成一份技能健康报告。反馈闭环的关键动作是“谁影响谁负责”——技能描述和逻辑的负责人必须每周看报告并给出改进动作否则评估做了也没人管最后又会变成空转的形式主义。6. 常见问题与排查技巧实录6.1 技能一直没被调用的排查思路这是Agent开发最常遇到的问题“模型明明有技能可用就是不调用”。我分享一个完整的定位路径第一步看任务日志里模型的实际输出。确定模型是真的没看到技能还是看到了但选择不调用。这一步能排除80%的表层问题。第二步检查技能清单是否注入完整。有些框架对技能数量有截断技能多了后面的就丢了。我之前就遇到过技能描述总字数超过上下文窗口后靠后的技能被截掉模型“看不到”自然就“想不起”。第三步审视技能描述与用户意图的匹配度。把用户请求和技能描述同时打印出来用“第三人称”对比看看是不是“你觉得有关联但模型不觉得有关系”。描述太抽象或者只写了内部术语模型匹配不上就会去瞎编或者让用户换个问题。第四步确认调度层的路由是否正确。如果用了规则前置过滤检查命中条件是不是过于严格导致模型侧压根没收到候选技能。这套排查路径我跑过不下二十次90%的技能“不触发”问题都能定位到上面四步中的某一步。6.2 技能参数解析失败的处理参数解析失败的表现通常是模型生成了不符合Schema的参数、必填参数缺失、枚举值超出范围。我强烈建议处理这类问题采用“重解析一次让模型自我修正”的组合拳错误提示带有明确的结构哪个字段错了、期望什么格式、实际收到什么值这样模型能精确知道自己错在哪、怎么改。我实测下来提供带“字段级反馈”的错误提示后二次解析成功率达到85%以上。很多开发者在错误提示里只写“参数格式错误”模型愣在原地不知道怎么修正反复三轮也改不对。6.3 技能执行超时的定位方法技能超时是排查成本最高的故障类型之一。一次技能调用超时真正花费最大的不是那几秒而是整个Agent任务卡住后面的流程全部阻塞。我的排查套路分三层先确认超时是发生在“技能被调度之前”还是“技能执行之中”。前者通常是模型推理慢或上下文塞了太多技能后者要下沉到技能执行的接口调用链。给技能执行链路加细粒度的耗时埋点。每个阶段都加参数校验耗时、鉴权耗时、上游接口IO耗时、数据加工耗时、返回序列化耗时。这样看哪个阶段消耗占比高就重点优化哪个环节。用降级把“硬超时”变成“软超时”。不要让技能执行超过5秒直接报错。可以在3秒时检查是否有可用的降级方案比如先返回缓存快照或者在超时后异步补偿执行、先给用户一个“处理中”的中间状态。注意技能超时处理的最高原则是“绝不让用户干等”。宁可先让Agent回复“这个操作需要一点时间我处理完会主动通知您”也比卡住不动体验好得多。这也是为什么我会在设计执行引擎时把同步调用和异步补偿机制一起迭代。最后想说的几句实在话走了这么长的路我个人在agent-skills上的体会是技能系统没有一步到位的设计都是靠一次一次线上事故和用户反馈磨出来的。你可以从最小的技能集开始跑通核心流程再逐步加能力不要一上来就想着把所有业务都封装成技能那样只会让模型陷入“选择困难症”。如果准备开始做Agent技能系统的设计我的建议是从“写10个技能跑100个真实用户请求”起步通过真实的表现去迭代你对技能描述、参数约束、调度策略的理解。纸上的设计永远是别人的经验亲手踩过的坑才是你自己的能力边界。希望这篇文对你的项目有一些实际帮助。你在落地agent-skills时遇到的具体问题也欢迎带着场景来交流我用踩过的坑换你的新教训大家彼此都长经验。