早在 Agent 这个概念刚火起来的时候我就在折腾各种框架。那时候大家普遍关注的是模型选型、Prompt 设计、记忆机制这些大方向但实际跑下来我发现真正决定一个 Agent 能不能从“演示品”变成“生产力工具”的往往是技能Skills体系的设计。标题里这个 agent-skills说白了就是一套让 Agent 学会“做事”的工程化方法——从按剧本执行到真正拥有可复用、可组合、可观测的“手艺”中间隔着好几层实践经验。这篇内容不是科普什么是 Agent也不是讲某个具体的开发框架而是从我实际项目里摸爬滚打出来的技能体系搭建思路。包括技能如何定义、怎么拆解、怎么写描述才不会被模型误调用、多技能怎么编排协作还有一堆调试时踩过的坑。适合已经在做 Agent 开发、或者正准备把智能体落地到业务里的读者参考。1. 技能体系的核心设计思路1.1 技能不是工具列表而是一个完整的抽象层很多人一开始会把技能理解成“给 Agent 接的几个 API 调用”。比如接入搜索、接入计算器、接入数据库查询然后在系统提示词里写一句“你可以使用以下工具”就以为技能做完了。我最初也这么干过但后来发现问题很快就暴露了。技能的本质应该是一个完整的抽象层。它既不是简单的函数枚举也不是纯自然语言描述的行为建议而是处于两者之间的工程产物。一个合格的技能单元要包含触发条件、输入输出协议、执行逻辑、约束边界、错误处理以及与其他技能协作的方式。这几乎相当于给 Agent “手写岗位说明书”而不只是给它递工具。举一个真实场景。我做过一个团队协作助手类 Agent一开始把“创建任务”“查询日程”“发送消息”都做成独立的工具函数。结果模型经常在应该查日程的时候去发起会议创建或者明明用户已经说完需求了Agent 还在反复确认“您确定要创建这个任务吗”。Review 日志的时候发现问题就出在技能定义太薄了只有函数名和参数缺少上下文触发的判断标准。后来我重新设计了技能层的结构。每个技能会有一个明确的“适用场景”描述和一个“不适用场景”说明。比如创建任务的技能它的适用场景是“用户表达出明确的待办事项、任务指派、截止时间诉求”不适用场景则是“用户只是在询问任务列表、提醒已有安排、讨论优先级”。这听起来像是在写更长的提示词但区别在于这些信息被我结构化地放进了技能的元信息里而不是塞进系统 Prompt 里让模型自己领会。改动之后效果差别很明显。Agent 在决策时的选择准确率高了很多日志里也很少看到“误调用”了。这里面的核心逻辑是模型本身并不知道你的业务流程边界在哪里技能层必须充当“行为护栏”让 Agent 的动作在一个受控范围内展开。1.2 技能分类要用“决策维度”来分而不是用功能维度我见过很多团队把技能分类做成功能标签搜索类、计算类、数据类、消息类。这种分类方式对用户讲解挺友好但对模型决策几乎没有帮助。模型在底层判断该用哪个技能时更多依赖的是当前对话的意图方向、上下文信息的完整度、以及技能输出结果的可预期性。所以我自己在做技能拆解时会从三个决策维度来分成三类。第一是确定性技能。这类技能输入输出边界清晰比如数学计算、日期转换、格式整理、文本截断。模型调用这类技能时几乎不需要做任何权衡只要触发条件满足就必须调用。这类技能写起来最简单但在整个体系里的价值更像“基础设施”。第二类是判断型技能。这类技能需要模型根据上下文做一定的推理和取舍比如意图识别后的路由分发、检索增强时的查询重写、多源信息冲突时的取舍策略。这类技能不能做成“只要触发就执行”的逻辑因为它会产生多样的后续连锁影响。第三类是流程型技能。这类技能往往是多步骤的或者会调用其他技能完成一个业务目标。比如“安排一场会议”这个技能内部可能涉及查询参会者空闲时间、创建日程邀请、发起会议室资源分配、给参会者发提醒。它是一个编排层技能而不是单点能力。这三类的处理方式是完全不同的。确定性技能只要保证参数校验和结果稳定性判断型技能要注意给模型留出足够的推理空间并在输出结构上提供可操作的选项流程型技能则要做成独立的状态机不能被模型中途随意打断或跳步。如果把三类混在一起用一套管理模式Agent 很容易在生产环境里表现出非常“神经质”的行为。1.3 技能描述怎么写直接影响调用命中率这个我特别想说因为太多人在这上面吃亏了。技能描述也就是我们常说的 skill description不同于函数注释。函数注释是给开发人员看的可以写很多技术细节技能描述是给模型看的它的目标是让模型在正确的时机以正确的参数调用正确的技能。我最早写技能描述的时候照着 OpenAPI 文档风格写每个技能都附带详细的参数数据类型、默认值、返回值说明。后来看调用日志发现模型经常把技能 A 的参数按照技能 B 的逻辑传给技能 A例如给字符串字段传一个 JSON 对象。排查了很久才发现是描述里关于参数格式的说明太抽象模型在低概率采样时产生了错误联想。现在我写技能描述会遵循三个原则。第一个原则是“场景优先于功能”。开头第一句话先用自然语言描述这个技能会在什么情境下被用户需要而不是先写这个技能的输入输出。例如“当用户试图安排多人的线下会议且给出了会议主题和时间范围时这是一个需要调用 meeting-scheduler 技能的情境”。这样模型在做动作决策时匹配的是意图语义而不是字面函数名。第二个原则是“给出反例”。我会在每个描述里加一小段“不要调用该技能的场景”。比如分诊路由技能要明确说明“当用户只是想了解某个部门的上班时间时不要调用分诊路由直接回答即可”。反例信息对模型纠正边界很有帮助。第三个原则是参数示例用真实值。描述里的 JSON Example 不能写占位符比如 name: string要写成 name: 张三。模型对具体值的理解远好于对类型标注的理解。这一点我是在观察多次调用失败后总结出来的。2. 从零搭建一套技能集的关键步骤2.1 先做技能盘点再谈技术实现如果你的 Agent 已经跑了一些基础流程或者你准备给 Agent 设计技能体系第一步不是写代码而是做技能盘点。拿一张白板把所有可能用到的能力域列出来再针对每个能力域去拆解“用户的话术长什么样”“这个能力内部会经过哪些环节”“成功和失败分别以什么状态返回”。我会按五个维度做盘点能力名称、触发的用户意图、前置依赖条件、执行步骤清单、输出产物。这五个维度确定清楚了后面写技能描述和实现逻辑都会顺畅很多。如果这一步偷懒后面每加一个技能都要返工非常折腾。举个例子如果我要给一个客服型 Agent 做“退款进度查询”技能。触发意图是用户询问退款到哪一步了前置依赖条件包括用户身份已识别、退款单号已提取。执行步骤则拆成调用订单系统查询退款单状态、判断退款单所属阶段、拼接最新的进度话术。输出产物是一个包含状态文本和一个可选解释字段的消息结构。这些信息比“入参 orderId出参 status”要丰富得多对模型判断有实质帮助。盘点结束后你手里就有了一张技能的“全局地图”。接下来才进入具体实现。2.2 因子化拆技能不要每个动作都做成独立技能有些开发者喜欢把一切拆成粒度极细的技能比如“发送验证码”技能、“校验验证码”技能、“刷新验证码”技能。粒度太细的问题在于模型需要在众多语义相近的技能里做选择出现误选的概率会成倍上升调用链也会越来越深。我在实践中的经验是技能粒度应该按照“业务可理解的子目标”来定。也就是说一个技能对应一个用户能感知到的结果。比如“完成验证码校验”可以作为“用户登录”这个业务子目标的一个技能而不是把“发送验证码”单独拆出来。发送验证码只是过程中的某一步可以放在技能内部的执行逻辑里处理没必要暴露给模型做决策。这样做的好处有两个。一是模型决策面变小了技能数量精简之后选择的准确率自然提高。二是技能内部的可扩展空间变大了以后如果要在发送验证码之前加一个风控检测直接在这个技能内部加逻辑就行模型不需要知道这些子步骤的存在。当然使用一个复合技能时也要注意技能内部执行的步骤越多出问题的可能性就越大。我会为每个复合技能单独写一个状态机记录它执行到哪一步了哪一步失败了失败后是重试还是终止。这样即便出了故障也能从日志里快速定位。2.3 技能注册表与动态发现机制当一个项目的技能数量超过十个静态的“把所有技能都塞给上下文”的设计就成了明显的性能瓶颈。一方面模型每轮对话都要处理大量与当前场景无关的技能描述注意力被稀释另一方面 token 成本也扛不住。这时候就需要技能注册表和动态发现机制。简单说就是先有一个记录了所有技能元信息的注册表然后在每轮对话开始时基于当前对话状态做一次技能召回只把相关技能注入到上下文中。我做动态召回时的做法是先给技能打上领域标签和状态标签。领域标签像是财务、日程、审批状态标签像是需要用户确认、后台静默执行、结果可展示。然后写一个轻量级的召回器基于用户当前 message 的向量相似度加一些规则约束筛出 top-N 个候选技能。规则约束很关键比如财务领域的技能召回如果当前会话没有完成身份核验那相关技能就会被直接排除掉。这些机制的实现并不复杂但它让技能体系具备了规模化的能力。不然技能越多效果越差会很打击团队信心。3. 技能编排协作的实操路线3.1 从串行调用到状态感知的任务编排Agent 通常不会只调用一个技能就能完成任务。多数业务流程需要多个技能按某种顺序协作。最简单的编排方式是让模型自行决定技能调用顺序这就是大家常说的“Agent 自主规划”。这个方法在简单场景下可行但在复杂业务流程里会经常出问题。模型会在中间步骤缺乏判断依据时就开始“自由发挥”把不该调用的技能串联起来。我采用的方案是做一层轻量的状态感知编排器。它不去替模型做所有的决策只维护一个当前任务的上下文状态表。这张表里记录了当前流程的阶段、已经完成的步骤、各步骤产出的数据依赖。当模型想调用某个技能时编排器先检查前置条件是否满足。例如未完成身份核验时任何涉及用户敏感数据的技能都不能被调用。这套机制在工程上的实现并不难但收益非常明显。Agent 的自主性依然存在但它的自由度被约束在业务流程的安全边界内。这就是技能体系从“能用”走到“可控”的关键分水岭。3.2 技能切换的上下文交接设计多个技能协作时最容易被忽略的问题是上下文交接。比如一个技能输出了中间结果到下一个技能执行时模型可能记不住前一个技能返回里的细节。这是很多 Agent 项目表现不稳定的主要原因之一。我的做法是使用结构化的上下文槽位来显式传递关键数据。举个例子在一个“客户投诉处理”的流程中第一个技能负责从用户陈述里提取结构化信息包括订单号、问题类型、客户情绪等级输出一个结构化槽位。第二个技能在执行解决方案推荐时并不是从聊天历史里自己找数据而是从槽位中读取。这样做的优势在于即使中间经历了较长对话槽位数据依然稳定可靠不会因为对话轮次增加而丢失或模糊。而且后续如果要做多轮修正只需要更新槽位里的字段即可模型不用重新从头理解整段历史。实际排障时也非常好用看一个技能的输入输出就能定位上下文数据到底正不正确。3.3 并行与回退进阶编排的必要功课有些技能的调用没有前后依赖关系比如在分析用户问题时需要同时检索内部知识库、查询历史工单、拉取产品文档。如果串行执行既浪费时间又增加多次调用的延迟。把这些无依赖的技能并行触发在各结果就绪后再做汇总是性能优化很直接的手段。但并行也有坑。如果并行调用的多个技能访问了同一个共享资源或者其中一个技能的结果会改变其他技能的输入条件就不能简单并行。我遇到过并行调用后检索型技能拿到的知识快照和判断型技能所基于的数据版本不一致导致输出自相矛盾的情况。现在我的做法是在设计技能时明确标注“可并行”和“不可并行”两类属性并由编排器控制调度策略。回退机制同样不可忽视。当一个流程型技能执行失败时究竟是重试当前步骤、跳过它还是换一个替代路径需要提前定义。一套好用的回退机制不是让模型临场判断而是在编排器里配置好回退策略。比如检索类技能连续失败两次后自动切换为“仅回答通用建议”的降级模式。这种提前设计好的降级路径比让模型面对报错时硬着头皮胡编要可靠得多。4. 常见问题与调试实录4.1 技能被频繁误调用怎么定位和修正这是我在支持其他开发者时最常被问到的问题。技能误调用的典型表现是用户明明在闲聊Agent 却调了一堆技能或者用户咨询 A 类型问题时Agent 优先调用了 B 类型的技能。排查这类问题我一般从三个角度走查。首先看技能描述是否足够有区分度。打开所有技能的 embedding 或者语义相似度看看如果 A 技能和 B 技能的描述相似度过高模型当然会在两者之间摇摆不定那就需要重写描述把各自的应用场景讲得更鲜明。其次看上下文中有没有让模型混淆的表述。比如系统提示词里把“查询”这个词既用于搜索技能场景又用于数据库查询技能场景就容易诱导误判。第三看召回器。如果做的是动态召回要检查是不是召回候选集里同时混入了多个高度相似的技能把决策难度放大了。一个很具体的修正案例是我曾有一个“日程查询”技能和一个“待办事项查询”技能。它们的描述几乎都是“获取用户的日程或待办事项列表”只是参数不同。导致模型经常把“查询待办”识别成“查询日程”。修正之后我强调了一个关键差异日程技能需要绑定具体日期和时间点待办事项技能则没有时间段概念只关心完成状态误调用率就明显降下来了。4.2 技能内部报错模型“假装成功”怎么破技能调用失败后Agent 可能没有把错误信息透传给用户而是顺着上下文一本正经地编造一个结果。这个问题在生产环境里非常致命因为用户会把假结果当成真结果去执行。解决这个问题的核心是“失败必须显式化”。我在技能的输出协议里规定凡是执行失败的技能必须返回一个结构化错误对象包含错误码、可读错误信息、以及降级建议。同时要提供一个“无法验证”的置信度标记。如果技能没有返回但是模型还在往下走那我就会在编排器里拦一道连续多次调用无有效结果的任务必须被标记为失败并引导用户补全信息或转人工。这个机制看着简单但很多项目就是忽略了它在工程上的强制性。技能层的核心任务是消除不确定性假设模型总能正确处理异常状态。是错误的设计取向。4.3 回归验证技能改完别忘旧场景技能的迭代频率通常很高。改一个参数的描述调整某个步骤的执行逻辑或者替换内部的第三方服务都可能无意中影响已有正常运行的技能链路。我也经历过这样的情况改了一个底层检索技能的超时时间结果导致两个高层编排技能的执行节奏全乱了之前能跑通的流程全部异常。后来我建立了一个技能回归数据集。每个技能至少配三组典型场景、三组边界场景、三组错误场景。每次改动技能就把这些数据集跑一遍看输出是否符合预期。虽然没法做到全靠自动化但至少能拦住很大比例的回归问题。尤其在技能数量增多之后这可以说是最省力的避坑方案了。如果团队人少哪怕用手工方式做回归记录也比不做要强得多。我见过太多项目在推进新功能的过程中悄悄丢掉了旧功能到了演示给业务方的时候才被发现已经不能用了。4.4 调试技能时最推荐的信息采集思路调试 Agent 技能比调试普通后端接口难得多因为输出的不确定性来自模型本身。我的经验是在设计阶段就要把可观测性想进去。每个技能调用时都要记录入参快照、出参快照、执行耗时、调用链上下文、以及模型决策的理由草稿。有了这些数据后复现问题时不需要用户再重新描述一遍直接查看调用链就能还原当时的决策过程。我从自身经验出发结论是可观测性越早做后续调试返工的次数就越少。不要等到几十个技能都上线后再补充日志到那时候你会发现自己陷入了一团理不清的纠缠中。我在实际使用中还有一个心得技能设计这件事不存在一次性做到完美这个选项。模型在升级框架在变化业务流程在调整技能体系必须跟着迭代。维护一套技能集本质上是在维护一份活着的操作手册。这既是工程能力的体现也是 Agent 效果长期稳定下来的根基。