如果你接触过AI Agent开发一定遇到过这种情况模型本身能力很强但让它去查天气、操作数据库、调用内部API的时候表现却像第一次上班的新人——要么答非所问要么干脆说我没有这个功能。问题往往不在模型而在你给它配备的技能没有设计好。agent-skills这个概念说的就是这件事给Agent构建一套可复用、可编排、可演进的能力单元让模型知道在什么场景下用什么工具、以什么格式传参、期望什么结果。这篇内容当作一次完整的项目复盘我会把技能定义、注册机制、路由策略、调试方法和避坑经验都拆开讲。这套东西适合谁来参考如果你正在做Agent类应用比如智能客服、自动化运维助手、企业内部知识问答机器人或者单纯想把LLM接到真实业务系统里那这篇文章正好对路。如果你对Prompt Engineering已经很熟想进一步解决模型知道该做什么但做不了的问题也可以从中找到切入思路。1. skills不是工具列表它是一套完整的能力契约很多人第一次上手给Agent配技能做法很简单写一堆函数把函数名和描述塞进System Prompt然后等着模型自己选。真实跑起来就会发现技能一多模型就开始乱——该调A的时候调了B参数传错不说面对两个功能相近的技能时甚至直接忽略可用的那个。这里有个关键认知skills不应该被设计成工具列表而应该被设计成一组能力契约。1.1 从一次失败的查天气说起我最早做的一个Demo是让Agent帮忙查天气并给出出行建议。我当时定义了两个Python函数一个调天气API一个把天气数据转成出行文案。System Prompt里写得很详细你是助手你可以调用get_weather获取天气可以调用generate_travel_advice生成建议。测试的时候模型表现很迷惑它常常只调用get_weather然后自己编一段出门记得带伞的话完全无视generate_travel_advice的存在。更烦的是有时候它为了看起来合理会虚构一个城市代码传进去把API搞崩溃。问题出在哪里我给的只是一个函数列表没有告诉模型这个函数在什么条件下应该被调用它的输入输出和整个任务流程有什么关系如果多个函数配合工作执行的先后顺序是什么1.2 技能契约的三层结构后来我把每一个skill的定义重构成三层结构效果立刻不一样第一层是元数据层主要负责描述技能的用途、适用场景、调用边界。注意这里不要再写当你需要天气信息时这种含糊话要写具体的前置条件仅当用户明确询问某城市今天或未来的天气情况时本技能才应当被激活。若用户只是闲聊天气感受禁止调用。这类约束性描述对模型的作用比想象中大得多。第二层是输入输出契约层必须严格定义参数结构。不要直接复用函数签名的默认值要为每个参数写清楚取值范围、格式、是否必填最好直接给出一个expectation示例。我在实际项目里会在描述里加一句参数中对城市名的表达必须与城市代码表严格一致不允许自行推断缩写这句看着像废话但能挡住大量幻觉性参数错误。第三层是执行流程层告诉模型这个技能被调用后会怎样影响环境代价是什么。比如该技能会触发短信发送无法撤销该技能返回的数据在30分钟内有效过期必须重新获取。让模型具备基本的风险评估意识它才不会把一个重操作技能随手调出来。我把这套实践放在agent-skills项目里的核心位置技能数量一旦超过5个单纯依赖自然语言描述维持路由准确性就会迅速失效。真正可靠的方案是给每个技能做结构化的能力契约让模型判断的不是这个函数像不像而是当前上下文是否完全符合这个技能的前提条件。2. 技能定义与注册如何让技能被模型看得见、分得清、用得好定义好契约之后下一步就是落地——这些技能要以什么形式被模型感知目前主流做法有Function Calling、JSON Schema描述、或自定义的工具调用协议。我以自己的实际项目为例说一下怎么把技能注册到Agent运行时中。2.1 技能描述书写的实际案例我项目里有个内部工单查询技能第一版描述写的是查询工单状态参数为工单编号。运行一周后发现模型经常把工单编号和订单编号搞混导致查询结果张冠李戴。改成完整描述后代码大致长这样skill_config { name: query_ticket_status, description: ( 查询内部工单的当前处理状态。 适用条件用户明确提供了以TK开头的工单编号并期望获得该工单的进度、 处理人或当前状态节点。 禁止条件用户提供的是订单号、物流单号、流水号等其他编码必须先引导用户 确认编号类型不得尝试用其他类型编号查询。 ), parameters: { type: object, properties: { ticket_id: { type: string, description: 完整的工单编号形如TK1234567890必须包含TK前缀, pattern: ^TK[0-9]{10}$ }, need_history: { type: boolean, description: 是否需要返回完整的流转历史默认为false仅返回最新状态, default: False } }, required: [ticket_id] } }这里有个我曾经忽略的细节description字段里禁止条件这一段比适用条件更管用。模型对不该做什么的遵守度远高于对应该做什么的理解度。这可能跟训练数据的对齐方式有关但从实测效果来看显式写明禁止条件能让误调用率下降不少。2.2 技能注册表与冲突消解技能数量一多光靠单条描述已经不够了。我会做一张技能注册表把每个技能的核心信息汇总起来便于运行时做初筛和冲突消解。技能注册表大概长这样技能名所属域数据代价副作用调用优先级query_ticket_status工单域低无高create_ticket工单域中创建新记录中send_sms_notify通知域低触发短信计费低batch_export_report报表域高后台计算耗时低这张表真正的作用不是给模型看而是给运行时的路由逻辑用。当模型返回的技能调用请求与当前上下文冲突时——比如用户只是问问有哪些工单模型却调了batch_export_report——路由层可以直接拦截。拦截规则是硬编码的不依赖模型判断。这一步我称之为安全兜底。另一个必须提到的问题是技能名冲突。多个技能不能起相似的名字否则模型的语义区分度会急剧下降。比如get_ticket_list和query_ticket_status这种描述再清楚模型也可能混淆。我后来统一了命名规范动词_对象_范围保证同一域内的技能名彼此有足够区分度。2.3 注册后的首轮验证清单技能注册完毕不要急着上线。我在agent-skills实践里沉淀了一份验证清单用最直接的自然语言提问模型能否正确命中技能用模糊的、缺省参数的提问模型能否主动澄清而不是瞎猜用与技能无关的问题模型能否明确拒绝调用用两个功能相近技能的边界问题模型能否正确区分参数校验失败时Agent能否给出可理解的纠错提示这份清单的意图很明显技能注册的核心目标是让模型快速命中、准确传参、克制调用。上线前的验证必须覆盖不该调用的场景因为这类错误比该调用没调用危害更大——至少用户能看出来Agent不会做某件事而不是看着它把错事做得有模有样。3. 技能路由与选择策略从模型自由发挥到工程可控定义好技能以后下一个问题来了模型实际执行的时候到底怎么决定用哪个技能是不是让我刚才说的那段描述自动生效答案是描述很重要但不够。为了让Agent在复杂的真实对话中稳定选择技能我加了几个工程层面的控制策略。3.1 系统级预筛选在模型调用前做一个硬性预筛选。具体做法是把用户当前输入先过一次轻量分类器判断意图落在哪个域——工单域、报表域、通知域还是纯闲聊。如果落在某个域就把该域相关的技能描述拼进System Prompt如果纯闲聊一个技能描述都不放。这个做法的好处是技能描述不再全部塞给模型减轻了上下文负担也降低了跨域误调用的概率。模型每次看到的选择范围变小路由准确率自然上升。你可以想象成以前给模型看一百个工具的说明书让它挑一个现在先按部门归类只把相关部门的说明书递过去模型挑错的概率自然小很多。3.2 意图置信度与二次确认预筛选也解决不了一切问题。当用户输入比较模糊时比如帮我处理一下这个订单这种表达同时涉及工单查询、订单修改、物流跟踪等多个技能的可能模型的初次路由置信度往往不高。我的策略是设置一个置信度阈值。路由模块会给每个候选技能打分如果最高分和次高分差距不大就触发澄清追问您是想查工单进度还是要修改订单一次澄清的成本很低但能避免一连串后续操作的连锁错误。这里有个经验澄清问题要给出选项不要开放式提问。让用户从预设选项中选比让用户自己组织语言快得多而且选项本身就是一种提示能帮用户理解Agent能干什么。3.3 技能执行的观测与回滚调用了技能不代表事情结束还需要观测执行结果是否合理。有些技能副作用不可逆比如发短信、创建工单、执行转账。对这种重操作技能我会在路由层设一个额外的确认门槛模型必须把将要执行的完整动作、参数、目标对象组织成一段可读摘要经用户确认后才真正执行。如果技能执行过程中发现异常——接口超时、返回数据格式不合法——要保证Agent能体面地退出而不是硬着头皮把错误结果当作正常回答呈现给用户。我在Agent运行时里加了一个约定任何技能返回error状态时模型必须明确告知用户操作未完成并说明原因禁止用猜测性语言掩饰。还有一点关于回滚的经验有些技能虽然副作用不可逆但可以设计反向操作。比如发送短信之后支持发送一条撤销说明短信创建工单之后支持关闭工单。把这些反向技能也注册进技能库并建立正向技能和反向技能的关联关系。这样万一判断失误还有补救机会不至于直接造成事故。4. 实战中的坑我在agent-skills项目里踩过的十类问题这一节分享真实跑项目时踩过的坑我会把每个问题都拆成表象、根因、解法三部分。这些经验不是从文档里抄来的是实打实调试出来的。4.1 参数幻觉模型编造不存在的合法参数最常见的坑就是模型传出一个我从未定义过的参数比如我在参数里定义了ticket_id和need_history模型却多传了一个user_role进来。Debug日志一看发现模型在脑补我的接口可能需要权限参数。根因是System Prompt里职权边界模糊——它不确定自己有什么信息就开始编。解决方式很直接在技能描述里显式写一句本技能仅接收已定义的参数任何未定义的额外参数将被忽略。同时在代码层做严格的参数白名单校验直接过滤掉未知字段。4.2 模型把回复当成技能调用结果另一个高频问题技能明明返回了JSON数据但模型不直接转述反而自己发挥一段根据查询结果我认为……。当返回数据本身很明确时这种发挥就变成了信息失真。根因在于对模型角色的设定错误。我当时把Agent的角色设定成智能助手语气上鼓励分析它就忍不住评论。解法是把任务的输出规范写清楚当技能返回结构化数据时你的回答必须严格基于该数据不得自行补充或推断数据中不存在的信息。若数据无法回答用户问题直接回答该信息暂未获取到。4.3 循环调用Agent在技能之间绕圈还有一种画面模型调query_ticket_status发现工单已关闭于是又调create_ticket表示要重新开单接着又调batch_export_report想导出历史记录比比看。在无人工干预的情况下这种调用链可能无限延长。根因是路由层缺少调用次数与逻辑循环的检测。我的处理措施比较工程化限制单轮对话中技能调用的最大次数例如5次如果同一技能连续被调用2次以上且用户没有新增指令自动终止并询问用户意图在Prompt层面加入调用的每个技能都必须对用户当前问题提供新的可回复信息若没有新增价值应当结束调用并直接回复。这招治住了多数无意义循环。4.4 上下文遗忘导致的重参数传递Agent要在多轮对话中保持状态是比较难的一件事。用户第一轮说帮我查一下工单TK123第二轮说顺便看下历史模型有时不再把ticket_id传进去反而直接问用户请问要查哪个工单。这类问题的根因在于没有把对话状态持久化到每一次技能调用中。解法是在Agent外层维护一个关键状态记忆组件一旦某技能成功提取了关键实体就把该实体值缓存起来在下一次技能调用时自动注入参数而不依赖模型自己记住。这属于工程层补位把模型不太擅长的事用代码搞定。4.5 描述过长的反效果我也试过把技能描述写得非常详细一个技能写五六百字事无巨细地介绍。结果模型反而抓不住重点路由准确率下降。后来我理解了模型的注意力资源有限描述越长给该描述分配的权重越分散。现在的做法是描述控制在150字以内核心信息前置。把适用条件和禁止条件放在开头两句剩下的才是参数说明。如果技能背后有复杂逻辑把详细说明放到技能执行的说明书文档里不占Prompt空间。4.6 测试时过拟合于真实场景我在测试阶段犯过一个错误就是用真实场景的模板测试太多导致模型对模板说法响应极佳但换个说法效果骤降。比如用户说工单啥情况了模型能正确处理但用户说我那个单子现在卡在哪儿了模型就犹豫了。根因是测试数据多样性不够。现在我的测试集里强制加入三类变体口语化说法、省略关键实体的说法、包含冗余信息的说法。确保模型在噪音环境下也能正确命中技能。4.7 并行调用时的依赖冲突有些技能之间是存在依赖关系的比如先要查权限才能创建工单。模型如果并行发起两个调用可能会因为权限未确认导致创建失败。虽然LLM可以一次返回多个函数调用但我在设计技能时要求标明depends_on依赖列表路由层遇到依赖关系时会自动改为顺序执行。这条经验对小规模的Demo可能不重要但一旦技能数量上到几十个并行依赖的正确性就会显著影响稳定性。4.8 日志缺失导致的问题排查困难没有结构化的技能调用日志排查问题会非常痛苦。每次模型调用技能后我至少记录时间戳、会话ID、触发用户原始输入、技能名、完整参数、技能返回码、返回数据摘要、模型最终回答。这些日志不只是给程序排查用的也是给Prompt调优提供数据的——回看哪些误调用是描述不清导致的比瞎猜管用得多。4.9 不做A/B测试就上线技能描述微调后想象中是好了一点但实际效果如何不能凭感觉。我养成的习惯是每次调整描述都准备一组固定测试集跑一遍新旧版本的对比。记录命中率、参数正确率、误调用率三个指标。没有对比就没有伤害A/B测试能帮你筛掉大多数看起来更好但实际更差的改动。4.10 忽略技能执行的性能代价有些技能看起来配置简单实际执行要消耗大量算力或时间。比如batch_export_report要跑几分钟的后台计算如果模型在一个即时对话里调用了它用户体验会非常糟糕。我的解法是给技能标记异步执行属性对于耗时超过阈值的高代价技能先返回一个任务已受理的中间状态后台跑完后通过后续通知补充结果。不能让用户对着转圈等待发呆。5. 从单技能到技能库组织、治理与演进当技能数量超过某个量级后靠一个一个配置已经不太现实需要把技能资产沉淀成一个可持续演进的技能库。这一节聊组织方式与治理思路。5.1 技能分类与命名空间设计我在agent-skills项目里把技能按域划分ticket域、report域、notification域、user域。每个域有独立的前缀和目录便于检索和权限管理。更重要的是分域之后Prompt组装模块可以按域加载技能描述避免全量加载造成的注意力稀释。每个技能字段里还增加了version字段。技能背后的接口升级后不要直接改旧技能而是新增一个版本号。这样一方面支持灰度切换另一方面可以快速回滚。版本管理这事儿看着繁琐真正出过一两次事故之后就会觉得值得。5.2 技能质量评估与淘汰机制技能库不是只增不减的。我每两周会做一次技能使用分析调用次数、命中率、误调率、用户反馈。如果一个技能连续一段时间调用量极低且与核心场景无关就考虑下线或合入其他技能。技能库的规模一旦失控路由准确率会反向下降。技能上线前还要统一过一遍最小可用描述检查删掉所有冗余修饰词看描述是否仍然清晰。很多技能描述中强大、高效、智能这类词价值不大反而削弱了关键信息的权重。我现在的描述风格偏清单式是可以直接刷到重点的。5.3 来自反馈闭环的持续优化最后补充一个认知技能库的质量上限不取决于定义技巧而取决于反馈闭环的速度。每次模型误调用或参数错误都要有渠道回收到技能维护者那里。否则同一个错误会反复出现用户失去耐心技能库也难以前进。我做的闭环很简单运行时把每次调用行为打分命中是否准确、参数是否合规、用户是否纠错异常行为自动进入待优化池。每周我只需要优先进化池中的高频错误技能迭代节奏就会稳很多。这种方式比纯靠Prompt刷感觉更可持续。6. 实操总结与下一步建议最后分享几条我实操下来最有价值的体会。第一技能的数量和复杂度要与业务场景匹配。给只有5个用例的Demo配上50个skill效果一定比10个skill更差。克制是技能设计里最重要的能力。第二任何Prompt层面的优化都不如工程层的安全兜底可靠。技能描述的合理设置能提升模型的正确行为概率但要防止灾难性错误仍需在路由层做参数白名单、次数上限、重操作确认等硬控制。第三开始做agent-skills之前建议先想清楚一个场景你的Agent最重要、最常用的一件事是什么先把这一个技能做到极致再扩展到其他场景。早期技能过多只会拖垮路由准确率让Agent看起来什么都会但什么都做不靠谱。如果你想试试可以按我之前提到的三层契约结构先定义3个技能跑一周记录误调用率再逐步加量。对比一下有契约和无契约时的表现差异会比我在这里写一千字的论证更有说服力。我在实际开发中还有一个体会技能的维护过程是没有终点的。模型版本、接口结构、用户语言习惯都会不断变化今天表现良好的技能库下个月可能就开始出现奇怪的误调用。留出持续调优的时间和机制比追求一劳永逸的完美配置更有意义。这也是agent-skills这套做法的核心价值——它不是一次性代码资产而是一套让Agent持续变聪明的基础设施。