智能体技能工程实战：从工具调用到可复用技能库的完整设计指南-北京尧图网络

直接说结论如果你正在做智能体Agent应用无论是跑在RAG框架里、套在自动化工作流里还是嵌在对话产品里agent-skills这个名字背后涉及的就是给大模型配一套“可复用、可组合、可评测”的行为技能库。模型负责理解意图、拆解任务技能负责真正把事情做对。这篇文章不聊空泛的概念我会把技能体系从设计、定义、实现、编排到排查问题的完整路径拆开讲全程用自己实操过的案例作参考。适合两类人看一是正在做Agent产品开发、但觉得每次让模型调工具都像在碰运气的工程师二是刚接触智能体技能设计、想知道从哪下手的初学者。1. 智能体技能到底是什么1.1 一个让我彻底想明白的场景先说一次真实经历。我之前做过一个内部运维助手功能很简单查服务器状态、重启服务、看日志、发告警。最初版本把所有能力都写成一个工具列表塞给模型结果非常不稳定模型经常把“查日志”和“重启服务”搞混甚至用查状态的参数去调重启接口把一台测试机折腾得够呛。后来我把这些能力重构成“技能”问题立刻缓解了。原因很简单技能不是单个函数而是一整套“模型调用规则”它告诉模型这个能力是干什么的、适合什么时候用、参数是什么、依赖什么前置条件以及执行后的预期结果。这个经历让我明白了一件事Agent的智能程度很大程度上取决于模型身边那一排“技能”被设计得好不好。模型本身的推理能力再强如果技能入口混乱、描述含糊、参数约束缺失最终表现也是失控的。1.2 技能Skill与工具Tool的区别很多资料把两者混为一谈实际差别很大。Tool通常指“单个可执行函数”比如一个API接口输入参数、返回结果简单直接。Skill是比Tool高一层级的抽象它至少包含四个要素技能名称和命名空间意图描述说明这个技能解决什么问题、在什么场景下触发输入参数Schema每个参数的类型、必填项、取值范围、默认值执行器可以是函数、API调用、脚本也可以是另一个Agent的调用后置处理逻辑可选对结果的清洗、结构化、错误兜底等用一个生活类比最直观Tool好比你家工具箱里的一把螺丝刀Skill则是“拧下显示器支架螺丝”这件事。同样是螺丝刀但“怎么握、拧哪颗螺丝、要小心什么、拧不动时怎么办”这些信息才是真正的技能。Agent开发最大的坑就是只给了模型螺丝刀没教它怎么干活。我自己的定义是Tool解决“能不能做”Skill解决“做得好不好、会不会选错、失败了怎么办”。任何复杂的Agent产品迟早都要从Tool层面走向Skill层面。1.3 为什么现在特别需要技能工程模型能力这两年进步飞快但智能体落地依然很难核心瓶颈就是“最后一公里”的执行确定性。模型擅长模糊推理但不擅长精确执行。你问它“北京的天气怎么样”它能给个大概你让它“把北京分公司所有在线节点的CPU使用率和内存占用拉一份报告”它就容易在参数、请求方式、结果整理上犯错。技能工程出现的核心原因就是把“执行层面的确定性”从Prompt里剥离出来变成一个结构化、可被程序检查、可被拆分测试的对象。结构化技能有三个直接收益。第一可控性强。每个技能的触发条件、参数校验、失败处理都是可枚举的出了问题能定位。第二编排灵活。多个技能可以拼接成复杂工作流。第三评测简单。技能能被单独拿出来测试不需要每次跑完整的模型对话。另外从工程效率角度看技能是可复用的资产。项目A里写的“查询订单状态”技能项目B可以直接拿来用只要把执行器换成B的API就行。这种复用性让团队不需要每次从零开始调Prompt。2. 技能的整体设计与拆解思路2.1 技能边界的划分原则设计技能时最常遇到的灵魂拷问是一个技能应该多大拆得太细模型要在几十个技能里做选择容易浑水摸鱼拆得太粗一个技能内部包罗万象又回到了混沌工具调用的老路。我常用的判断标准是三个“是否”是否属于同一领域操作、是否共享同一套前置条件、是否能在一次模型决策内完成。如果三者的答案都是“是”就合并否则就拆开。拿电商客服机器人举例。“查询订单状态”和“修改收货地址”都属于订单领域但修改地址需要先做身份校验与查询的前置条件不同所以应该拆成两个技能。而“查询订单状态”和“查询物流轨迹”虽然列表页不一样但前置条件都是订单号也可以合并成一个“订单信息查询”技能通过enum参数区分查询类型。技能边界定了下一步要定义技能的“元信息”。每个技能最好带一个版本号因为技能的业务逻辑很可能随着产品迭代变化而模型的调用方式如果跟着变评测基线就会乱套。版本号能帮助追踪“这个技能在什么版本下表现如何”。2.2 技能命名的讲究命名看着是小问题实际影响巨大。大模型对技能名的语义理解非常敏感命名模糊的后果就是模型在“不知道用什么”的时候瞎猜。我们当时的教训是“用动宾结构”。不叫“数据”要叫“查询用户基础信息”不叫“订单处理”要叫“更新订单状态”。动词要具体名词要能对应到业务实体。用户在对话里说“帮我查一下订单”模型搜索技能时匹配的就是“订单”“查”这些关键词动宾结构能让相关性更高。同时技能名不建议包含修饰性词。不要叫“高效查询用户信息”这种词模型无法理解还污染语义空间。命名应该像函数名一样严谨甚至更严因为函数名是给人看的技能名是给模型看的模型又是在搜索语义空间里找最接近的匹配项噪音越少越好。2.3 技能定义的完整结构一个合理的技能定义文件应该包含七个核心字段。前五个容易理解name、description、parameters、executor、returns。后两个容易被忽略但至关重要when_to_use触发条件和examples典型调用示例。先说when_to_use。它是一段给模型看的话说明“当你收到何种意图时优先选择本技能”。很多技能描述洋洋洒洒写了一大堆功能模型反而看不出触发时机。我后来把触发条件独立成字段之后调用准确率明显上升。再说examples。这是几条示例性的“用户输入-参数映射”对。模型在零样本条件下对参数提取往往不稳定给了示例之后相当于做了一次“少样本提示”准确性会大幅提升。比如“查询订单状态”技能示例里写“用户说‘帮我看看单号DD123456到哪了’→ 参数order_idDD123456query_typelogistics”。模型看到这个结构后后续类似的说法都能自动对齐。另有一处细节必须在定义文件里写清楚技能是否需要前置技能。例如“申请报销单”技能可能需要“查询审批人信息”技能先执行。把这些依赖关系写在技能定义里编排器才能建立正确的执行顺序。3. 技能开发与接入实操3.1 一周做出一套技能库画个实线路径我给新接触的人用的五步流程记录业务动作 → 抽象共性 → 定义Schema → 实现执行器 → 联调回归。第一步把产品里所有模型需要执行的动作全部列出来。这一步不要做任何抽象有多细列多细。第二步把动作按“意图”归类。归类的时候会发现很多动作共用了同一数据源、同一前置条件此时再决定合并还是拆分。第三步为每个技能写出JSON Schema参数定义。第四步用代码把每个技能的执行器实现出来。第五步用一个包含典型用户对话的测试集反复联调记录模型选中技能的准确率、参数提取的完整率、执行结果的正确率。这套流程第一次做不用追求完美重点是建立起“技能是可迭代资产”的认知。我见过很多团队直接把一个框架项目里的function列表改名为skills文件然后跟风发博客这是自欺欺人。3.2 一个可以直接抄的示例文件下面这个示例是我之前一个数据报表智能体里的真实技能定义我做了简化处理。它展示的技能叫“获取业务指标报表”参数包括报表类型、时间范围、维度。{ name: get_business_report, namespace: analytics.report, version: 1.2.0, description: 获取一个或多个业务指标的统计数据报表支持按小时、天、周聚合, when_to_use: 当用户请求查看PV、UV、转化率、GMV、订单量等业务指标或要求对比不同时间段的业务表现时使用, parameters: { type: object, properties: { metrics: { type: array, items: {type: string, enum: [pv, uv, conversion_rate, gmv, order_count]}, minItems: 1, description: 需要查询的指标代码列表 }, start_date: { type: string, format: date, description: 统计开始日期格式YYYY-MM-DD }, end_date: { type: string, format: date, description: 统计结束日期格式YYYY-MM-DD }, granularity: { type: string, enum: [hour, day, week], default: day, description: 数据聚合粒度 }, dimensions: { type: array, items: {type: string, enum: [channel, device, region]}, default: [], description: 分组维度 } }, required: [metrics, start_date, end_date] }, examples: [ { user_query: 看看上周每天的GMV和订单量, arguments: {metrics: [gmv, order_count], start_date: 2025-02-10, end_date: 2025-02-16, granularity: day} }, { user_query: 对比一下这个月1号和15号的转化率, arguments: {metrics: [conversion_rate], start_date: 2025-02-01, end_date: 2025-02-15, granularity: day} } ], executor: { type: http, method: POST, url: https://api.internal.example.com/v1/reports, headers: {Authorization: Bearer ${TOKEN}} }, returns: { type: json, schema: { type: object, properties: { report_id: {type: string}, rows: {type: array}, total: {type: number} } } } }注意几个细节metrics用了数组类型并在items里限定了enum这能有效防止模型乱填指标名dimensions默认给了空数组模型不填也能正常查询但填了就能做更细致的分组examples两条示例分别覆盖了“多指标查趋势”和“对比两个日期”两种常见诉求传递出的信息是“不要只查单个数字要能帮我做对比”。执行器我用的是HTTP调用实际场景还可能是Python函数、SQL查询或另一个Agent。HTTP方式的优点是技能与执行逻辑彻底解耦后续改执行器不用动技能定义。3.3 参数Schema设计的三个原则参数Schema是整个技能定义里最容易被低估的部分。很多开发者随手写一个宽松的Schema觉得模型反正会理解。实操下来Schema越宽松模型越倾向于“自由发挥”后续解析错误越多。三个原则第一必填项必须显式声明。可填可不填的参数多了模型无从判断。声明required是把决策压力交给模型本质上是在逼它把用户的信息问清楚。第二能枚举就枚举。能用enum定义取值范围就不要开放自由文本。自由文本带来的问题是值域不可控下游处理困难。enum相当于给参数划定合法边界模型选择起来更轻松下游处理也能省掉一大部分脏数据清洗。第三类型要尽量窄。能用integer就不要用number能用string但配合format如date就不要裸用string。窄类型能提前拦截一类错误避免执行阶段才发现参数类型不匹配。我在实践中还发现一个规律参数的description不宜写太长最好控制在20个字以内而且应该描述业务含义不是描述代码含义。比如startDate参数应该写“统计开始日期”而不是“请求起始时间戳”。模型不是编译器它理解的是语义不是变量名。4. 技能编排与组合使用4.1 从单技能到技能链实际业务中一次对话很少只触发一个技能。用户说“把昨天的数据汇总发到邮箱”实际要执行三个技能查询数据 → 生成报表 → 发送邮件。如果让模型一次调用三个技能看起来没问题但一旦第二步生成报表失败第三步发送邮件就变成一个“没有依赖对象”的无效调用。更合理的做法是定义成一条技能链带依赖顺序。技能编排的核心是“前置条件检查”。执行第二个技能之前必须确认第一个技能的产出物已经存在且格式正确。我建议在编排器里做一个状态机每个技能执行之后维护一个artifacts清单记录产出物类型、存储位置、有效时间下一个技能执行前检查清单。这个设计能让失败定位从“说不上来哪步错了”变成“第2步生成报表无产出物”排障效率完全不同。4.2 编排器的配置与实现思路我以一次数据查询与报告推送的编排配置为例展示编排层如何组织技能调用workflow: id: daily_report_pipeline trigger: intent: 日报推送 steps: - step_id: query_data skill: get_business_report next: generate_digest - step_id: generate_digest skill: summarize_report depends_on: query_data requirement: query_data.result.rows is not empty next: send_email - step_id: send_email skill: send_mail depends_on: generate_digest requirement: generate_digest.result.file_path exists这个编排里最核心的是每个步骤的requirement字段。它定义了执行条件编排器在执行前用轻量逻辑判断一次不满足就跳过。这样技能链就有了“短路保护”查询数据为空时后续生成摘要和发送邮件直接不执行并返回提示给用户。刚开始做编排时总忍不住加条件判断后来发现一个准则编排器只负责顺序和依赖不负责业务。业务判断比如数据量是否足够多应该下沉到技能内部而不是放在编排层。编排层做的是控制流程不是理解业务否则后面编排逻辑会越来越庞大最终无法维护。4.3 并行执行与合并结果有些场景下技能之间没有依赖关系可以并行。比如用户要求同时查“订单量”和“库存水位”两个技能互不依赖。对这类无依赖技能我用异步调度的方式并行执行再做一个结果合并器把双方结果组装在同一份回复里。并行执行的收益在交互式Agent中尤其明显。串行等待两次API往返大约需要好几秒并行能直接减半。不过并行带来的复杂度也需要权衡并发数上去以后要给每个技能调用加超时控制否则一个技能挂住了合并器一直等它反而比串行更慢。我现在的做法是为每个技能单独配一个timeout_ms合并器取所有技能的超时最大值整体执行时间不会超过这个上限宁可超时降级为“部分结果返回”也不让它无限期等待。另外合并结果时要注意格式化冲突。两个技能返回的JSON结构可能不一致合并器应该先做归一化把字段名统一再决定展示顺序。有个经验展示顺序尽量跟用户请求里提到的顺序一致。用户说“先看订单再看库存”合并结果就把订单放在前面这种细节对体验影响很大。5. 常见问题与排查技巧实录5.1 模型死活不调用技能怎么办这个问题太常见了。技能文件写得完整、清晰但模型在对话里就是不用自己瞎编一通。排查思路按顺序来先看技能描述与用户输入的相关性再看示例是否覆盖了目标表达方式。我遇到过的一种典型情况是技能描述写得太“程序化”比如“根据用户提供的参数组合调用业务报表API”这种描述模型难以判断何时触发。后来改成“当用户想查看任何业务指标数据、做趋势对比或维度分析时”触发率立刻上升。另一个技巧是检查示例里是否有与目标表达接近的句子。模型对没见过或距离远的表达方式天然容易漏选。还有一种原因是技能间彼此打架。几十个技能同时放进提示词列表模型的注意力有限排在后面的技能容易被漏掉。这种情况该考虑分层索引先做一层粗粒度技能组路由比如“财务类技能组、运营类技能组”再做组内精排。而不是把所有技能都堆在一个大列表里指望模型每次都能全看一遍。5.2 技能执行失败后怎么自动恢复技能执行失败是日常。最怕的不是失败而是失败之后整条链路僵死。在设计技能时一定要预埋错误处理逻辑至少覆盖三种情况重试、降级、反馈。重试网络抖动、瞬时错误加上指数退避重试两三秒内自动恢复。降级主执行器挂了切换到备用的只读数据源。比如查询报表的主API超时可以降级到离线数仓的预聚合结果。反馈重试降级都失败要把错误结构体返回给模型让模型生成可读的提示语并主动向用户提问是否需要替代方案。错误反馈的信息一定要结构化。不要只返回“Request failed”应该返回“skillget_business_report, error_codeTIMEOUT, msg上游channel网关5s未响应”。让模型机会根据错误信息给用户更准确解释例如明确告诉用户现在查不到某个渠道的数据。我曾经因为偷懒只返回了一个错误码模型对着用户说“系统异常”用户完全摸不着头脑。5.3 技能描述污染上下文怎么办接入技能太多每秒调用都把全部技能定义塞进Prompt上下文被大量技能描述占满留给对话历史和业务上下文的窗口就少了。我的实测经验是一份技能的JSON Schema平均400到600 token如果注册了50个技能光技能描述就吃掉两万多token多轮对话的上下文会被严重挤压。解决的思路是做“动态技能加载”。不把所有技能一次性注入而是根据对话历史先做一次意图初筛只加载相关度最高的5到8个技能。这个过程类似信息检索里面的召回-精排两步走。实现方式不复杂可以先用关键词匹配或者一个轻量分类模型做初筛候选技能只保留TopN再连同完整描述注入模型。这样上下文占用可以压缩到原来的十分之一左右而且触发准确率不会明显下降因为每次模型只需要做选择题而不是大海捞针。5.4 多技能冲突和权限问题多个技能都能处理同一类请求时模型可能选错。比如“查询报表”和“导出报表”用户一个模糊表述“把数据导出来”模型可能会选择导出技能但导出前又没做格式选择导致结果千奇百怪。这种冲突需要在技能描述里明确区分场景。我的做法是在when_to_use里加“前置条件描述”比如导出技能里写“仅当用户明确指定导出格式或要求发送文件时使用若用户仅要求查看数据请用查询技能”。权限问题也有讲究。有些技能对用户身份有要求比如“修改订单状态”需要管理员权限。建议不要在技能定义文件里标注权限信息因为定义文件会被模型读取告诉模型“这个技能需要管理员”相当于向旁路泄露了权限边界模型可能会替用户想办法绕过限制。权限应该在执行器层强制校验模型只负责提交调用请求执行器根据token或用户上下文拒绝无权限的调用。这个边界一定要硬不能靠模型自觉。6. 技能评测与迭代策略6.1 评测一个技能从四个维度看技能开发出来必须验证效果好不能靠感觉。我常用的评测体系是准确率、完整率、时效率、回归率四条维度。准确率模型在测试对话里选对技能的比例。分母是测试集所有需要调用技能的情况。完整率选对技能后参数提取是否完整必填参数是否都拿到。时效率从模型输出调用请求到执行器返回结果的总时长是否在可接受范围。回归率本次迭代有没有破坏之前已经通过的功能。这四项需要分别打分。准确率主要考察技能描述与when_to_use是否清晰完整率主要考察参数Schema与示例是否充分时效率主要考察执行器性能和编排器调度做得如何回归率则对应整体工程质量的稳定性。缺了任何一项技能都可能在某一个维度上暴雷。6.2 构建一套回归测试集技能迭代最大的隐患是改A技能B技能悄悄变差。所以我强烈建议每个技能配一个专属回归测试集。测试集不用特别大每个技能准备20到30条真实用户对话加上对应的期望调用的技能名和参数组合就初步够用了。把测试集跑起来时要关注三类错误。第一是误触发用户没有这个意图模型却调用了技能。第二是漏触发用户明确表达了意图模型迟迟不调用。第三是参数错误技能选对了但参数映射错乱。这三类错误对应的修复手段完全不同误触发是描述太泛需要缩小when_to_use的范围漏触发是语义距离没覆盖到需要补充示例和改写描述参数错误则是Schema约束不足或示例缺失需要用enum、format、required等字段加固。6.3 从日志里反推迭代方向评测集做得再完善也覆盖不了线上复杂情况。我每周固定做一次“技能日志复盘”把模型没有按预期选择技能的case捞出来用脚本聚类相似对话按问题类型分组然后针对性改进。这个过程能持续发现新的表达方式、新的意图边界慢慢形成一套“对边界情况越来越熟悉”的技能库。日志复盘最有价值的一条经验是能复现问题才能改问题。捞日志时我会把模型当时收到的Prompt原文和技能列表快照一起存档否则几周后再想复盘当时的上下文根本无从下手。技能版本号在这个场景里发挥了大作用快照里存了技能版本问题case定位就能直接对到定义文件的具体版本不用猜是哪个版本的技能出了问题。另一个从日志里能发现的重要信号是“技能空转”。有些技能被高频调用但返回结果几乎不被使用说明这个技能触发了但不解决用户问题。这时候要判断是技能本身没价值还是结果格式不对用户看不到。二选一要么删掉技能要么改输出呈现。最后说点实际操作的事技能体系是一个越滚越有价值的资产。最开始把第一个技能写出来时会感觉只是加了一个函数描述跟原来直接列工具列表没什么区别。坚持迭代几个月后技能库开始覆盖产品里绝大多数常见动作此时模型在场内发挥的稳定程度会明显高于没有技能支撑的裸模型。但我个人要强调一句技能设计不是一次性的它是一种持续投入的工程日常。每次用户抱怨“怎么又答错了”背后几乎都能归结到某个技能定义不够清晰或者某个技能缺失。跟随着日志、评测、现场反馈把技能库打磨到能覆盖目标场景的80%以上Agent才算真正“能干活”。这套方法是笨功夫但非常可靠我希望你把工具技能化这件事落实到自己的项目里别只让它停留在概念阶段。

智能体技能工程实战：从工具调用到可复用技能库的完整设计指南

相关推荐

Allegro整板铺铜：板框驱动铺铜边界与Z-Copy实战

【数据集】上市公司制造业内卷式竞争5种方法（2002-2024年）

PHM中文教案：面向产线落地的机械设备状态监控实战指南

更多资讯

微信小程序设备报修系统开发实战：从状态机设计到订阅消息推送

Python字符串与字节拼接：从报错到实战全解析

企业大模型网关实战：从Key管理到Agent接入的完整指南

微信小程序设备报修系统实战：工单设计、状态流转与上线避坑

四层板叠层设计与阻抗计算全流程：Allegro 17.4实操与避坑指南

小红书API怎么获取？官方开放平台申请流程与合规替代方案解析

今日更新

基于sEMG与IMU的手语手势识别：从数据采集到实时部署避坑指南

装配车间MES落地指南：SimpleMES工单流转、BOM与齐套检查实战

AI获客怎样减少重复线索？意客AI的原文复用与版本筛选

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？