“agent-skills”这个词最近在圈子里出现的频率越来越高但说实话我看不少团队把它理解窄了。有人觉得这就是给Agent多挂几个API接口有人觉得就是把提示词写成文件。真正把Agent技能体系搭起来之后你才会发现它本质上是把模型能力工程化的一套方法论——怎么定义技能边界、怎么写描述让模型稳定路由、怎么管理版本和冲突、出了问题怎么排。这篇文章我就拿自己最近在做的技能库项目为底子把这套东西从头到尾拆开讲。1. 为什么需要“Agent Skills”从工具调用到技能编排的演进1.1 工具与技能的本质区别先说一个最常见的误区很多人觉得Tool和Skill是同一个东西换了个名字这其实差得很远。一个工具Tool通常就是一个确定性的函数接口输入JSON输出JSON执行逻辑写死在代码里。比如查天气、发邮件、调数据库这些都是工具。工具本身不包含“决策”也不包含“流程编排”它就是个原子操作。而一个技能Skill是一整套可复用的能力单元它通常包含这样几个层次触发条件什么情况下这个技能该被激活内部步骤技能执行时需要调用的一个或多个工具以及这些工具之间的先后顺序决策逻辑在什么分支下走什么路径这可能是代码写的也可能是让模型做的输出协议技能执行结束后向上层返回什么结构化结果边界声明这个技能明确不处理什么、什么情况要放弃。拿换轮胎来打比方工具就是一把扳手、一个千斤顶你给它一个螺栓它负责拧动技能是“换轮胎”整套动作——判断胎压、顶起车辆、拆螺丝、换新胎、拧紧、放下千斤顶、复测胎压。一个技能里要调多个工具并且要按一定的顺序和条件来调。为什么要做这层区分因为在真实的Agent系统里模型并不擅长在每一个细小的步骤上都做决策。如果每一步都要让模型从几百个工具里选一个出错的概率会随着工具数量指数上升。把高频、稳定的操作路径封装成技能模型只需要在“技能”这个粒度上做一次路由决策复杂度一下子就降下来了。1.2 技能编排要解决的核心痛点我做完一期技能库改造之后整理了三个最想解决的问题这三个也基本覆盖了大部分团队的共性需求第一降低模型在复杂任务中的决策负担。一个Agent面对的任务往往有十几个子步骤。如果全部平铺成工具列表模型不仅要理解每个工具的语义还要现场推理出步骤顺序。技能把顺序和分支提前固化等于给了模型一份“标准作业流程”它只需要判断“现在该执行哪个SOP”而不是现场发明SOP。第二提高子任务的复用率。同一个业务里的用户身份查询、订单状态同步、数据脱敏逻辑往往会被多个Agent用到。把这些做成独立技能之后客服Agent能用运营分析Agent也能用不需要每个Agent各自实现一遍。版本更新也只需要改一处。第三让代码逻辑与模型能力的边界更清晰。这可能是最容易被忽略但最重要的一点。没有技能层的时候模型一会儿负责逻辑推理一会儿负责调用代码一会儿又要处理数据格式边界一模糊bug就满天飞。有了技能层之后凡是确定性的、有标准流程的一律下沉到技能里让模型只做它擅长的事理解意图、判断路由、处理模糊信息。1.3 什么时候该引入技能层并不是所有项目都需要一上来就搞技能库。我见过不少团队犯的一个错误就是Agent还只有两三个工具的时候就开始设计复杂的技能注册中心结果维护成本比收益还高。我的判断标准比较简单满足下面任一条就可以考虑引入任务可以被拆成多个稳定的操作路径而且这些路径会反复出现同一个能力块有多个Agent要在各自场景里用到工具数量超过20个模型路由准确率开始明显下降你需要对Agent的执行过程做审计但现在的调用链太碎没法追溯。反过来如果你的Agent只是做一个简单的问答、一次单工具调用或者整个系统还在验证阶段先别急着造技能框架。过早抽象是最大的隐性成本等需求逼到那个份上了再抽层也完全来得及。2. Agent Skill的技术骨架协议、上下文与运行机制2.1 技能的最小可用定义一个能稳定运行的技能光有代码是不够的。我经过几个版本的迭代沉淀下来一套最小可用的定义结构缺一样都觉得别扭。组成部分作用举例技能ID全局唯一的标识符用于注册和路由user.profile.lookup名称人类可读的名字也用于模型理解用户画像查询描述对触发条件、能力、边界的自然语言描述当需要查询用户基础资料时使用不处理订单信息输入Schema定义调用参数的结构、类型、必填项user_id: string, required执行逻辑实际的代码或工作流可以调用多个工具先查缓存再回源DB最后脱敏输出Schema定义返回结果的结构{name, age, memberLevel}校验规则对输入输出做合法性检查邮箱格式、日期范围、敏感字段下面是一个最小技能定义的示例我习惯用JSON做注册元数据用Python写执行逻辑{ skill_id: order.status.query, name: 订单状态查询, description: 当需要查询订单当前状态、物流进度或预计送达时间时使用。仅支持查询已付款订单不支持退款或售后流程。, input_schema: { order_id: {type: string, required: true}, include_tracking: {type: boolean, required: false, default: false} }, output_schema: { order_id: {type: string}, status: {type: string}, eta: {type: string, nullable: true} }, timeout_ms: 3000, retry: {max_attempts: 2, backoff: linear} }执行逻辑部分我会保持一个统一的函数签名async def execute(inputs: dict, deps: SkillDeps) - SkillResult: order_id inputs[order_id] include_tracking inputs.get(include_tracking, False) # 先查缓存 cached await deps.cache.get(forder:{order_id}) if cached: return SkillResult.ok(cached) # 回源订单服务 order await deps.order_client.fetch(order_id) if order is None: return SkillResult.error(ORDER_NOT_FOUND, 订单不存在) # 敏感字段脱敏 order mask_phone(order) # 写入缓存 await deps.cache.set(forder:{order_id}, order, expire60) return SkillResult.ok(order)这层设计里有几个细节值得展开说说。接口的进出都是结构化数据这个非常关键。技能内部可以自己写逻辑、调多个工具但对外暴露的输入输出必须是干净的JSON。为什么因为Agent主流程要靠这些字段来继续后续推理如果返回一个半格式化文本或者带了一堆调试日志模型很容易被带偏。执行函数带上一个deps参数把所有外部依赖都通过依赖注入传进来。这样做的好处是测试的时候可以非常方便地替换成mock实现不需要真的连数据库。返回结果统一包装成SkillResult要么ok(payload)要么error(code, message)。这样上层Agent拿到结构化错误码后可以精准判断要不要重试、要不要换别的技能而不是靠猜。2.2 上下文窗口的管理策略技能与上下文之间的关系是我在这个项目里踩坑最深的地方。初期我天真地以为“技能”就应该把全部相关的说明书、规则、示例都塞进上下文让模型充分理解。结果就是每个技能占据大几千tokenAgent一次的上下文很快被打满到后面真正需要推理的地方反而缩手缩脚。后来我总结出一套上下文预算策略核心原则就一句话把可执行逻辑从上下文中搬出去上下文里只放路由需要的信息。一个技能真正要放进上下文的东西其实只有三样技能名称和一行描述输入参数的关键说明使用时的注意事项和禁止事项。至于这个技能内部怎么实现、调用了哪些工具、处理逻辑是什么一律不进上下文。对模型来说这些是实现细节它看了不仅没用还会干扰决策。我现在的技能列表项会精简成这样order.status.query: 查询订单状态、物流进度和预计送达时间。 仅支持已付款订单不处理退款售后。 参数order_id必填、include_tracking可选是否返回物流明细。这行文本全加起来不到40个token。一个Agent哪怕挂了50个技能技能列表总token占用也才2000出头给后续的对话历史和内部推理留出了充足空间。当然也有不得不把大段外部知识放进来的场景。比如一个技能要处理几十种商品类目每种类目的处理规则不同这显然没法全塞进上下文。我的做法是技能描述里只写“支持查全量类目规则”真正执行的时候用代码去检索规则库把命中那条规则提取出来后在技能内部处理。这样模型每次只需要看到跟当前请求相关的那一小段规则而不是全量规则。另外一个容易被忽视的问题技能执行过程中产生的中间状态也会污染上下文。如果你在技能的返回结果里悄悄夹带了内部日志、调试输出或者干脆把技能的执行步骤也作为消息回传给模型那你就会看到模型的后续行为变得非常古怪。它可能在毫无必要的情况下反复提到你的内部日志内容。所以技能对外输出必须严格过滤只保留输出Schema里定义的字段。2.3 技能的调用与路由机制技能注册好了关键在于模型怎么知道该调哪个技能。目前我实测下来有三种主流的路由机制各自适用场景不一样纯模型路由把技能列表放进提示词让模型根据用户请求自动选择技能。优点是灵活、能处理没预定义的组合请求缺点是模型会“幻觉技能”尤其是技能数量多、描述相似的时候选错概率明显上升。我做过一次统计超过30个技能后纯模型路由的准确率会掉到85%以下。规则路由用关键词匹配、意图分类器或正则来绑定技能。优点是确定性强同一个请求每次路由结果都一样缺点是僵化用户换个说法可能就路由不到而且需要维护一套路由规则更新成本高。语义检索路由把用户请求向量化和技能描述的向量做相似度匹配取Top-k后交给模型做最终选择。这个折中方案的实战效果最好既能照顾语义模糊的表达又通过缩小候选范围降低了模型误选概率。我目前在生产环境用的就是这个方案。下面是我封装的一个简化版语义路由逻辑from sentence_transformers import SentenceTransformer from sklearn.metrics.pairwise import cosine_similarity import numpy as np model SentenceTransformer(sentence-embedding-model) class SkillRouter: def __init__(self, skills): self.skills skills self.vectors model.encode([s[description] for s in skills]) async def route(self, user_request: str, top_k: int 5): req_vec model.encode([user_request]) scores cosine_similarity(req_vec, self.vectors)[0] top_indices np.argsort(scores)[::-1][:top_k] candidates [ {skill_id: self.skills[i][skill_id], description: self.skills[i][description], score: float(scores[i])} for i in top_indices if scores[i] 0.5 ] return candidates这个路由的阈值得仔细调。我一开始设的阈值很低结果什么请求都会召回到一堆无关技能反而干扰模型判断。后来我把阈值调到能筛掉95%的无关项只保留真正的候选集。注意这里不要贪心候选集宁缺毋滥。无论用哪种路由方式我强烈建议给每个技能配一个“阻止条件”字段明确声明这个技能不处理什么。它在减小误路由上非常管用。比如订单查询技能写一句“不处理退款售后”那么用户问怎么退款的时候即使向量相似度碰巧很高模型看到这个限制也会主动放弃该技能转到售后技能上去。这比只写“能做什么”要可靠得多。3. 从零搭建一套Agent技能库的实操过程3.1 需求拆解与技能粒度划分技能库落地时第一个大问题永远是拆成多少个技能、粒度多大算合适。太粗了比如把“处理客户咨询”做成一整个技能那本质上就是把之前的无技能Agent搬了个壳内部的决策复杂度一点没降太细了比如“格式化用户输入的邮箱”也要一个技能那路由列表会爆炸维护成本也飙升。我自己常用的拆分方法是顺着“用户旅程”去切。先把目标Agent的核心业务流走查一遍列出所有高频出现的用户请求和系统动作然后把这些动作按业务目标聚类凡是属于同一个业务目标的、经常连续执行的就能聚成一个技能最后再做一次粒度校验——如果一个技能内部严重依赖外部条件做巨大分支说明它可能还需要继续拆如果多个技能里反复出现同一段逻辑说明可以抽一个公共技能出来。举一个实际例子。我做的是一个客服辅助Agent最初从用户旅程里列出来一百多个细动作查订单、查物流、改地址、催发货、转人工、查退换货规则、查优惠券、计算赔付金额……经过聚类之后沉淀为15个技能。比如“查订单”和“查物流”合并成了“订单状态查询”因为它俩在业务上高度耦合用户问订单状态的时候有一半概率也想知道物流进度“改地址”和“催发货”保留为独立技能因为它们的内部逻辑完全不同。我还定了一个经验法则单个技能的输入参数不要超过6个内部调用的工具不要超过4个执行路径的分支不要超过5个。超过这个数技能的认知负担就会直线上升而且测试用例会变得非常难构造。3.2 技能描述与元信息的写法技能描述这玩意儿写得好不好直接决定路由准确率但很多工程团队压根没意识到这也是一个需要打磨的产物。我发现一份好用的技能描述需要满足三个条件能触发写清楚“当遇到什么情况时使用”最好包含高频近义词有边界写清楚“什么情况不要用”明确排除相邻场景参数具体关键参数说明取值范围、格式、默认值避免模型瞎猜。给你看一个反例和正例的对比。反例典型的地狱级描述订单查询技能查询订单信息。这个描述几乎没用。模型根本不知道这个技能的输入长什么样、查询范围是什么、能不能查物流、跨境订单算不算、退款单算不算。用户说“帮我看看我那个快递到哪了”模型可能觉得“快递”跟“订单”沾边就给你路由到这个技能但技能内部根本没有物流查询的能力结果就是返回一个错误或者一个不完整的答复。正例能打的好描述订单状态查询 当用户需要查询订单当前状态、物流进度、预计送达时间或确认订单是否已发货时使用。 支持查询已付款的实物和虚拟商品订单。 不支持退款/售后/纠纷单此类请求请转售后处理技能。 参数 - order_id订单号必填格式为20位数字 - include_tracking可选是否返回物流轨迹明细默认false。 注意用户未提供订单号时先使用用户身份查询技能获取其最近订单再用本技能查询。这段描述看似长了点但每一个信息块都有用。前半是触发条件“物流进度”这种近义词也写进去了中间是边界声明告诉模型别把退款单路由过来后半是参数说明和使用策略。我写技能描述的时候还有一个习惯每两周花半小时把最近一次路由日志里“模型选错技能”的case过一遍根据失误模式去补描述。比如我发现模型经常把“改收货地址”误路由到“订单状态查询”因为两者描述里都有“订单”这个词。我在地址修改技能的描述里加了一句“仅当用户明确要求更换收货地址时使用涉及订单信息的查询请使用订单状态查询”误路由率立刻降下来了。3.3 技能的注册、加载与热更新技能不是写完了就完事它需要一套运行时的注册和加载机制。我采用的是目录加注册表的方式结构非常直白skills/ order.status.query/ meta.json execute.py tests/ user.profile.lookup/ meta.json execute.py tests/ refund.process/ meta.json execute.py tests/harness.py每个技能一个目录目录内固定有meta.json元信息和execute.py执行逻辑测试放在tests/下。启动时技能管理器扫描整个skills/目录读取每个meta.json把技能ID作为键注册到内存注册表里。技能管理器核心代码类似这样import json from pathlib import Path from importlib import import_module class SkillRegistry: def __init__(self, skills_root: str): self.skills_root Path(skills_root) self._registry {} def scan_skills(self): self._registry {} for meta_file in self.skills_root.glob(*/meta.json): skill_dir meta_file.parent with open(meta_file, r, encodingutf-8) as f: meta json.load(f) execute_module import_module( fskills.{skill_dir.name}.execute ) self._registry[meta[skill_id]] { meta: meta, execute: execute_module.execute, } return list(self._registry.keys())我特意避开了“一次全量加载执行代码”的做法而是在scan阶段只加载元信息执行模块在技能首次被调用时才做懒加载。这对启动速度和内存占用都有好处尤其在技能库膨胀到七八十个技能的时候这个区别很直观。热更新方面我的方案最简单实用文件监听加版本号。每次技能文件变更后监听器把对应技能的版本号1然后把新模块加载进内存后续路由请求就会走到新版本。这里有个血泪教训千万不要直接在原模块引用上做覆盖Python模块导入是有缓存的如果模块名不变importlib.reload可能不会生效。我吃了一次亏之后统一改成给模块名加版本后缀——execute_v2、execute_v3——这样彻底避开缓存问题。注册表的设计还可以加一层“启用/禁用”状态方便临时下架某个有问题的技能而不需要重启服务。我在灰度期间经常用这个功能一个技能新版本上线后表现不稳我直接在注册表里把它禁掉模型路由到它时返回“技能暂不可用”同时把流量切到备用技能或内部人工入口。3.4 错误处理与降级策略技能执行失败是常态不是异常。这个心态一定要有。关键的容错设计我总结成三层。第一层重试。对于网络抖动、下游超时这类瞬时错误重试非常有用。重试时注意退避策略我一般用线性退避间隔1秒、2秒最多3次。重试前如果技能内部有副作用操作——比如已经写入了半条记录——直接重试会造成脏数据。这种情况就必须先做“补偿清理”再重试。第二层降级。重试还是失败怎么办技能不应该继续硬扛应该快速失败并把控制权交还给Agent主流程。Agent此时可以选一个替代技能或者走人工兜底。举个例子我的订单查询技能依赖订单服务订单服务挂了之后技能返回错误码ORDER_SERVICE_UNAVAILABLE主Agent收到这个错误后直接切换到一个“订单查询降级”技能后者会去查本地数据快照给用户返回一个“当前订单已确认详细状态临时不可用”的弱化答复。第三层快速失败。每个技能都必须设超时时间。我见过最典型的坑是一个技能在等待下游接口响应时把Agent主线程卡死了整个对话直接无响应。技能的超时时间要横着比技能超时必须小于Agent整体的单轮响应时限。比如Agent单轮要求4秒内出结果技能超时就不能设到4秒我给自己的参考值是不超过2.5秒。下面是我封装的重试工具片段async def run_with_retry(fn, retries3, base_delay1.0): for attempt in range(retries): try: return await fn() except RetryableError as e: if attempt retries - 1: raise await asyncio.sleep(base_delay * (attempt 1))这个工具虽然简单但解决了一个大问题——避免了每个技能各自写一套丑陋的重试循环。所有技能统一依赖这个工具重试策略的调整就只需要改一处。4. 技能质量评估与生命周期管理4.1 技能质量怎么看不只看“有没有报错”技能上线只是开始真正的大头是持续评估。很多团队对技能质量的判断停留在“能跑通就好”实际上远远不够。我维护的一套核心衡量指标如下指标名定义衡量方法调用率技能被路由调用的次数占比按天统计观察分布路由准确率在该调用时被调用的次数 / 被调用的总次数人工标注采样日志成功率技能执行完成且返回OK的比例执行日志统计平均耗时技能执行一次的平均时间跟踪系统用户满意度调用该技能后用户是否顿时简短满意反馈对话后问卷/关键词情感这些指标里路由准确率是最容易隐藏问题的。如果你的路由准确率70%意味着30%的请求其实不该调这个技能是模型“硬调”的。这类请求就算技能执行成功回答也大概率驴唇不对马嘴。所以我每周都会抽50条技能调用日志做人工标注专门看“该不该调”。调低了还容易出问题如果服务依赖的是技能版本2的缓存行为版本升到3之后数据库表结构变了缓存的key照样存在但取出来后解析报错。我吃过这个亏现在的做法是缓存结构变更时强制改缓存key的前缀相当于让旧缓存自动失效。4.2 技能之间的冲突检测与消解技能数量多了之后模型“选错边”是常态。最常见的冲突模式是两个技能描述里出现了高度重叠的词汇模型分不清该用哪一个。我在实际系统中碰到过最典型的一组冲突是“退款申请”和“售后工单”这两个技能。它们都涉及退款、赔付、纠纷等词用户一句“我要退了这单”模型有接近40%的概率选到售后工单技能上而这个技能根本不做退款。排查模型日志后发现两个技能的描述里同时存在“退款”“售后”“订单”这些关键词向量检索阶段就已经难分高下。我的消解方案有四个组合使用描述互斥化明确写“退款处理不包含售后退换货流程售后退换货请用售后工单技能”给模型一个显式的选路指引优先级标注在元信息里给技能打优先级字段路由时如果候选分接近优先选高优先级技能示例注入每个技能描述里附上2到3个“用户说法示例”比如“我要退款”对应退款申请技能“我收到货坏了”对应售后工单技能。这招在实战中对模型最友好冲突测试集专门维护一组边界case的自动化测试每次技能改动后跑一遍防止冲突复发。冲突测试集长这样CONFLICT_TEST_CASES [ { user_input: 我要退款, expected_skill: refund.request, }, { user_input: 我收到的货坏了能换吗, expected_skill: after_sale.ticket, }, { user_input: 帮我看看我的退款到哪一步了, expected_skill: refund.progress, }, ]这段测试的价值不在于跑完就算过而在于它把每一次踩坑都固化了。只要模型在这批case上误选就应该去改描述、改示例直到全部通过为止。4.3 技能版本管理与回滚技能迭代多了之后版本管理就变成刚需。我用的方案是每个技能目录下维护一份CHANGELOG.md每次改动记录变更内容执行模块按版本号命名execute_v2.py、execute_v3.py注册表指向当前激活版本。版本切换我最常用的是“影子模式”新版本技能以order.status.query.v3注册但不进入正式路由列表在影子模式下正式版的每个请求会同时调用v2和v3两个版本执行v3的返回结果只做记录、不返回给Agent积累一段时间样本后对比两个版本的成功率、耗时、输出质量确认新版本没退化再把它切换为正式版。这个流程虽然比重启多了一点点工作但在生产环境中非常必要。Agent系统的行为是模型和代码耦合出来的你更换一个技能影响的可能不止这一处还会连带影响后续的对话路径。影子模式能让你在尽量不影响线上的前提下观察变更的实际影响。如果新版本真的出了问题回滚也要非常快。我的做法是技能目录里始终保留上一个版本的模块文件切换版本只是一个注册表指针的变更连代码部署都不需要。5. 实测中的典型问题和排障过程5.1 模型“误选”技能的根因一次完整排查链路有一次线上用户问“我的东西显示签收了但没收到”模型没有走到物流异常技能反而调了订单状态查询技能返回了一个“已签收”的结果把用户跑崩了。我一般是按下面这条链路排查的第一步拉出模型日志。看它在路由决策时把哪些技能放进了候选列表每个候选的分数是多少。结果发现“订单状态查询”和“物流异常上报”两个技能的向量分数都很接近模型犹豫之后选了分数稍微高一点的订单查询。第二步看候选技能的描述。订单状态查询描述里有“支持查询物流进度”而用户那句话里包含“签收”“没收到”跟“物流进度”兜在一起模型被带偏了。第三步修描述。我在这两个技能的描述里各自加了一句互斥声明订单查询技能明确写“不处理签收异常、包裹丢失等情况此类问题走物流异常上报”物流异常技能写明“当用户反馈包裹显示签收但实际未收到、物流中断、包裹丢失时使用”。第四步跑冲突测试集。把这批边界case加进测试集从误选修复到全过然后重新看线上路由准确率。这轮排查的收获是大多数模型误选根源都在描述层改描述比改模型参数划算得多。模型本身不擅长精细区分词义相近的两个任务你的描述就要替模型做这个区分。5.2 上下文污染一个隐蔽的杀手另一个让我记忆深刻的坑是上下文污染。症状是Agent在技能调用完成之后后续的推理开始出现莫名其妙的“幻觉”比如用户根本没提订单Agent却喋喋不休地讲订单号或者原本只问一句话Agent却把技能内部的各种中间步骤复述了一遍。我回放了Agent轨迹发现数据链路上多了好几段不该出现的内部信息。具体来源是技能执行时内部记录了MySQL查询日志以及为了调试加的print输出。这些内容被错误地当成了技能返回结果的一部分随消息回传给主Agent。模型看到之后就误以为这些内部环节是用户关心的东西开始围绕它们“发挥创作”。处理方案有两个方向我都用上了严格执行输出Schema白名单技能返回值用SkillResult.ok(payload)统一包装而payload的字段必须在meta.json的输出Schema中声明过字段白名单之外的其他键一律丢弃给外发数据加一道序列化拦截技能返回在写入消息缓冲前做一次json.dumps再json.loads这一步可以把Python对象里藏着的意外字段暴露出来避免静默透传。这次踩坑给我的最大教训是Agent的上下文就像水管你往里倒什么水流出来的就是什么水。技能内部是调试还是脚手架统统只能待在技能这一层绝不能漏到上层推理链里。5.3 多个Agent共用技能时的边界问题最后说一个多Agent协作时才暴露的边界问题。我做了一套客服Agent和一套工单处理Agent两个Agent都会用到“用户身份查询”这个技能。客服Agent的对话上下文里可能已经存在用户身份信息工单Agent则是纯后端流程没有任何对话上下文。结果同一个技能在两个Agent里的输出被消费的方式不一样导致工单Agent那边经常报错。问题的根子在于技能的执行逻辑写成“有状态”了——它内部会根据上下文是否存在身份信息来决定返回字段的完整度。客服Agent觉得这个“智能”很贴心但工单Agent只想要一个固定结构多余字段反而打乱了它的后续处理。修这个问题的思路是把技能彻底改成无状态接口输入必须显式带user_id不依赖上下文补充任何信息。输出永远是一个固定结构字段完整度不随调用方变化。对于客服Agent它自己在调用前多了一步从上下文解析用户ID的操作然后把ID显式传给技能。这次之后我给所有技能加了一条设计准则技能不感知调用方的上下文输入不完整就直接返回参数缺失错误或者要求调用方补齐。这条准则虽然牺牲了一点“智能感”换来的却是稳定性和可测试性我认为非常值得。6. 最后分享几个经验和技巧文章写到这里核心的东西基本都覆盖了。我最后分享几条个人经验算是给要做技能库的同学一点提前量。技能体系不是一次性工程它更像一座花园要持续打理。技能不断增多之后每个技能都像一个微服务有自己的描述、版本、错误码、依赖任何一个细节老化都会让整体质量下降。我建议每个技能在合入时就配上完整的元信息和测试集别欠技术债。多写“技能说明书”少写“技能实现”。我见过太多团队把时间花在精修技能代码上而描述写得跟草稿一样。说句可能得罪人的话技能的代码逻辑只要不含bug一般能用很久但技能的描述如果不到位每一条真实用户请求都在帮你付“选错技能”的代价。把技能当成产品来运营。这句话是我一直在践行的技能库上线之后每周看调用率、路由准确率、成功率、用户反馈持续迭代描述和边界条件。真正让一个技能库值钱的并不是代码本身而是它和模型、和业务需求之间反复磨合出来的那种契合度。最后技巧层面的一件事给每个技能配一个本地冒烟测试。你的技能库里几十个上百个技能改动了一个公共依赖理论上可能影响一大片。本地冒烟测试不用复杂每个技能跑一个代表性的用例确保它至少能正常跑通。这个习惯虽然看起来不起眼但我统计过至少帮我提前拦截了70%以上的低级回归问题。如果你也在搭Agent技能库或者正准备把现有的工具调用升级成技能体系希望这篇文章里写的那些选择和坑能让你少走点弯路。同行之间经验共享比什么都值钱。