最近在给团队的项目做技能体系重构翻代码的时候突然意识到一个问题很多人把 agent-skills 理解成“给模型加几个工具函数”但实际上它是一个完整的技能生命周期管理问题。从技能的定义、注册、执行、编排到评估每一个环节都有坑而且这些坑绝对不是靠堆几个 prompt 就能填平的。这篇文章我就用最近在做的智能体项目为例子把 agent-skills 这套东西从头到尾拆一遍。适合正在做 AI 应用开发、Agent 研发或者 Prompt 工程的同学参考尤其是那种已经跑通 demo、正准备上生产的阶段里面提到的很多问题你大概率也会遇到。先交代一下背景我们做的这个 agent 不是聊天机器人而是要真正替用户干活的数字助理比如查订单、订会议室、发通知、操作内部系统。这类 agent 的核心瓶颈不在模型智商而在技能层是否稳——也就是 agent-skills 这一整套机制能不能把模型的能力稳稳落到具体动作上。1. 先搞清楚agent-skills 在智能体里到底管什么1.1 从“会说话”到“会干活”中间夹着一层技能层大模型本身是个推理内核它真正擅长的是理解语义、生成文本、做逻辑推理。但要让 agent 从“会说话”变成“会干活”中间必须有一层东西来承接模型与外部世界的交互这就是技能层。你可以把大模型理解成一个专家大脑技能层就是它的手和工具——没有技能层再聪明的专家也只能给你出主意不能帮你把事办了。这个区分特别重要。很多项目翻车就是因为团队把“模型聪明”等同于“agent 能干”结果发现模型什么都会说但一到真实操作就各种掉链子。不是模型不行而是技能层太单薄。所以 agent-skills 管的事情用大白话讲就是三件让模型知道有什么技能可以用、帮模型判断什么时候该用哪个技能、在模型决定调用之后把技能稳稳执行出结果。这三件事环环相扣缺一环都会出问题。1.2 我把技能体系拆成三层原子技能、组合技能、元技能在做技能体系设计的时候我推荐先按粒度把技能分三层这是整个 agent-skills 的骨架原子技能最小的不可再拆的执行单元比如查询天气、发送邮件、获取订单状态。它只做一件事入参明确出参明确。组合技能按业务场景把多个原子技能编排成一条执行流程。比如“安排会议”这个动作拆开后是查日历、创建邀请、通知参会人三个原子技能按顺序执行。元技能管理和决策层面的技能比如任务规划、执行反思、结果评估、判断当前还缺什么技能。它不直接操作外部系统而是指挥其他技能。这个分层不是拍脑袋想出来的而是从实际维护成本倒推出来的。一开始我们把所有技能都平铺在一起模型的选择空间太大经常选错。后来按粒度拆层之后模型先找组合技能组合技能内部再调度原子技能准确率提升非常明显。举一个我们技能注册表里的简化例子你感受一下这个结构技能名类型入参出参依赖get_order_info原子技能order_id, user_id订单状态、金额、物流信息订单系统create_calendar_event原子技能title, start_time, end_time, participants会议邀请链接日历系统arrange_meeting组合技能topic, participants, preferred_time会议创建结果、通知发送结果create_calendar_event, send_notificationreflect_on_result元技能task_goal, execution_result是否达成目标的判断、下一步建议无这样拆的好处是原子技能可以复用组合技能可以按业务场景灵活拼装元技能负责在更高维度做决策和纠错。整套技能体系不是静态清单而是有结构的、可演化的资产。2. 实操技能怎么定义才能让模型少犯错2.1 技能描述的范式给模型的操作说明书要写“什么时候用”和“什么时候不用”技能怎么定义直接决定了模型调用它的准确率。我发现很多团队写技能描述只写“这个技能是干什么的”比如“查询订单信息”。这远远不够——模型不是人它没有业务背景它判断是否调用某个技能完全靠描述文本里能否找到与用户意图匹配的信号。一份好的技能描述至少要包含以下几个部分触发条件什么场景下应该调用这个技能。比如“当用户询问订单配送进度时调用用户可能表达为‘我的东西到哪了’‘快递什么时候到’”。输入约束参数从哪来有什么限制。比如“order_id 必须从用户输入中提取若用户未提供需要先追问user_id 从当前登录会话获取不允许用户直接传入任意值”。输出说明返回什么格式的数据模型拿到之后该怎么用。负面约束什么情况下不要调用。这一点最关键也最容易被忽略。比如“当用户只是泛泛地问‘订单怎么查询’而没有给出具体订单号时不要调用先向用户索要订单号”。我踩过最狠的一个坑就是没有写负面约束。某个技能在描述里写了“查询订单状态”结果用户问“你们平台能查什么订单”模型也触发了查询技能因为没有真实订单号参数抽取阶段直接幻觉出了一个订单号返回了一堆错误数据。用户看到的结果就是答非所问体验非常差。后来我把负面约束单独加了一段模型的表现立刻稳了很多。所以写技能描述时别光想着“这个技能能做什么”更要写清楚“这个技能不能做什么、什么条件下才该做”。2.2 入参校验和类型设计从源头拦截幻觉参数模型在参数抽取阶段编造参数这是 agent-skills 里发生率最高的问题之一。用户说“帮我查一下上个星期的订单”模型可能就给你编一个不存在的 order_id 出来。要解决这个问题光靠 prompt 约束是不够的必须在技能定义侧做硬约束。我现在的做法是每个技能的参数都用严格的 JSON Schema 来定义指定类型、必填项、枚举值、格式约束。然后在运行时先按 Schema 做校验校验不通过绝不执行下一步。Schema 的写法要注意几个点首先能用枚举就用枚举。比如订单类型明确列出可选的类型值模型就不会编出奇怪的类型。其次能校验格式就校验格式比如时间参数规定必须是 ISO 8601 格式模型输出不合法直接打回。最后必填参数缺了不要直接报错而是触发一次“参数追问”——让模型基于缺失项向用户提问把缺的信息补上。这里贴一段我们做参数校验的核心逻辑用伪代码表达一下思路def validate_and_fix_arguments(skill_name, extracted_args, user_input): schema get_skill_schema(skill_name) errors validate_schema(extracted_args, schema) if not errors: return extracted_args, None missing_params [e[param] for e in errors if e[type] missing] if missing_params: # 不是直接报错而是让模型基于缺失项向用户追问 follow_up build_follow_up_question(skill_name, missing_params) return None, {type: ASK_USER, question: follow_up} # 格式错误的情况尝试让模型基于错误信息二次修正 correction_prompt build_correction_prompt( skill_name, extracted_args, errors ) corrected llm_correct_args(correction_prompt) return corrected, None这套流程的核心思想是校验失败要分情况处理。缺参数就追问格式错就让模型修正连续两次修正失败才降级为报错。这样既拦截了幻觉参数又不会因为一点小问题就把整个对话卡死。2.3 技能注册表让每个技能都有“身份信息”技能数量少的时候用代码写死就行。但技能一旦上了十几个、几十个就必须有一个注册表来做统一管理。这个注册表解决的核心问题是模型上下文窗口有限不可能把所有技能的完整描述一次性塞给模型所以要靠注册表做技能发现和动态裁剪。我们的注册表结构大致是这样的技能 ID、名称、类型、版本号、描述全文、参数 Schema、依赖列表、负责团队、当前状态可用/灰度/下线、调用统计埋点信息。注册表存成 YAML 文件或数据库表都行关键是它要变成运行时的一部分而不是一份写着看的文档。我建议把这个注册表做成动态加载的agent 启动时读取可用技能列表根据当前对话上下文只把候选技能的描述注入到模型 prompt 里。比如用户聊的是订单话题就只注入订单相关的技能描述而不是把 50 个技能全部灌进去。这样做的好处很明显模型的选择空间小了误调用的概率自然下降同时 token 消耗也大幅降低。还有一点需要特别提醒技能版本要管起来。我们曾经有两次线上事故都是因为改了技能描述或参数定义之后没同步更新导致旧会话还在用旧定义新会话用了新定义行为不一致。后来强制要求技能的每次改动都必须升级版本号并且和对话上下文绑定版本快照。3. 技能执行与编排跑通“手、口、脑”的链路3.1 一次技能调用的完整生命周期技能定义好了接下来看它在运行时是怎么被调用起来的。一次完整的技能调用从用户说出请求到最终收到回复大概要经过以下几个环节用户请求 → 意图识别 → 技能选择 → 参数抽取 → 权限校验 → 技能执行 → 结果加工 → 模型生成回复。这个链路里最容易翻车的是中间三段技能选择、参数抽取、权限校验。技能选择错了后面全白搭参数抽取出幻觉执行结果就是垃圾权限校验漏了轻则闹笑话重则出事故。以我们“帮我订明天的会议室”这个请求为例走一遍完整链路第一步意图识别判断出这是一个会议室预订请求。第二步技能选择从注册表里匹配到 arrange_meeting 这个组合技能。第三步参数抽取提取出时间“明天上午 10 点”、人数“4 人”这些信息但缺失“具体会议室”这个参数于是走追问流程。第四步用户补充会议室后进入权限校验确认该用户在会议室系统的预订权限范围内。第五步执行组合技能内部流程查询该会议室明天上午是否空闲空闲则创建预订然后发送通知给参会人。第六步把执行结果加工成自然语言回复“已帮你预订 A204 会议室明早 10 点到 11 点半通知已发送给 3 位参会人。”每一步之间必须有明确的输入输出契约前一步的输出就是后一步的输入。一旦某一环节异常要有清晰的状态记录方便排查是哪一步出了问题。3.2 技能编排的两条路子固定流程和动态规划技能编排是 agent-skills 里最需要设计取舍的部分。目前主流的做法就两条路子固定流程和动态规划各有各的适用场景。固定流程也就是把技能的调用顺序预先编排成工作流。比如“安排会议”这个组合技能内部就是固定的三步查日历、建邀请、发通知。这个路子的优点是稳定、可控、可测试适合业务流程确定、不容出错的场景。缺点是灵活性差业务一变就要改代码。动态规划就是让模型基于技能列表自己规划调用顺序。比如用户说“帮我安排个会议并订好午餐”模型可能自动组合出“建会议邀请、订外卖”两个技能。这个路子的优点是灵活能应对开放式的复杂请求但缺点也很明显模型编排的稳定性差可能步骤顺序搞错可能漏步骤甚至可能自己编造不存在的技能流程。我的经验是生产环境不要走任何一条极端路线而是用混合模式——“规则兜底 LLM 编排”。具体做法是优先匹配注册表里已有的组合技能匹配不到时再让模型做动态规划但动态规划的结果需要经过一层规则校验比如规划里的每一步是否都在注册表中存在、依赖关系是否满足。校验通过才执行校验不通过就告知用户当前无法完成。另外还有一点容易被忽视降级处理。组合技能内部的某个原子技能不可用时整个流程怎么走比如订会议室时日历系统临时故障这时候是挂起整个任务还是先通知用户稍后重试我们实践下来的经验是不要静默失败一定要明确告知用户“哪一步没做成、为什么没做成、接下来可以怎么办”宁可让用户看到进度也不要让用户面对一个毫无反馈的空白。3.3 给技能加上权限和审计这个坑必须提前埋好技能层一旦接入真实系统就必须设计权限模型和审计机制否则迟早出事。比如删除操作、转账操作、发消息这类敏感动作绝不能模型说调就调。我们的做法是在技能执行前加一道权限校验闸口。校验规则分三层用户身份层确认“谁”在发起请求资源权限层确认该用户对这个“资源”有没有操作权限动作敏感度层确认这个”动作“本身是否需要二次确认。比如普通查询技能走第一层校验即可但涉及删除、发送、支付等敏感动作即使前两层都通过了也要弹一次确认框让用户点头确认。审计方面每一个技能的调用记录都要落日志至少包含请求 ID、用户 ID、技能名称、入参摘要、出参摘要、执行耗时、执行结果、异常信息。这不仅是排查问题的抓手也是后续优化技能评估的数据基础。还有一个细节值得提幂等性。写操作类技能要防重放比如用户因为网络超时点了两次“提交退款”系统不能真的退两次款。通用的做法是生成一个全局唯一的 request_id带上这个 ID 做服务端的幂等判断重复提交直接返回第一次的结果。4. 常见问题与排查实录技能“看起来能用一用就翻车”的坑4.1 五个高频问题和排查思路技能体系上了一段时间之后慢慢就会遇到各种“看起来能用一用就翻车”的情况。这里把我遇到过的五个高频问题整理成一张表后面再展开细说问题典型现象根因排查方向技能不触发用户请求完全符合技能范围但模型就是不用技能描述与用户表达匹配度不足触发条件写得太窄收集 badcase分析对话中意图表达的覆盖度参数幻觉模型编造不存在的订单号、日期、ID参数缺少枚举约束可选值未注入 prompt给参数加枚举校验把可选项作为上下文注入执行超时或上下文爆炸技能返回数据过大对话变慢甚至超限结果未做摘要化和分页截断对技能输出做裁剪、摘要、分页技能互相打架多个技能同时被触发或编排顺序混乱技能边界不清组合流程缺少状态约束明确技能触发条件互斥规则组合技能加状态机越权操作用户调用了不该有权限的技能技能层没有建立权限模型增加技能级权限矩阵和二次确认4.2 技能不触发问题通常出在描述和真实表达的鸿沟先说说技能不触发。这个问题的根子在于你的技能描述用的是工程师语言而用户表达用的是自然语言。比如我们有个技能叫 query_leave_balance查询假期余额描述里写的是“当用户查询剩余年假天数时调用”但用户实际说的话是“我今年还能休几天”“我还有假吗”“帮我看看休假够不够去旅行”。如果描述里没有覆盖这些变体表达模型就难以把用户意图和技能关联起来。解决方案分两步走第一步在技能描述里补充丰富的触发示例把同义表达尽量列全。第二步也是最关键的持续收集 badcase定期做一轮“意图—技能”映射回归。我们发现每次迭代触发条件描述之后技能召回率都会明显提升但这不是一次性工作而是要形成固定节奏。4.3 参数幻觉幻觉不是模型问题是约束问题参数幻觉这个事很多人一上来就骂模型不行但其实它更多是约束问题。模型在参数抽取时基于的是 prompt 里的上下文描述如果你没有告诉它“order_id 从用户输入中提取没有就追问”它就只能靠猜而猜编造出来的参数往往看起来十分可信实则根本不存在。我们的解法概括起来是三板斧提示约束、Schema 硬校验、可选值注入。提示约束是告诉模型参数从哪里来、提取不到怎么办。Schema 硬校验是运行时的最后防线校验不过就拦截。可选值注入是把合法参数选项直接提供给模型比如订会议室时把可用会议室列表和 ID 放进上下文再由模型根据用户偏好选择而不是让它自己编造。实测这套组合下来参数幻觉率降了大概七成左右。4.4 让技能学会优雅地说“我不知道”最后一个想展开说的是“技能缺失”时的表现。agent 在遇到自己完成不了的事情时最常见的反面两个极端要么硬编一个不存在的技能去完成要么冷冰冰地回复“我做不到”。这两种都会严重破坏体验。我们做了一次针对性优化当技能匹配和动态规划都找不到可行路径时模型要主动向用户解释“当前我还不能完成这个操作具体原因是……”并且给出一到两个可替代的建议。比如用户要求“把这份合同翻译成英文并盖章发送”如果盖章能力还没接入模型应该回复“翻译和发送邮件我都能做但电子盖章功能还没有开通需要先点一下这个入口授权”。这种坦诚式反馈的体验比假装能干或冷漠拒绝都好得多。这背后其实是一个元技能在起作用识别自身能力边界并给出补救方案。5. 技能评估与迭代怎么知道这套体系在变好还是变坏5.1 建一套技能健康度指标让优化有据可循技能体系上线后最怕的就是凭感觉优化。今天觉得这个描述不对改一改明天觉得那个技能没用删一删结果越改越乱。我们的经验是建一套技能健康度指标让每次改动都有数据支撑。我目前长期看五个核心指标技能调用率、调用成功率、用户侧任务完成率、参数幻觉率、平均响应延迟。其中“用户侧任务完成率”和“调用成功率”是两回事——调用成功只代表技能执行没报错不代表用户的需求真的被满足了。所以我会结合对话终态做评估人工抽样判断这轮对话结束的时候用户问题是否被真正解决。平均响应延迟也要单独盯因为技能调用链路过长会直接影响用户体验延迟超过 5 秒用户感知就非常明显了。这些指标每周看一次趋势比绝对值更重要。比如某技能上周调用成功率和用户侧完成率都在涨但平均延迟在涨那就说明是执行链路变慢导致的而不是描述优化带来的需要单独拆执行链路去查。5.2 回归测试技能版本升级前的必过关卡技能体系的改动非常频繁改一个描述、加一个参数、换一个执行逻辑都可能带来连锁影响。所以必须建回归测试集每次升级之前跑一遍。我们建的测试集结构是对话上下文 用户问题 期望触发的技能 期望抽取的关键参数 期望的回复口径。这些用例一部分来自历史真实 badcase一部分来自核心业务场景的模拟请求。每次技能定义或编排逻辑有变更就用同一批用例跑一遍对比技能选择的准确率和参数抽取的准确率。这里有个小技巧回归测试不能只看“对不对”还要看“稳不稳”。同一个问题跑 10 次代码逻辑是确定性的但模型决策有随机性。我们要设置的是一条容忍线比如技能选择准确率波动超过 5 个百分点就视为不稳定需要排查是不是描述文本中有歧义导致模型在不同结果之间摇摆。5.3 从 badcase 里长出来的技能技能是越维护越多不是越多越好技能体系的演进最终要靠 badcase 驱动。我现在的日常流程是每周从线上对话日志里捞一轮低满意度的会话人工跑一遍归因到具体环节——是意图识别错了、技能选错了、参数抽错了还是执行链路异常了。归因结果汇总后进下个迭代计划。有些问题可以通过调整描述解决有些问题则需要新增技能。举个例子我们发现很多用户会问“这笔订单能开发票吗”之前只在订单详情技能里加了一行说明但效果不理想。后来单独拆了一个 query_invoice_info 技能把开票规则、可开票金额、开票入口全部包装进去用户侧完成率立刻上来了。这就属于从 badcase 里长出来的新技能。但这里也要特别提示一点技能不是越多越好。每一个新增技能都意味着注册表维护成本、模型选择难度的上升还伴随着 prompt 上下文占用的增加。我们现在的策略是新技能先灰度跑两周看调用量和用户侧完成率如果调用量极低或者完成率不达标就果断下线或者重做。定期做技能清理和合并让技能资产保持精简。写在最后的一点体会这套 agent-skills 体系从零搭起来到现在踩过的坑比写过的代码多。回头看我个人的感受是不要把技能体系当成一次性开发任务它更像是一个知识库需要持续的运营和维护。你每加一个技能都建议先问自己一个问题——三个月之后我还愿不愿意维护它如果答案是犹豫的那这个技能的设计可能还不够简洁或者不在核心场景上。最后再分享一个小技巧给技能写描述的时候试着把自己当成一个完全不了解业务的新同事把描述当作一份交接文档来写。如果你觉得这份文档能让一个新同事准确判断什么时候该做什么、什么时候不该做那么这份描述对模型来说大概率也是合格的。
