最近社区里聊得最多的就是把大模型从“能聊”变成“能干活”而这一切的落地关键就在agent-skills这四个字上。你可以把技能理解成Agent的操作手册模型本身再聪明如果没法稳定调用工具、读写数据、执行流程它依然只是个聊天机器人。我过去大半年一直在做技能库的设计与落地从最初手写十几个if-else串联工具函数到后来抽象出一套可注册、可编排、可独立测试的技能体系中间踩了不少坑也总结出一套直接能用的打法。这篇文章不聊虚的就讲清楚技能体系到底是什么、怎么拆、怎么写、怎么调以及在真实业务里会踩到哪些坑。agent-skills本质上是一层“能力中间层”它把模型和业务工具解耦开。模型不需要知道每个接口的内部实现只需要知道“什么场景下该调用哪个技能、传什么参数”而技能本身负责把模型的意图翻译成可执行的函数调用再把结果整理成模型能理解的结构化返回。这套设计看着简单真做起来从技能粒度划分到参数Schema设计每一步都有讲究。1. 内容整体设计与思路拆解1.1 为什么Agent需要一套“技能”体系先看一个最原始的场景你让Agent帮忙查天气并安排行程。没有技能体系时你会怎么做大概率是让模型自由发挥希望它自己调用天气接口、日历接口。但实际上模型很可能把城市参数传错、把天气数据里的温度和风速字段搞混、甚至在用户说“下午出门”时不知道应该查14点到18点的降水概率。这不是模型不聪明而是它缺少“操作的规矩”。技能体系的第一个作用是给模型的每次调用立规矩。每个技能都有明确的触发条件、输入参数约束、执行流程和输出格式。模型在决策时看到的不是一堆零散的接口文档而是几张结构清晰的“技能卡片”它只需要做选择题当前任务匹配哪个技能。这大大降低了模型的自由发挥空间也让错误模式从随机变成可预期。第二个作用是让能力可以被沉淀和复用。项目做大了之后你会发现很多操作是跨场景重复出现的比如“解析用户地址”“格式化金额”“检查库存状态”。这些逻辑如果不抽象成技能就会分散在多个Prompt里改一处要动全局。抽象成技能之后它们就变成了独立模块任何新的Agent都可以通过“装载技能”的方式获得这些能力不需要重新写一遍。第三个作用也是我后来才深刻体会到的技能体系是Agent安全性和可观测性的最小抓手。每个技能都是一个受控的入口调用记录可以被审计参数可以被校验执行结果可以被追踪。想让Agent只能做特定范围内的事情你不需要去约束模型的每一句话只需要控制它手上有什么技能、每个技能允许什么参数就够了。1.2 技能粒度怎么定技能粒度是设计阶段最纠结的问题。定太粗一个技能里塞了太多逻辑模型难以准确触发参数组合爆炸定太细技能数量膨胀模型在决策时面对几十个候选选择困难LLM的上下文窗口也吃不消。我实践下来比较稳妥的粒度标准是一个技能最好只对应一个完整的用户意图原子操作。什么叫原子操作就是不需要用户再补充额外信息、不需要依赖另一个技能结果就能完成的最小闭环。“查询天气”算原子操作“安排行程”就不算因为它需要先查天气、再查路线、再排时间这应该是一个工作流Workflow由多个技能编排而成。举个例子。我在一个电商客服Agent里最初设计了“处理售后”这个技能结果模型经常不知道该传order_id还是refund_id内部逻辑又长又绕。后来拆成“查询订单”“提交退款申请”“查询退款进度”三个技能准确率立刻上去了。原因很简单技能内部的判断分支越少模型需要做的决策越少出错的概率自然指数下降。还有一个经验值分享给你如果技能描述需要写超过50个字才能讲清楚触发条件说明粒度多半粗了。技能描述应该像一个精准的电梯演讲几秒钟就能让模型明白我在什么时候该用你。这个标准我几乎用在了所有项目上都很灵。2. 核心细节解析与实操要点2.1 技能声明与参数设计技能声明的格式直接决定了模型能不能读懂你的技能。现在主流Agent框架普遍采用类函数描述的方式一个技能声明包含四部分技能名称、功能描述、参数Schema、执行目标。其中最重要的是参数Schema和功能描述这两个地方写不好后面全盘皆输。先看参数Schema。大模型本身不擅长解读嵌套过深的JSON结构你给它一个包含三层嵌套、类型模糊的参数字段它大概率会传错。我在设计时坚持几条原则尽量使用扁平结构不要超过两层嵌套。所有参数必须声明类型和取值范围比如city要明确是城市中文名而不是经纬度date要明确是YYYY-MM-DD格式。必填参数控制在三个以内超过三个模型漏传的概率大幅上升。如果确实需要很多信息考虑拆成多个技能或者引导用户说清楚后再触发。参数名用业务语义直给的词不要用缩写。比如用delivery_address而不是da用preferred_time而不是pt。功能描述同样大有讲究。很多开发者喜欢把描述写成“该技能用于处理查询天气的需求”实际上这是句废话。好的描述应该包含触发场景、前置条件、执行结果、边界说明。比如天气查询技能的描述至少明确当用户询问某城市当前天气、未来天气预报、气温、降水、风级等气象信息时应调用本技能。用户未指明城市时技能应使用上下文已确认的城市不得自行猜测默认城市。执行后返回城市名、日期、天气现象、最高最低气温、降水概率。注意那句“不得自行猜测默认城市”这类负面约束在描述里特别重要。模型天生倾向于“脑补”你明确划出红线它才能老老实实向你确认。2.2 技能描述与上下文注入的取舍技能描述写得再完善如果全部塞进上下文一次要占掉几千Token。模型上下文窗口有限几十个技能全量注入双方的预算都会爆炸直接在真实场景里会因为互相覆盖而参数串台。我实测过一组对照数据全量注入还是按策略注入同为查询库存与物流信息两个技能后者在复杂场景参数准确性提升了大约两到三成。原因也简单按需注入让模型在每个决策点只看到少量相关技能决策面窄反而更稳。现在我的做法是三段式路由第一段用一次轻量分类请求让模型判断当前请求属于哪个技能域这个请求只注入技能名称和一句话描述开销极小。第二段根据分类结果只加载对应域内两到三个技能的完整描述、参数Schema和示例让模型做具体决策。第三段如果分类置信度低或参数缺失额外注入一次“澄清引导”指令让模型主动向用户追问缺失字段而不是硬着头皮瞎传。这样整体注入量从全量时的几万个Token压缩到每次几千Token响应速度提升非常明显。尤其是做线上业务时每轮调用的延迟直接关系到用户体验这个优化很值。2.3 技能命名和归类规范命名这事看似是小问题实际在模型决策时影响很大。大模型对特征的识别是基于语义空间的相似度如果你的技能名称和别的技能描述相互重叠它在触发时就会徘徊不定。所以命名要遵循一个原则名称本身就能独立表达技能的独特语义。我处理过一个典型的冲撞原来同时存在“查询订单进度”和“查询物流信息”两个技能模型经常在两者之间犹豫甚至出现查订单时返回物流信息的情况。后来把名称改成了“查询订单支付与处理状态”和“查询包裹配送轨迹”并同步调整了描述冲撞立刻缓解。因为新名称在语义边界上划分得更清晰一个管订单状态本身一个管实物配送环节。归类方面建议在技能声明里增加category字段方便做技能域的聚合管理。比如电商域、出行域、营销域这样在做路由决策时可以直接按域去检索效率会高很多。还有一个不易察觉的细节技能名称不要用过于通用的动词比如“查询”“获取”“处理”这类词几乎出现在所有技能里模型区分起来很费劲。尽量用名词性短语把对象在名称里点出来。3. 实操过程与核心环节实现3.1 搭建一个最小技能模块理论说了不少下面来点实际的。我们先从一个“查库存”技能看起这个技能足够小也足够通用。目标是让Agent只凭一句“这个商品还有货吗”就能准确调用技能并拿到结构化的库存结果。# 最小技能模块示例 { name: 商品库存查询, category: 订单_库存, description: 当用户询问指定商品是否有货、当前库存数量、可售状态等情况时触发。触发前提为用户已明确指出商品ID或提供可明确对应商品的链接/名称。不得用猜测的商品ID查询商品ID缺失时返回提示并要求用户补充。, parameters: { type: object, properties: { sku_id: { type: string, description: 商品的SKU ID必须是系统内存在的标识例如SKU20240101 } }, required: [sku_id] }, handler: fetch_stock_by_sku }这段声明描述里我特意加了触发前提并明确“不得用猜测的商品ID查询”。这样模型在用户没说具体商品时就不会自作主张地猜测后乱调而是主动追问。这是经验里最实用的一招把临界命令写在描述里。所谓临界命令是指用户输入不满足触发条件时模型应该怎么办。默认情况下模型可能会强行调用你不如提前替它想好路径。然后是handler字段它指向一个实际的业务函数。这个函数只需要做一件事接收声明里的参数去查数据库返回结果。它不关心上下文也不处理对话逻辑保持纯粹的执行身份后续才能被各种上游复用。接着是结果返回格式我长期用的模板是{ status: ok, data: { sku_id: ..., available: true, stock: 23 } }。用available这类布尔值做第一层摘要data里放明细既能被后续流程读取也可以直接拼装成用户可读的答复。3.2 技能注册与动态装载技能模块只是一个静态声明要让Agent跑起来还需要把它们注册到一个统一管理的技能仓库里。我推荐的模式是每个技能对应一个文件按域建目录启动时全量扫描注册。这样新增技能不需要改任何主流程代码塞个文件进去就能生效。# 技能仓库的注册与装载逻辑伪码示例 SKILL_REGISTRY {} def register_skill(skill_definition): key skill_definition[name] if key in SKILL_REGISTRY: raise DuplicatedSkillError(key) SKILL_REGISTRY[key] skill_definition def load_skills_from_directory(skills_path): for domain_dir in os.listdir(skills_path): for skill_file in glob.glob(f{skills_path}/{domain_dir}/*.json): with open(skill_file) as f: skill_definition json.load(f) skill_definition[category] domain_dir register_skill(skill_definition) def retrieve_skills(query, top_k2): # 基于嵌入检索或简单关键词匹配召回最相关的技能 scored [] for skill in SKILL_REGISTRY.values(): score compute_semantic_similarity(query, skill[description]) scored.append((score, skill)) scored.sort(keylambda x: x[0], reverseTrue) return [skill for _, skill in scored[:top_k]]动态装载的另一个好处是热更新。线上业务往往需要临时下线某个出问题的技能或者灰度测试一个新技能。在仓库模式下只需要把对应文件改名或标记disabled在下次装载时就不再生效。早期我把技能写在Prompt模板里每次调整都要重新发布整个Agent服务一次迭代半小时起步。改成独立文件注册后改个描述、换个函数五分钟就能生效开发和联调效率完全是两个量级。3.3 技能执行的完整链路有了技能声明和装载机制还要打通从用户请求到技能执行的完整链路。我的链路分五步每一步都有明确的数据约定第一步用户输入标准化。把用户原始语句统一转成{ query: ..., history: [...] }结构。第二步技能路由。用第一次模型调用或规则匹配选出最相关的技能域并加载技能描述。第三步参数提取。这一步是模型调用核心是把用户语句映射成技能参数JSON。第四步参数校验与执行。校验不通过就返回错误码由框架决定是追问还是走兜底校验通过则调用handler拿到结构化结果。第五步结果转述。把结构化结果交给模型用口语化表述回复用户。这里最容易出问题的是第三步。参数提取时模型容易受聊天历史干扰比如用户之前说过一个城市现在问别的事模型提取参数时可能错误带入上一次的实体。我在做这一步时会在提取Prompt里显式加一句仅基于当前用户消息提取参数不要在历史对话中推测信息。同时提取结果必须输出严格的JSON任何多余的文字都会导致解析失败所以我会在解析层加兜底如果解析失败就启用一个基于规则的实体识别模块作为降级方案保证链路不至于中断。4. 常见问题与排查技巧实录4.1 模型“想不起来”用技能你明明把技能写得清清楚楚但模型就是在该调用的时候不调用这几乎每个做Agent开发的人都遇到过。排查时不要直接怀疑模型能力先看看你的检索环节召回了什么。早期的调试经历里我遇到最多的情况是top_k设置太小真正相关的技能没有被召回或者候选技能语义太接近模型在两者之间徘徊之后干脆不调用了。给一个实用经验检索结果返回给模型时不仅给技能描述还要给每个技能附上一到两个典型触发例句。比如库存技能附带“这个还有货吗”“现在下单几天能发”这样的例句模型看到例句后能更快理解这个技能对应什么样的用户表达触发率明显提升。这个技巧实践下来效果很显著属于低成本高收益的优化方向。还有一种情况是上下文污染。如果历史消息里有大量无关的对话模型容易被带偏忘了手边有工具可用。我的做法是在每次路由决策前先裁剪历史只保留与当前请求相关的对话片段并把“你有以下技能可用”这句话放在上下文最靠后的位置。让指令靠近上下文尾部模型通常更容易注意到同时直接削减不必要的历史噪声。还有一个偏门但有效的思路如果模型始终不用某技能不妨检查一下技能名称本身是否过于抽象。我遇到过“获取用户偏好画像”这种命名语义空间太大不够直观改成“读取用户历史偏好标签”并补充具体标签示例后调用率一下子上来了。越是抽象的名字模型越不知道它到底能干什么宁可名字长一点也要把对象和动作说清楚好让模型明白什么场景该参考它。4.2 参数幻觉与非法取值模型传了不该传的值这是比“不调用”更头疼的问题。比如商品SKU明明不存在模型还能编一个出来日期格式不符合业务预期把“价格”字段传成了字符串。要解决这个问题单一靠Prompt描述远远不够必须做三层防御。第一层是Schema约束在参数Schema里定义好类型和枚举值凡是不符合的直接过不了基础校验。第二层是业务校验函数比如SKU是否真实存在于商品库中日期是否在有效期内这些要交给实际代码去判断不能依赖模型自觉。第三层是语义兜底如果校验失败框架自动触发一次澄清追问让用户补充或确认而不是把错误参数一路传递下去。我特别想强调第二层。模型产生幻觉是概率性的你无法通过调Prompt让它彻底不犯。但从“不可信”变为“不可执行”框架层面就能拦截大批坏数据既避免脏数据污染后续业务也保护了业务流程不被带偏。执行器里我通常还会加一个超时和重试机制超时后返回一个明确的超时错误避免模型把旧的失败记录当作成功结果继续向下游传递。4.3 技能冲突与优先级处理当技能数量超过三十个冲突几乎不可避免。常见冲突是不同域的两个技能描述里都提到了“订单”模型分不清该调哪个。这种情况下不要急着调整描述先检查是不是技能粒度过粗或者复用逻辑没抽象干净必要时通过业务规则做一层路由偏好。我习惯在技能定义里加一个可选的priority字段规定在触发器重叠时优先使用哪个技能。但这个手段只能解决已知冲突解决不了模型自己判断时左右摇摆的问题。更干净的做法是把容易混淆的技能做一次归并。比如把“查询订单支付与处理状态”和“查询包裹配送轨迹”统一到一个“订单全链路查询”技能下通过内部的子步骤判断用户真正想看什么。这样表面上少了一个技能实际上因为分工清晰整体稳定性和准确率反而更高。另一个常见冲突来自共用参数的表达不一致。比如一个技能用order_id另一个技能用order_sn模型即使识别出该用订单查询也无法确认到底传哪个字段。统一术语表在技能体系里是必需品所有跨技能引用的概念必须叫同一个名字。我在项目初期吃过这个亏两个域各自开发等到联调时才发现参数名对不上后来专门做了一次数据字典的统一这个问题才算彻底解决。5. 更多经验与扩展方向5.1 技能的一次性验证与回归测试技能体系做得越成熟就越需要一个自动化测试机制来兜底。每次新加或修改技能都不能只靠人工抽几条数据试一下就上线。我采用的模式是把历史真实请求与期望调用技能组成回归集每次改动后跑一遍这些用例把“应该触发哪个技能、提取哪些参数、返回什么格式”作为断言标准智能体实际执行结果与标准比对。这套回归测试机制在长期迭代中价值非常大。因为技能的改动能引起几十个既有场景的连锁反应有时候只是改了一句描述某个边缘case的触发路径就完全变了。没有回归测试傍身你根本不敢动老技能。而有了它改起来心里就有底测完再上线。还有一个实操细节每次跑回归测试时把模型回答里关于技能选择和参数提取的中间步骤记录下来可以留存成一份决策轨迹。模型出错时这份轨迹能直观地看到它是如何走到错误结果的是检索环节遗漏了技能描述还是参数提取时被历史噪声干扰大部分问题都能一眼定位到具体环节而不是对着黑盒反复猜原因。5.2 技能的可观测性与数据回流技能上线之后日志里暴露出的数据要持续反哺优化。我比较关注四个指标触发准确率、参数提取通过率、执行成功率、兜底触发次数。前两个直接反映模型对技能描述和Schema的理解程度第三个反映业务链路稳定性第四个则能暴露出技能覆盖的盲区。举一个真实例子。某个客服Agent的退款技能上线后执行成功率稳定但触发准确率偏低。查日志发现用户说“退货”时模型经常触发成“退款”把语义上相近的两种行为搞混了。后来在技能描述里分别补充了最典型的用户表达并给“退货”技能加了触发优先级再跑回归测试触发准确率直接上了一个台阶。如果没有这类数据回流机制这个问题可能要在线上潜伏好久而单靠日常人工体验根本注意不到触发准确率的细微变化。技能库的数据回流还有一个用途就是反哺检索模型。凡是发生过错误触发或未触发的样本都值得人工复核后放进检索训练集。你的召回向量会越用越准技能路由的自然语言匹配能力也会随之持续变强形成一个逐渐积累的收益。5.3 从技能到工作流单个技能解决的是“怎么执行一个动作”但真实的业务场景往往是多个动作的连续编排。比如“处理售后”需要一个完整的工作流查询订单、判断售后类型、生成处理方案、提交审核、通知用户。这五个环节由五个技能完成但它们之间的衔接顺序和状态流转已经超出了单个技能的职责范围。我的做法是引入轻量级的工作流编排层把技能当作工作流里的节点。每个节点定义输入来源和输出去向上一个技能的结构化结果自动映射为下一个技能的参数。这样既保证了技能可以被单独复用又不至于让一个技能承担过多逻辑。你现在设计技能时不用一下子想得太深但当技能数量到达一定规模工作流编排几乎必然是你下一步的演进方向。这里节奏最好踩得稳一点先把每个技能守住把调用链跑通再考虑上工作流。我在实际操作中最大的感受是工作流如果建立在基础不够稳的技能体系上调试成本会成倍上升所以基础打磨值得多花时间。最后再分享一个调整节奏的小技巧当你把一套技能写完之后不妨试着找个完全不懂背后系统的朋友试用一下你的Agent看用户用日常口语提出需求时系统是否能准确触发对应技能。很多技能设计上的“死角”只有换了表达方式才能暴露出来。这种体验式测试做上几轮你打磨技能的方向感会清晰很多。