1. Agent Skills是什么先从一个翻车的项目说起去年年中我接手了一个企业内部知识库助手需求听起来不复杂员工在飞书里问一句上季度的报销流程是什么机器人就得给出准确答复顺便把相关表单链接甩出来。最开始我走的是当时最流行的路子——把所有业务规则、文档索引、问答逻辑全部塞进一个巨大的System Prompt里再配上几个function calling接口。初版跑起来确实像那么回事demo演示的时候管理层还点头了。但上线第三周就出事了。随着业务文档从二十篇涨到两百篇Prompt从三千字膨胀到八千字模型开始频繁出现幻觉把去年的报销标准答成前年的甚至会把休假申请和调休规则混着答。我试着继续往Prompt里加约束结果就像往沙子里掺水越多越散。后来我彻底放弃了增量修Prompt的方案把架构重构成基于Agent Skills的技能编排模式——三个星期后准确率从76%拉到了94%维护成本还降了一半。今天这篇就聊聊一个合格的Agent Skills体系应该怎么搭哪些坑我是真金白银踩出来的。这篇文章适合谁看如果你手上正在做AI客服、Copilot工具、知识库机器人或者任何一个大模型要执行多步任务的项目并且已经感受到大Prompt方案越来越难维护那这篇文章正好解决你的问题。我会先讲清楚Skill的底层架构逻辑再给出一套能落地的实现方案最后把我排查过的几个真实翻车现场摊开给你看。2. 为什么大Prompt硬调这条路必然走死2.1 上下文窗口再大也装不下整个业务系统很多人的第一反应是模型上下文窗口不是有两百万token了吗把所有东西都塞进去不就行了这个想法我在项目里也试过但实践下来有三个绕不开的硬伤。第一个硬伤是注意力稀释。模型对Prompt头部和尾部的内容记忆最强中间部分最容易丢失。当一份业务手册被塞进上下文中间位置时模型对它的关注度会显著下降表现出来就是——规则明明写在Prompt里模型却像没看见一样自由发挥。第二个硬伤是更新成本。业务规则每个月都在变每次修改都是对Prompt的一次大手术改一行字可能引起系统其他部分行为异常而且无从排查。第三个硬伤最致命——你没法测试。Prompt越长输出越不稳定同样的输入今天能答对明天就答错回归测试根本没法做。2.2 推理与执行混在一起必然互相污染我在重构前好好想了想为什么大Prompt方案这么脆弱根子上是因为它把**推理该做什么和执行怎么做**搅在了一起。举个例子。知识库助手的任务是查报销规则并举一反三给出注意事项。在旧架构里模型要先理解这个任务属于哪个业务域然后在八百行Prompt里定位相关规则再决定要不要调用接口拿最新数据最后还要组织语言答给用户。这四层思考全都发生在一次推理里任何一个环节状态不好整条链路就歪了。Agent Skills的思路是把这四层拆开第一步模型只负责判断这问题归哪个Skill管第二步Skill内部预先定义好了该怎么办。判断是模型的活执行是代码的活两者不再互相干扰。用大白话说大Prompt模式是让AI当全才实习生——每个任务都要现场想一遍流程Skill模式是让AI当调度员——它只负责把工单派给合适的老师傅。2.3 可观测性与可维护性的鸿沟还有一个经常被忽略的问题是排查故障的效率。大Prompt方案里用户问一句报销比例多少模型答错了你根本不知道它是在哪一步想错的是没定位到规则是规则太长读漏了还是定位对了但输出时表达错了这不是玄学这就是架构缺陷——你拿不到中间过程的日志能看到的只有输入和输出。Skill架构天然具备日志切面。模型判断这个问题属于Query_LeavePolicy然后Skill执行体去数据库捞数据——每一步都有明确的日志节点。用户投诉一条答错的消息我打开链路追踪一眼就能定位是模型选错了Skill还是Skill里的数据查询出了问题。这个差异在调试期还不明显等业务量上来之后就是天壤之别。3. 一个可用的Agent Skill到底长什么样3.1 解剖四个核心组成部分很多人理解的Skill就是给模型多一个工具这个认知太浅了。一个真正可用的Skill要包含四个层次的内容缺一个都容易在生产环境出问题。第一层是元数据Skill Definition。这层负责向模型描述这个Skill叫什么、管什么用、什么情况下该用它、不该用它。这是模型做意图路由的最关键依据也是整个体系里最需要打磨的部分。我见过太多团队把description写得太笼统比如处理请假相关查询模型根本分不清我明天想休息一天和帮我看看我的年假余额该走哪个Skill。第二层是输入Schema。也就是这个Skill接收哪些参数每个参数的类型、格式、约束条件是什么。这一层决定了模型猜你的接口参数时有多容易出错。我实测下来的经验是参数越少越好命名越贴合自然语言越好必填项之外的都尽量给默认值。第三层是执行逻辑。这是Skill真正干活的代码体——可能是调用内部API可能是拼装查询语句可能是触发下游工作流也可能只是做一次模板化回答。要注意的是执行逻辑里头还要包含输入校验和结果检查不能假设模型给的参数永远是合法的。第四层是失败处理。这是最容易被人忽略、但生产环境最要命的环节。Skill调用了外部API结果服务挂了这时候是返回兜底回答、重试三次、还是把错误反馈给模型让它换个思路没有这层设计Skill体系会在真实流量下被冲垮。3.2 一个可直接参考的Skill定义示例以我项目里的查假期余额Skill为例它的定义是这样写的{ name: query_leave_balance, description: 查询员工当前可用的年假、调休、病假余额。当用户询问我还有多少天假年假剩几天能不能休两天调休等涉及具体假期余额数值的问题时必须使用本技能。注意本技能只查余额不处理请假申请流程。, parameters: { type: object, properties: { employee_id: { type: string, description: 员工的工号可以从对话上下文中提取若无法确定则默认为当前会话用户 }, leave_type: { type: string, enum: [annual, compensatory, sick, all], description: 要查询的假期类型若用户未指明则设为all } }, required: [employee_id] } }注意这个Skill里我写了注意本技能只查余额不处理请假申请流程这不是废话这是在模型路由时给它一把尺子——防止用户问我要请假两天时模型误调用这个只读类Skill。在模型能力不够强的阶段这种正向反向约束非常管用。代码运行效果如何需要加入你自己的真实项目场景来验证。在我实际系统中Skill执行业务流程图如下用户提问 -- [意图路由模型] -- 匹配到query_leave_balance -- [参数抽取] -- employee_id10023, leave_typeall -- [执行体] -- 调用HR系统API -- 获取结果 -- [模板化组装] -- 您的年假余额为7天调休余额为2天 -- [失败重试兜底] -- 若API超时则回复系统繁忙请稍后再试3.3 路由层怎么选型模型判断还是规则优先Skill的执行逻辑写好了接下来要解决的问题是模型怎么知道该调用哪个Skill这里有两个主流方案——纯模型路由和规则兜底模型路由。纯模型路由最省事让大模型读一遍所有Skill的description然后输出自己该调用哪个。缺点是模型会有概率性抽风Skills一多还会互相抢生意。我目前的线上方案是混合式先用非常轻量的规则层做前置过滤比如会话中检测到余额剩几天这类强关键词直接把候选Skill范围缩小到两三个再把缩小后的候选列表交给模型裁决。这么做的实测效果是路由准确率从88%提升到96%而且规则层逻辑简单出了问题容易调。4. 从零构建一个技能库五步落地实操4.1 第一步盘点高频任务划清边界不要一上来就写代码先用一个周末的时间把业务方的历史提问记录翻一遍。我当时的做法是把三个月内所有用户问句拉出来按主题聚类统计频率然后给每个主题写一句话定义。这里有个关键经验Skill的粒度宁可粗一点也不要切太碎。我刚开始把查年假查调休查病假拆成了三个Skill结果模型频繁把问题路由错。后来合并成query_leave_balance一个Skill、内部用参数区分假期类型准确率立刻上来了。Skill粒度怎么判断我给你一个标准如果你发现自己要写超过三句话来解释这个Skill的边界那它大概率太碎了反过来如果这个Skill里要写一排switch case分五六种逻辑那它太胖了应该拆。一铲子下去边界清清楚楚的才是好Skill。4.2 第二步把description写成给陌生人看的产品说明这回是Skill工程里最考验功力的环节。很多技术出身的朋友容易把description写成技术文档风格——调用此接口可获取员工假期余额数据但关键问题是模型不是人它要用这段描述来判断意图描述写得好不好直接决定路由质量。我总结了一个description写作公式触发场景 具体例句 反向排除。触发场景是当用户询问XX时具体例句是例如我还有多少天假年假剩几天——例句宁可多写因为模型对具体句子的理解力远比对抽象规则的理解力强。反向排除是注意本技能只查余额不处理XX情况这个能显著降低模型把相似意图误判到这个Skill的概率。4.3 第三步参数Schema设计要克制参数设计的核心思想就两个字克制。我踩过的坑是给Skill设计了七八个参数期望模型一次性把信息全抽出来。结果模型在抽取时频繁出错缺这个漏那个。后来我把参数缩减到只留关键的两三个其余信息交给执行体内部从上下文或数据库补全。比如查假期余额这个Skill其实只有一个必填参数——employee_id。leave_type给了默认值all。这样的话模型就算没听清用户要查哪种假也不会调用失败。记住每个必填参数都是一次潜在的意图误判点能省则省。4.4 第四步执行体要带防呆设计执行体是Skill真正干活的代码很多人都写得很直给——拿到参数直接请求API拿到结果直接返回。这在真实生产环境是大忌。我在重构后给所有Skill的执行体加了三个标准件第一个是输入预校验。模型抽出来的employee_id可能带空格、可能是中文数字甚至可能跟用户提的不是同一个人的工号。我在校验层做了格式清洗、白名单校验不合法就进失败分支。第二个是结果结构校验。外部API返回的数据未必是预期的格式特别是HTTP 200但body里是个错误码这种情况需要显式判断。第三个是降级分支。API超时、限流、异常都应该有对应的温和回复不能直接把堆栈拋给用户。这里用Python写一个执行体骨架你可以直接参考def execute(employee_id: str, leave_type: str) - Result: # 输入预校验 employee_id validate_employee_id(employee_id) if not employee_id: return Result( statusfailed, reply抱歉我没有识别到您的工号请确认是否已绑定账户。 ) # 核心调用 res hr_api_client.get_leave_balance(employee_id, leave_type) # 结果结构校验 if res.code ! 200 or res.data is None: log.warning(fHR API返回异常: {res}) if res.code 504: return Result(statusfailed, reply系统查询超时了请稍后重试) return Result(statusfailed, reply暂时无法获取假期余额请稍后再试) # 模板化组装 balance res.data reply build_reply_message(balance, leave_type) return Result(statusok, replyreply)加的每一层看起来都多余但生产环境的数据辣不辣眼睛只有上线后才知道。没有这层防呆一个API偶发超时就能让整个Agent体系被用户骂上热搜。4.5 第五步建立Skill回归测试集Skill体系的优势之一就是可以做回归测试。我建了一个意图金标集从历史真实用户问句里挑出200条人工标注好每条应该路由到哪个Skill。每次改完一个Skill的描述或路由规则就跑一遍这批测试数据看看路由准确率是升了还是降了。没有这套机制你就永远不知道改完一个Skill是不是把另一个Skill搞挂了。这里有个实操细节金标集需要每隔一两周补充新问句。用户总会用你意想不到的话术提问把带回来的新case加入测试集路由准确率才会持续提升。维护这个测试集是我认为整个Skill体系里性价比最高的一件事。5. 实测中的翻车现场与排查链路5.1 事故一两个Skill怎么也分不清上线第一周就出现了一个诡异现象用户问报销打完款了吗系统一会儿走查报销进度Skill一会儿走查报销规则Skill。我在日志里追踪发现路由模型在两个Skill的description之间反复横跳相同的问题今天走A明天走B。排查链路是这样的首先打开链路日志确认问题确实出在路由环节而不是执行环节——两个Skill都执行成功了但选错的那个答案牛头不对马嘴。然后我把两个description拿出来并排看问题立刻暴露了——查报销进度的description里写的是处理报销相关查询而查报销规则写的是回答报销标准相关问题。模型会认为报销打完款了吗既跟进度有关又跟规则沾边于是两边都在候选区。修复方案很简单把description改成互斥的强烈触发词。查报销进度只回答钱到哪了、款有没有打、审批走到哪一步了查报销规则只回答能报多少、范围是什么、流程怎么走。改完之后相同问题的路由准确率从82%升到了99%。教训描述Skill时痛痛快快地把这个Skill的场景边界锁死不要用模糊的领域词汇。5.2 事故二模型抽参数时过拟合到了错误语义有一次用户问我想用调休抵半天你看看我这周还能不能请假——这个问句其实包含两个诉求查调休余额、顺便确认能不能请假。我的路由模型正确选到了query_leave_balance但是参数抽取环节把leave_type抽成了sick因为请假两个字触发了病假联想。结果系统一本正经地回答您的病假余额为5天用户当场无语。这个问题的根因在于参数抽取的提示词里给的枚举含义不够清晰。我给enum值写了annual年假、compensatory调休、sick病假模型确实没有理由把请假理解成调休。修复办法是在description里把每个枚举值的语义都写了跨场景例句——当用户提到调休换休时使用compensatory——效果立竿见影。参数枚举命名的偏差是Agent体系里最容易忽略但实际频繁翻车的地方。5.3 事故三Skill内部的循环请求烧穿预算还有一个让我后怕的事故。某个Skill的执行体在调用外部搜索API时如果第一次结果为空代码里写了一个for循环自动换关键词重试三次。结果某个高峰期搜索API响应变慢一批请求全部触发了循环重试单次用户请求最多发了12次外部API直接导致合同额度超支。排查链路从成本监控告警开始拉出计费日志定位到一批search_skill的调用链看到每个链路里都挂了七八次API记录。修复方案是给所有外部重试加上总次数上限、单次超时和熔断开关同时在Skill执行体入口加了一层高峰期限流。这里要提醒一句给执行体写重试逻辑之前一定先做一次极端情况推演——如果外部系统延迟百分之五十我的重试策略会把流量放大几倍5.4 一套通用的排查方法链路日志 回放测试踩了这么多坑之后我沉淀了一套自己的排查流程分享一下先看路由日志确认模型选的是不是对的Skill。不是的话问题在意图路由层。再看参数日志确认抽出来的参数合不合理。参数错了问题在抽取层。看执行日志确认执行体内部的每一步是否按预期走。用金标集回放把出错的用户问句喂给同一个系统确认修复是否生效、有没有副作用。这四步走一遍大部分问题都能精准定位。如果你发现始终定位不到问题那就要回头检查是不是Skill的description写得太模糊导致模型行为本身不稳定——这种情况改了日志也查不出花来。6. 从能用到好用技能调优与体系演进6.1 多轮对话里的状态与记忆是Skill体系的隐藏难点单个Skill调好了还不够多轮对话场景才是真正的分水岭。用户说帮我查一下张三年假接着又补了一句顺便看看他的调休——这句话在系统里怎么处理最自然的设计是让上一轮的Skill状态延续下来把第二轮的两个参数合并进第一轮的查询上下文里。我的实现思路是引入一个轻量级的会话状态槽位第一轮Skill执行完后我把参数和结果摘要写回会话槽位第二轮路由模型先看槽位里有啥再决定是新建Skill调用还是基于槽位信息增量执行。说实话这个模块目前还没有标准答案各家都有自己的实现方式。我的建议是第一阶段别追求通用记忆机制先把业务强相关的状态槽位做好就够了——比如刚才那种查询类场景一个skill_result_slot就能覆盖绝大多数需求。6.2 Skill版本管理与团队协作当你的技能库超过二十个Skill并且是三四个人一起维护时版本问题就浮出水面了。我们今天上午刚改完A Skill的路由描述下午发现B Skill的准确率掉了——这种狗血剧情我经历了不止一次。落地方案非常朴素但好用每个Skill的变更必须走Pull Request路由金标集测试必须过90%才能合并。Skill的description变更看似是个小改动但影响的可能是所有路由的决策分布。把改了Skill描述必须附带金标集通过率写进代码评审清单能挡掉至少一半的踩坑。另外执行体代码和Skill描述文件一定要放在同一个仓库同一次发布里分开管理会出现描述已经写好了代码还没部署的中间态触发各种离奇错误。6.3 跨Agent的技能共享——下一步的扩展方向目前我正在尝试把Skill抽象成团队级的共享资产。思路是建一个内部的技能注册中心每个Skill定义成一个带契约的声明式文件任何Agent实例都可以通过注册中心拉取。这样新开一个Agent项目不用从零维护一套技能库直接注册需要的现有Skill即可更多时间去沉淀新的业务技能。这里做一个小预告声明式Skill定义如果能标准化未来的Agent协作会变得更像乐高拼装——不同团队维护不同的技能模块上层Agent通过编排把它们组合成完整工作流。到这个阶段Agent不再是单个系统的附属品而是一个可以跨系统复用的业务能力层。这中间的技术选型比如用JSON Schema还是YAML做契约、要不要引入语义注册表还在探索中有进展了我再写一篇继续分享。最后再补一句个人体会我在这个项目里最大的收获不是技术方案的升级而是重新理解了架构的意义——把需要猜的部分和不需要猜的部分干净利落地分开永远好过在大Prompt里用更多的文本去掩盖不确定性。Agent Skills的本质就是这条原则的工程化落地。