1. 先想清楚一个问题Agent到底缺的是技能还是说明书最近我在整理内部技能库的时候发现一个很有意思的现象很多同学对Agent的效果不满意第一反应都是把提示词再写长一点上下文再塞详细一点。结果Prompt越来越厚模型越用越笨该出错的地方照样出错。最后大家才慢慢意识到Agent真正缺的往往不是一份更长的说明书而是一套能重复执行、可验证、能兜底的技能。这里说的技能不是指提示词模板也不是指某一次任务里临时拼出来的工具调用链。它是一种被结构化封装过的执行能力包含触发条件、输入输出约定、领域知识、操作步骤、回退方案以及和外部工具之间的明确边界。你可以把它理解成给Agent装了一个专用遥控器——按哪个键、执行什么动作、出了问题怎么复位全是预先设计好的而不是每次都让模型从零开始读说明书。为什么这个概念值得专门写一篇因为技能设计的好坏直接决定了Agent从能聊会答变成能干活且稳定干活。我在团队里推动技能化改造几个月后任务完成率、返工率、可维护性都有明显变化但也踩了不少坑。这篇文章就把整个思路、步骤和翻车经验都摊开来讲适合正在做Agent应用、被提示词越写越乱困扰的朋友参考。先说一句总体判断Agent技能的本质是把不可控的自由发挥压缩到可控的参数空间里。模型仍然是模型但你的设计决定了它是在做选择题还是在做开放作文。2. 一个可落地的技能应该拆成哪几层以会议纪要结构化为例很多人在设计技能时最容易犯的错误是只写操作步骤比如请将会议内容整理成纪要然后就没有然后了。这样出来的东西只能算一个很弱的Prompt根本不具备技能的鲁棒性。我现在的习惯是在写任何技能之前先把下面五层拆干净缺一层都不开工。2.1 触发层什么时候该启用这个技能触发层回答的是这个技能在什么场景下被选中。它不是你给用户看的营销描述而是给Agent的路由信号——当用户请求满足哪些特征时优先匹配这份技能。以会议纪要结构化这个技能为例我通常会写两类触发信号。一类是显式关键词比如会议纪要整理重点归纳待办另一类是隐式场景比如输入文本中有多个人名、有时间点、有下一步需要跟进这类动作词。要注意触发描述不要写得像聊天话术否则Agent会在用户随口说一句把会议记录发我看看时也误触发。我踩过一个很典型的坑某个技能描述里写了帮助用户整理信息结果它在用户问帮我梳理一下思路时也被抢着调用反而把本该走通用对话的请求截走了。后来我把所有的触发表述全部改成仅当出现……以下情况优先使用规则感立刻清晰了很多。2.2 知识层技能必须携带的领域信息和边界条件知识层是技能区别于普通Prompt的关键。它告诉Agent做这件事时有哪些事实是必须遵守的有哪些是绝对不能做的有哪些是需要实时获取的。拿会议纪要技能来说知识层至少要包含公司内部对待办项的定义必须包含负责人、截止时间、验收标准纪要不允许编造数据凡是没有原始发言支撑的结论要标注存疑涉及多轮讨论的内容需要区分已确认进度和尚未达成一致两部分。边界条件也要写清楚。比如该技能只适用于单次会议转写文本不适用于处理历史归档中的上百条散乱记录又比如输出语言与输入语言保持一致不能用户发中文会议内容结果纪要里夹带了一大段英文。我常打一个比方知识层就像说明书里的安全须知和产品规格把这两部分写到位Agent才知道自己不是在自由创作而是在按规格加工。2.3 操作层动作序列、工具调用与参数映射操作层是整个技能最硬核的部分它描述Agent要按什么顺序执行、每一步调用什么工具、工具参数从哪来。这里最常见的错误是让Agent自己看着办正确做法是给出一套明确的、带优先级的执行路径。还以会议纪要技能为例我在操作层里会设定如下顺序先对原始转写文本做分段清洗去掉明显的语音识别噪音比如重复词汇、无效的语气词。再从文本中抽出每位发言者提出的事项按事项主体-动作-期望结果三要素归档。接着识别每件事项的归属人如果原文没有明确归属就标记为待确认不允许擅自指定。最后按固定模板输出纪要模板包含会议背景、已确认结论、待办事项、遗留风险四个区块。每到一个步骤我还会写明这一步的输出是什么、下一步的输入是什么。因为Agent在长任务里特别容易走一步忘一步如果中间缺少显式的状态传递它就可能在第三步把第二步的成果丢了直接开始东拉西扯。参数映射则指工具调用时的字段来源。比如要写入企业内部的在线文档接口可能需要会议ID纪要正文参会人列表这些字段。设计技能时就要提前约定好会议ID从原始文本中的会议链接提取纪要正文由第四步的模板生成参会人列表从文本开头的人员名单区域解析。字段没有映射规则的时候Agent往往会拿错误的值去填充轻则写入错位重则触发接口报错。2.4 回退层失败时怎么降级而不是硬撑技能设计里最缺少意识、也最见功力的是回退层。大多数人的第一版技能只有一条路走到黑成则成不成就是生成了一堆乱七八糟的东西用户还得自己返工。我的经验是每个技能在关键节点都要配一个回退钩子。比如会议纪要抽取待办时如果结构化解析的置信度不够例如原文本里通篇都是闲聊没有实质事项那就不要强行假装提炼而是原样输出本次会议未识别到明确待办已保留原始发言片段供人工确认。再比如调用了在线文档接口但写入失败就不要让Agent假装成功而应该触发一个降级动作输出Markdown格式的纪要文本同时附加一句提示在线同步失败请复制到文档中手动归档。别小看这个认怂设计。Agent一旦学会做不到就说做不到、做不了就降级处理整体可信度反而比硬编答案高得多。这也是为什么我在团队里反复强调技能的回退逻辑必须在第一步开发时就写进去而不是出了问题再补。3. 从零构建一个最小技能包定义、注册、验证的完整链路把层级想清楚之后接下来就是动手做最小技能包。我会用一套相对固定的流程推进先写技能定义文件再把文件注册到运行时最后用一组评测用例验证。每一步都有相对标准的做法下面给出具体可落地的版本。3.1 编写技能定义文件骨架结构与字段说明技能定义文件是技能的身份证一般用JSON或YAML描述。我习惯用JSON因为它与大多数配置系统兼容度更高也方便程序化校验。参考骨架如下{ skill_id: meeting_notes_v1, name: 会议纪要结构化, version: 1.2.1, description: 仅当用户请求包含会议纪要、整理待办、归档讨论结论等场景时使用, trigger: { keywords: [会议纪要, 整理重点, 待办项, 讨论结论], domain_hints: [多个人名, 时间点, 跟进动作] }, input_contract: { required_fields: [raw_transcript, meeting_topic], optional_fields: [participants, meeting_link] }, knowledge: [ 必须区分已确认结论与待讨论内容, 无人名指向的事项标记为待确认, 不允许编造数据 ], pipeline: [ 第一步清洗转写文本噪音, 第二步抽取事项与责任归属, 第三步校验待办字段完整性, 第四步按模板生成纪要 ], fallback: { on_low_confidence: 保留原始发言片段并提示人工确认, on_tool_failure: 降级输出Markdown文本 }, output_format: markdown }这个骨架里最关键的不是某个具体字段而是它把描述、触发、输入、操作、回退全部拆开了。Agent读取这个文件时能够非常清晰地知道我该不该用这个技能、我需要什么输入、我要按什么顺序做、出了问题怎么办。这里有一个我后来才悟到的点description字段不要写成帮助用户整理会议纪要这种通用描述而要写成路由条件。你会发现很多技能路由错误根源都在于开发者把给用户看的介绍和给Agent看的触发规则混在了一起。前者越软越好后者越硬越好。3.2 注册到运行时如何让Agent发现技能技能文件写完后要让Agent在真实对话中能检索到它需要把它注册到运行时。这一步在不同框架里做法不同但核心逻辑一致技能注册表里记录了编号、版本、可用状态、资源路径运行时在每次请求进来时做一次意图与技能的匹配。我的建议是注册时要明确全局技能和场景技能的区别。比如会议纪要结构化属于全局技能所有对话会话都可以调用而某个项目专属的代码审查技能只在该项目的Agent实例里注册避免在无关场景中被误捞出来。注册之后也不是万事大吉。我会做一次冒烟测试用一个真实场景的请求触发它观察Agent是否在预期节点选择了该技能是否按pipeline顺序执行。如果Agent跳过了某一步或者执行顺序错乱我会优先检查操作层描述是否够显式而不是急着调模型温度。3.3 验证环节用最小评测集拦住回归技能开发完必须配一个最小评测集。不用做得太重我通常每个技能准备五到十组输入覆盖四类情况标准场景、边界场景、缺字段场景、工具失败场景。以会议纪要技能为例我会准备这几种输入标准场景一段有明确结论、有责任归属的会议转写文本预期输出标准结构。边界场景全是闲聊的会议记录预期触发低置信度回退输出未识别到明确待办。缺字段场景输入中没有参会人列表预期能正常生成纪要但附注参会人待补充。工具失败场景模拟在线文档写入接口返回500预期降级输出Markdown文本。评测不是只跑一遍就结束而是要作为技能每次改版后的回归检查。我见过太多人把技能调好后过了两周又改了个描述结果把整个路由弄坏了自己还不知道。有了最小评测集改完直接跑一遍问题五分钟内就能暴露出来。4. 技能库规模上来后的第一道坎匹配、冲突与版本管理如果你只维护三五个技能前面的流程足够应付了。但一旦技能库膨胀到几十个甚至上百个新的问题就会出现技能之间互相抢活、同名不同义、旧版本没下线、路由结果不稳定。这一章我重点讲规模化的管理思路。4.1 意图与技能匹配本质上是多选一还是多选多先说匹配机制。很多Agent框架在命中多个技能时往往只是按相似度排序取最高分但我实际用下来的感受是这种处理方式在技能数量少的时候没问题技能多了以后就会出现最高分技能其实不适合、次高分技能才是正解的情况。更好的思路是给技能匹配加两道闸。第一道是硬过滤触发条件不满足的技能直接排除不参与后续评分。第二道才是软排序在硬过滤之后的候选项里按技能描述的语义相似度、历史调用频率、场景标签等因素综合排序。两道闸的好处是能把能不能用和哪个更合适分开处理避免一个用户随便说了句帮我整理一下就把所有整理类技能全部拉出来打架。我还习惯在软排序阶段加入一个负例字段也就是显式声明哪些情况不要用该技能。比如会议纪要技能里写明不要用于客服对话总结这样即使语义相近路由权重也会被压低。4.2 同名不同义与边界重叠冲突消解的基本策略技能库一大最常见的冲突就是看起来都是做同一件事。比如可能同时存在纪要结构化会议总结讨论结论提取三个技能它们功能高度重叠但字面和内部逻辑各有差异Agent很可能会在不同会话里随机选择导致输出风格不一致。我的处理办法是四条在技能注册前做一次重名与近义扫描凡是意图重叠超过一定阈值的技能必须先合并或者明确差异化定位。给每个技能定义一个主要战场和禁用场景而不是让所有技能都声称自己全能。将技能名称统一命名功能域放前面、动词放中间、场景放后面例如meeting.notes.structure。定期人工巡检技能调用日志找出那些经常同时被召回、但用户最终都不满意的成对技能手动调整它们的触发描述。其中第四点最容易被忽略。依赖模型自动路由永远无法完全消除冲突因为技能描述是静态的而真实用户表达是动态的。人工介入用日志反推哪些技能在互相干扰是规模化维护里最有效的手段。4.3 版本号、弃用与灰度技能也需要发版节奏我们习惯把技能当成代码对待那就必须引入版本管理。我要求每个技能文件里必须有version字段任何修改都必须提升版本号小改升小版本结构性改动升大版本。运行时侧需要支持按版本灰度。做法不复杂注册表里每个技能有多个可用版本默认路由走稳定版同时可以按用户比例切一部分流量到新版本。等新版本运行几天没有明显异常再把默认版本切过去。一旦新版本出现问题可以秒级回滚到旧版。弃用流程也很重要。一个技能被新技能取代后不要直接删掉因为旧会话可能仍在引用。我的做法是将其标记为deprecated并在触发描述中增加本技能已由xxx替代除非用户明确要求旧逻辑否则不要调用。过一段时间确认没有实时流量了再彻底下线。5. 实测中最容易翻车的三个坑以及我的排查顺序技能体系搭起来之后真正的考验在实测。我在多个项目里反复遇到一些相似问题而且每次都能从日志里看到共同的征兆。下面挑三个最典型的坑来讲包含根因、现象和排查顺序。5.1 坑一技能描述写得太软导致频繁误触发现象用户只是正常聊天Agent却莫名其妙调用了某个技能输出的内容风格完全不对。比如用户问你今天有什么计划结果某个日程规划技能被触发给用户硬排了一张时间表。根因技能描述里写了太多帮助用户支持用户这类泛化表述或者把触发关键词写得太过普通。路由模块在进行语义相似度匹配时会把日常闲聊和技能描述里的计划安排等词关联起来。排查顺序先看调用日志确认触发该技能的原始输入是什么。对比输入与技能描述找出是哪个词或哪句话让路由产生了误判。把泛化描述改写为仅当只用于这类强约束表述并在负例字段里显式列出不应触发的情况。重新跑最小评测集尤其是对话场景的用例。我自己的经验是技能描述里每多一个帮助用户误触发的概率就肉眼可见地上升一点。这个说法虽然不够严谨但在实测中方向性很准确。5.2 坑二工具参数校验不足Agent总是传错参数现象技能本身执行到了工具调用环节但接口频繁报参数格式错误或者写入的数据错位严重。比如纪要技能需要传meeting_topic字段Agent却把参会人列表塞了进去。根因技能定义里的输入契约没有说明参数的来源与校验规则Agent在自由生成参数值时缺少确定性依据。尤其是在多个字段含义相近时模型极容易混淆。排查顺序检查工具调用的实际参数日志确认输错的是哪个字段。回到技能定义文件确认该字段是否有明确的提取来源说明。如果来源不明确在操作层补一步显式字段映射例如规定meeting_topic必须取自原始文本第一段或用户单独说明禁止自行概括。可以再补一个参数预检动作调用工具前先做一次必填字段检查缺字段就不发起调用转向回退逻辑。这个坑之所以常见是因为很多人把工具调用接口直接暴露给Agent中间没有任何校验层。我后来养成的习惯是所有对外工具都封装一层参数校验函数宁可多写几十行校验代码也好过让Agent在调用时放飞自我。5.3 坑三长对话里上下文被截断技能执行到一半失忆现象技能前半段执行正常后半段开始丢信息。比如纪要技能前几步还在正常分段到了生成模板时却忘记了原始文本里已经提取过的待办事项开始自己脑补不存在的任务。根因长对话或长文档场景下上下文窗口被截断或压缩Agent丢失了操作层中间步骤的输出。尤其是一些框架默认只保留最近几轮消息如果技能流程需要跨多个步骤传递状态很容易在某个节点断开。排查顺序观察失败节点的缺失内容判断是原始输入丢了还是中间输出丢了。检查运行时上下文管理策略是否对技能执行期间的中间状态做了显式保存。如果是上下文被截断优先改造技能为单次尽量短流程把长流程拆成多次小技能调用每次调用只处理一小块目标。或者在技能操作层增加中间结果缓存步骤把每一步的产物显式写成结构化数据而不是依赖模型记住。我个人的体会是上下文记忆问题是Agent技能设计里的隐形天花板。你无法完全依赖模型上下文去承载整个执行状态必须把状态外置到技能本身的结构里。谁早认识到这一点谁就能少踩一半的坑。5.4 附一个排查检查表下面是我贴在团队文档里的排查检查表实测中直接按顺序过检查项目的常见结果触发描述是否使用硬约束排查误触发描述太软导致日常对话被截流负例字段是否完备排查跨场景误用缺少禁用场景技能之间互相干扰输入契约是否覆盖所有必填排查参数缺失Agent开始自由发挥值不合规工具参数是否有预检逻辑排查调用报错字段错位接口频繁抛异常操作层是否显式传递中间状态排查流程失忆后半段输出与前半段脱节回退逻辑是否真实生效排查硬撑现象明明失败了还输出假成功结果每次技能效果不达预期先过一遍这张表通常能定位到八成以上的问题省得反复调模型参数做无用功。6. 我现在维护技能库的日常指标、复盘与克制最后这部分分享一些我在日常维护中的真实习惯。技术方案讲再多落到每天的执行节奏上其实就几件事看数据、做复盘、管住手。6.1 用三个指标给技能体检我每个技能都盯三个指标不贪多调用成功率、用户返工率、平均执行步数。调用成功率反映的是技能链路是否稳定如果这个数字低于八成我会把重点放在回退逻辑和工具校验上。用户返工率则看用户对输出结果的修改比例如果用户总要把输出改一遍说明知识层和模板设计没对准真实需求。平均执行步数则反映技能是否足够收敛如果一个简单任务被拆成十几步Agent在每一步都有出错机会不如减少步骤、合并操作。这三个指标不是独立看的。我见过一个技能调用成功率很高但用户返工率也极高原因就是它总在成功地产出错误格式内容。所以一定要交叉对比而不是只看单一数字。6.2 每周复盘排在技能变更之前我的固定节奏是每周挑一个时间段翻一遍技能调用日志集中处理三类问题新出现的误触发、排名靠后但频次不低的相关技能、以及新版技能的灰度表现。复盘做完才允许改技能。我的原则是先定位后修改改完必跑评测集。没有定位就改本质上是在赌运气赌赢了你也不知道赢在哪赌输了更是一头雾水。有了复盘日志和评测集的闭环每次修改都能说出为了改善什么、预期是什么、结果如何技能库才会越维护越清晰。6.3 克制才是技能库长期健康的关键技能库维护一段时间后最大的风险不是缺技能而是技能太多太杂。每新增一个技能都意味着路由匹配空间的复杂度整体上升原有的技能可能被新技能干扰。所以我现在的态度是非必要不新增能合并就合并能精简就精简。我会定期问自己三个问题这个技能是否解决了某个其他技能解决不了的问题它的触发场景是否足够明确如果它是为了一次性任务而建的是否可以拆成临时执行流程而不是常驻技能对于常驻技能我的理想状态是每类核心场景只保留一个最优技能。与其让十个半吊子技能互相打架不如把一两个技能打磨到极致。这个思路听起来保守但在我实践过的所有Agent项目里它都显著提升了整体稳定性。另外还有一个很小但很实用的习惯技能文件里一定要写最近一次修改原因和最近一次评测日期。这两个字段不是在给系统看是给人看的。一个月后你回头维护时会发现这两行字比任何注释都管用直接告诉你该往哪看、该担心什么。
