Agent Skills实战指南：从技能拆解到稳定落地

看着“agent-skills”这个词在热搜上挂着我其实挺有感触的。过去一年里我经手过好几个Agent项目从最初的“什么都能干”到后来的“什么都干不好”中间踩了无数坑。身边不少朋友也跟我吐槽说大模型明明很聪明可一落到实际业务里就“手无缚鸡之力”连查个库存、算个折扣都费劲。问题出在哪很多人第一反应是模型不行但折腾一圈下来我发现真正卡脖子的地方其实是技能——我们压根没教会Agent怎么“动手”。如果你也在做Agent应用或者正准备把大模型接入业务系统那这篇东西应该能帮你省下不少冤枉时间。我不会跟你聊那些抽象的“智能体哲学”就讲实际操作里怎么理解技能、怎么拆技能、怎么把技能真正用起来以及那些文档里绝对不会写清楚的坑。1. Agent Skills到底解决什么问题1.1 从“什么都会”到“什么都不会”的尴尬先说个场景。你给一个通用大模型投喂了一堆产品文档它确实能跟你聊得头头是道连你们家客服话术都能背下来。但你让它“把昨天华东区的销售数据拉出来按环比排个序”它就傻了。它不知道数据在哪、怎么连库、用哪个接口、字段怎么映射。这不是模型笨而是它根本没有“动手”的通道。Agent Skills这个概念说白了就是给大模型装上一双“手”。每个Skill都是一项可以被模型主动调用的具体能力比如“查天气”“算运费”“生成报表”“调用某个内部API”。它不是一个插件系统那么简单它的核心价值在于把模型从“会聊天”变成“会办事”。你不需要在提示词里把所有操作步骤写清楚只需要把技能暴露给它它自己会判断什么时候该用哪个技能。我当初第一次看到“Skills”这个命名时还觉得不过是换了层皮的Function Calling。但真正深入做下来才发现它更像是一种行为封装——不只是“调用函数”而是让模型具备某种“职业能力”。1.2 技能与工具、工作流的边界很多刚接触的人会混淆几个概念Tool、Plugin、Skill、Workflow。我自己的理解是这样Tool工具最底层的能力单元比如“执行SQL”“发送HTTP请求”“读写文件”。它不关心业务只负责执行。Plugin插件围绕某个外部系统做的封装比如飞书插件、Jira插件。它通常包含多个工具。Skill技能面向任务的能力封装它内部可能要用到多个工具还要加上提示词、参数规则、前置校验。它回答的是“能做一件什么事”。Workflow工作流把多个技能按业务流程串起来有状态、有分支、有编排逻辑。打个比方Tool是你厨房里的锅碗瓢盆Plugin是整套集成灶Skill是一道菜的完整做法——你得知道用什么锅、开多大火、放多少盐而Workflow是一桌宴席的上菜顺序。之所以要先理清这个概念是因为我在项目里见过太多人把技能设计成“一个Skill里塞了十几个工具”结果模型根本不知道该先调哪个。边界越模糊Agent的决策就越容易乱。1.3 我理解的Agent Skills核心价值对我来说Agent Skills真正的意义有三点第一可复用。一个写好的技能可以在不同Agent之间共享。比如“客户情绪分析”这个技能客服机器人能用销售助手也能用连售后工单系统都能接。你不用每个Agent单独写一遍逻辑。第二可组合。复杂任务能被拆成若干小技能再由一个主Agent按需调度。比如“生成周报”这个技能内部可能组合了“数据查询”“图表生成”“文本总结”三个子技能。这种组合能力让Agent在处理长周期、多步骤任务时不再像无头苍蝇一样乱撞。第三可治理。每个技能可以独立定义权限、限流、审计。谁用了这个技能、调了多少次、执行成功没有全部有日志可查。这对企业级落地来说几乎是刚需。2. 技能体系的整体设计与分类2.1 按功能划分的四种典型技能我在实际项目里习惯把技能先分成四大类每类的设计思路完全不同。感知类技能负责从外部获取信息。典型例子是“天气查询”“新闻检索”“数据库查询”。这类技能的特点是“只读”不修改数据但极其依赖参数准确性和返回结果的格式化。设计重点在参数校验和返回数据的结构上因为模型后续的推断全依赖这些返回值。操作类技能负责修改系统状态。比如“创建工单”“发送邮件”“更新订单状态”。这类技能风险高尤其在生产环境一不留神就是事故。设计重点在确认机制和幂等性上——同一个技能被模型重复调用两次结果必须一致否则用户会收到两封同样的邮件。计算类技能负责处理逻辑与运算。例如“折扣计算”“运费估算”“报表聚合”。这类技能不需要访问外部系统但对入参格式极度敏感。我踩过最大的坑就是模型把数字参数当成字符串传进来导致后端直接报错。生成类技能负责文本、代码、图片等内容产出。比如“会议纪要生成”“代码审查报告”。这类技能一般是纯提示词驱动不需要调用太多工具但需要严格约束输出格式否则后面再接其他技能时容易“消化不良”。2.2 通用型技能与业务专用技能的取舍这里有一个很容易纠结的问题技能到底做通用一点好还是做专用一点好我的经验是优先做业务专用通用化放在后头。道理很简单通用技能意味着你要处理更多边界情况而每个边界情况都需要额外的提示词和参数设计。比如“查询信息”是个通用技能但“查询客户订单信息”“查询物流轨迹信息”是两个专用技能后者的准确率和稳定性明显更高因为它的语义边界是清晰的。当然这也不是说通用技能一无是处。对于纯技术类的、不涉及业务语义的操作比如“HTTP请求”“运行Python代码”做成通用技能就非常合适因为它们的接口已经足够标准。所以我的判断标准就一句话涉及业务语义的尽量专用不涉及的可以通用。2.3 技能注册与调度的核心机制先看一个简化的技能注册JSON结构这是整个技能的“身份证”{ name: query_order_status, description: 根据订单号查询订单的当前状态包括待支付、已支付、配送中、已完成、已取消。, version: 1.2.0, owner_team: customer-service, parameters: { type: object, properties: { order_id: { type: string, description: 订单号例如 SO20250101A001 } }, required: [order_id] }, runtime: { timeout_ms: 5000, retry: 2, env: production }, permission: { roles: [agent, human_approval] } }这里面最关键的字段是description。很多人以为它是给人看的其实它是给模型看的。模型就是靠这段描述来判断“当前这个用户问题要不要调用这个技能”。所以描述不能写得像需求文档而要用“触发条件功能说明典型场景”的结构来写。至于调度机制我这边用的是注册表模式。Agent启动时从注册中心拉取所有可用的技能元信息在对话中模型根据用户意图从技能列表里做匹配一旦选中某个技能运行时就根据runtime配置去执行。整个流程最核心的瓶颈不在执行而在意图匹配的准确率——这个后面我会专门讲怎么调。3. 从零实现一个Skill的完整实操3.1 技能定义的元信息怎么写我自己写技能定义时有一条铁律name要短description要有触发条件parameters要写明枚举值。看一个反例{ name: tool, description: 这是查询工具, parameters: {} }这种技能定义模型根本没法用。你想象一下你让一个实习生去干活只跟他说“你用一下那个工具”他肯定一脸懵。正确做法是把话说清楚。{ name: query_weather, description: 当用户询问某个城市未来几天的天气情况时使用支持查询温度、降水概率、风力级别。输入城市名称输出未来3天的天气预报。, parameters: { type: object, properties: { city: { type: string, description: 城市中文名例如北京、上海、广州 }, days: { type: integer, description: 查询天数可选值为1、3、5默认是3 } }, required: [city] } }注意看我是怎么安排信息的description开头就是“当用户询问……时使用”这是给模型一个明确的触发条件比“该技能用于查询天气”这种说法命中率高得多。city字段我特意标注了“城市中文名”和示例这能显著降低模型传错参数的概率。days字段我给了枚举说明和默认值模型在不确定的时候会倾向于填默认值。3.2 技能的内部实现与上下文感知技能的外部定义搞清楚了内部实现同样有讲究。我建议不管底层用什么框架技能内部都要做成“输入校验—业务处理—结果格式化”三段式。输入校验我踩过一次很大的坑。当时某个技能接收一个date参数模型传了个“2025-03-15 14:22:31”这种带时分秒的格式而下游接口只认“2025-03-15”。结果就是接口报错Agent一脸无辜地跟用户说“系统开小差了”。后来我在技能入口加了一层严格的格式校验不符合预期就直接返回明确的错误信息并告诉模型正确的格式是什么。这样模型自己能纠正不需要用户重试。上下文感知是另外一个容易被忽略的点。比如查询订单状态时用户在对话里可能只说了“帮我查一下昨天那个订单”并没有给订单号。这时候技能不能直接执行要返回一个“缺少必填参数order_id”的信号由模型反问用户补齐。我见过很多团队直接把这类错误抛给用户体验非常生硬。正确的做法是让技能返回结构化错误码模型根据错误码决定是追问还是转人工。3.3 组合与编排让技能之间相互调用单个技能只能解决单一问题Agent真正厉害的地方在于组合。我给大家分享一个实际做过的例子客户投诉分析。这个场景不是一个技能能搞定的我拆成了四个fetch_ticket_detail拉取工单详情sentiment_analysis识别客户情绪返回正面/中性/负面category_tagging给投诉内容打标签比如“物流慢”“质量问题”“客服态度”generate_reply_draft根据情绪和标签生成回复草稿当Agent收到一条新的客户投诉时它会自己判断先调用fetch_ticket_detail拿到数据然后传给sentiment_analysis和category_tagging最后把结果拼起来交给generate_reply_draft。整个链路不需要你在代码里写死模型会根据用户问题的意图动态选择调用哪些技能、按什么顺序。但这里有个前提技能之间的数据格式必须兼容。比如sentiment_analysis输出的是一个{label: negative, score: 0.92}的对象而generate_reply_draft期望的入参里包含{emotion_label: angry}这样的字段。如果两边对不上模型在中间转换时很容易出错。我习惯在技能定义里增加一个output_schema字段明确声明返回结构这样上下游技能都能对齐。3.4 本地开发与调试建议调试技能是我花时间最多的地方这里分享几个提高效率的土办法。第一建一个技能沙箱。不要一上来就怼完整Agent你只需要一个最小化的shell把技能定义加载进去然后用几组固定输入去调。看返回结果是否符合预期。这一步能把纯逻辑问题快速暴露出来。第二强制查看模型的选择路径。在调试模式下把模型每一步的“思考过程”和“调用了哪个技能”都打印出来。很多时候模型不调用正确技能不是技能写错了而是它的注意力被别的内容带跑了。这时候我一般会做两件事精简其他技能的描述或者在本技能描述最前面加上“这是最常用的技能”。第三用“角色扮演”的方式测试边界。我自己会模拟一个比较刁钻的用户用各种同义表达去触发同一个意图看看技能匹配稳不稳。比如查天气用户可能会说“今天出门要不要带伞”也会说“周末去杭州穿什么”。这两种说法都不带“天气”两个字但都隐含了天气查询的意图。我发现这类模糊表达如果靠模型自由发挥成功率很随机后来就在技能描述里加了几个同义触发表达效果立竿见影。4. 常见问题与排查技巧实录4.1 模型“打死”不调用技能这是我被问得最多的问题。明明技能定义写好了功能也测过没问题但模型就是不调非要自己瞎编答案。排查顺序我建议是这样的先看技能描述是不是太泛。如果你写的是“查询信息”那模型根本不知道什么时候该用你。改成“当用户想了解订单配送进度时使用”。看技能description与其他技能有没有语义重叠。两个技能要是描述差不多模型会犹豫一犹豫就容易不调用。看是不是技能数量太多。实测下来单次上下文里暴露的技能超过15个之后模型的调用准确率就会明显下降。解决方案是把技能分组按场景动态加载而不是一次性全塞进去。另外还有一个很阴间的细节技能的name尽量别用下划线开头有些模型在解析时会认为这不是一个可调用的函数而是内部变量直接忽略。4.2 技能描述太长反而误触发你可能会想描述写详细一点不是更准确吗在我这实际测下来不一定。描述太长有两个副作用一是占用上下文窗口挤压别的信息空间二是容易让模型“浮想联翩”把无关问题也映射到你这个技能上。我之前有个邮件发送技能描述里写了“支持附件、抄送、密送”结果用户问“怎么设置邮件签名”模型竟然也调了发送邮件技能因为它看到了“邮件”两个字。后来我调整了写法把触发条件放在最前面功能细节往后放并且明确写上“不要用于XXX场景”的负向描述。命中率提升了不少。这里分享一个小模板我个人用着很顺手什么时候用当用户要求XXX时使用。做什么完成XXX并返回XXX。关键规则如果缺少XXX返回缺少参数错误不要自行猜测。不要做什么不要在这个场景下处理XXX。4.3 多个技能互相覆盖技能多了以后最头疼的问题就是“能力边界重叠”。比如你有create_ticket和create_refund_ticket前者是通用建单后者是退款单但模型有时候分不清该用哪个。我的解决办法是把容易混淆的技能合并用参数区分而不是用两个独立技能。比如建单和退款单合并成一个create_order_ticket然后加一个ticket_type参数枚举值写清楚“normal”和“refund”。这样模型在做意图匹配时不需要做“二选一”的精细区分只需要把参数填对就行难度就降下来了。如果两个技能确实无法合并那就在各自的description里加上“不要与其他技能混淆”的提示并把对方的名称写出来帮助模型做排除。4.4 技能运行超时与环境隔离技能执行超时这事我在生产环境里遇到过不止一次。尤其是那些涉及外部API调用的技能慢的时候能拖到几十秒。Agent等不起用户更等不起。我现在的做法是给每个技能设置明确的超时时间并且把超时反馈设计成“递进式”的。如果技能在2秒内没返回先向用户说“正在处理请稍等”。如果超过5秒模型会主动调用一个“查询处理状态”的技能去看后台任务是否在跑。如果超过15秒还没结果就直接告诉用户“当前系统繁忙请稍后再试”。这比干等一个结果要舒适得多。另外技能的执行环境最好跟主服务隔离用单独的容器或者沙箱跑。否则一个技能里出现内存泄漏直接把整个Agent服务搞挂那就太冤了。4.5 技能命名与权限管理最后说一个偏工程化的问题技能命名规范和权限。技能多了以后你会发现自己根本记不清每个技能是干嘛的。我建议命名用“动词开头业务对象操作类型”的格式比如get_order_list_by_customer、update_inventory_stock、export_sales_report。这样在日志里看到名字你基本就能猜到它干过什么。权限方面我吃过一次亏。某个Agent被放到了对外服务上居然能直接调用内部“删除用户数据”的技能差点酿成事故。后来所有技能的注册信息里强制加上permission字段分为public、internal、admin三级并且在运行时做拦截校验。凡是没权限的调用统一返回“无权限访问”的提示。5. 关于Agent Skills的进一步思考5.1 评测一个技能好不好的标准技能开发完了怎么评估它好不好不能光靠感觉。我自己有一套简单的评测维度分享出来给大家参考。第一是调用准确率。给定100个真实用户问题看模型是否在正确场景下调用正确技能。准确率低于90%的技能我基本不会让它上生产。第二是参数完整率。技能被调用时必填参数是否都被正确填充。如果一个技能频繁因为缺参数返回错误说明参数设计有问题要么是描述没写清要么是必填项本身设计得不合理。第三是执行成功率。也就是技能被调用之后内部逻辑是否顺利跑通有没有报错。我一般会盯这个指标的环比变化一旦出现下滑多半是外部依赖出了问题。第四是用户满意度。这个虽然主观但很真实。用户要是经常说“这不是我要的”那说明技能输出的结果跟用户预期有偏差需要调整返回内容的颗粒度。5.2 我给团队定的技能开发规范经过这么多轮折腾我现在给团队定了一套“技能开发六步走”的规范凡是不按这个流程来的一律不进主干。先确认这个技能是否真的需要独立存在有没有现成的能复用能不能合到已有技能里。写清楚用户需求模板明确触发场景、输出要求、异常处理方式。定义元信息和参数模型邀请至少两个人帮你看description确保不会产生歧义。做沙箱测试用不少于20组真实问题验证准确率。上线前加好监控和日志至少观察一周。定期review技能使用频率三个月没被调用的技能要么改善描述要么考虑下架。这套流程看着繁琐但能帮你省掉后面大量维护成本。别看现在技能少等你手上积累到几十个的时候没有规范就是一场灾难。最后再分享一点个人体会Agent Skills这个思路本质上不是在跟模型较劲而是在帮模型“减负”。你把能力边界切得越清晰模型就越容易做对选择。反过来如果你什么都想往一个技能里塞那就等于把复杂度又还给了模型最终的稳定性一定会让你失望。我现在做新技能时已经习惯先写两版description做对比实验选命中率高的那一版用起来确实稳妥不少。