“agent-skills” 这个词最近在圈子里频繁出现我自己在两个智能体项目里反复折腾过它算是踩了不少坑也总结出一些还算能落地的经验。简单说agent-skills 指的是给大模型驱动的智能体配备的“技能库”也就是一组可复用、可编排、可观测的能力模块让 agent 不只会“聊天”还能真正“办成事”。这篇文章我想围绕技能系统的设计、定义、调度、工程化、迭代和排障这几个维度把我在实操中的思路和一手的细节写透。不管你是刚接触智能体开发还是已经在做企业级 agent 应用这篇都应该能给你一些参考。1. 先说清楚agent-skills 到底在解决什么问题1.1 从“会聊天”到“会办事”的关键差距大语言模型本质上是一个“文本生成器”。你问它一个问题它给你一段话你让它算一笔账它可以给你公式但它自己不会调用计算器你让它查一下库存它只能告诉你“我无法直接访问实时数据”。这就是大模型能力边界最尴尬的地方它懂很多但手不够长。技能系统就是来解决这个“手不够长”的问题。它的思路很直白把现实中需要执行的操作封装成一个个“技能”让模型在推理时先“选一个技能”然后我们程序侧去真正执行这个技能再把执行结果回传给模型最终由模型综合结果给出用户可读的回答。生活里有个特别贴切的类比大脑在指挥手写字之前不需要知道每一根手指的每一条肌肉如何收缩。大脑只需要发出“写字”这个指令手会自动完成整套精细动作。对 agent 来说技能就是那套“自动完成的动作序列”模型只需要负责“选动作”和“理解结果”。这个思路真正有价值的地方在于它把“模型擅长的事”和“模型不擅长的事”彻底分开。推理、语义理解、决策交给模型精确计算、数据查询、外部系统交互交给技能执行层。各自做各自最擅长的事整体系统才能稳定。1.2 技能和普通工具调用的区别不少人会觉得“工具调用不就是 function calling 吗模型输出一个 JSON我根据 JSON 调用函数不就行了”过去我也这么认为但做得越深越发现工具调用只是一个“传输协议”而不是一个“能力治理方案”。模型在 function calling 里确实可以输出诸如{tool_name: search_stock, params: {sku: ABC}}这样的结构但真正落地时会遇到一连串问题函数名五花八门有的叫getStock有的叫stock_query模型经常选错。参数格式不统一日期有的传2024-08-01有的传2024/08/01有的传时间戳。函数返回什么结构、失败时抛什么错误没有统一约定。没有人分析哪个函数被调用得多、哪个函数总是失败。技能系统做的就是把“函数调用”升级为“技能治理”。一个技能通常包含完整的身份说明、参数规范、执行逻辑、返回格式、失败处理、使用示例甚至包括版本号和负责人。它不只是让模型能“调用一个函数”而是让整个团队能“维护一批能力”。用表格对比最直观维度普通函数调用技能Skill模型选择依据函数名 简短说明长文本描述 使用示例 边界条件参数规范靠函数定义自发约定JSON Schema 强制约束返回结构各写各的有统一的返回模型和错误码可观测性基本没有每次调用都记录指标和日志版本管理代码仓库管技能版本和运行时版本双重管理可编排性弱技能之间可以互相调用、组合所以当你听到 agent-skills 这个词时别只把它理解成“给 agent 加几个 API”它本质上是“给 agent 建立一套可治理的能力基础设施”。1.3 为什么需要一套技能系统而不是一堆零散函数没有技能系统的 agent 项目初期跑得飞快后期死得很惨。这是我真实的体会。第一模型的选择能力会被“混乱的函数列表”拖垮。你想想大模型在每次对话时要在一长串工具列表里挑出正确的那个。如果这些工具的命名和描述都是随手写的有些写得很模糊有些相互重叠模型的决策质量会肉眼可见地下降。用户说“帮我查一下订单”它可能在“查询订单”和“订单搜索”两个描述差不多的函数之间随机选一个效果自然不稳定。第二技能多了之后没有治理机制你根本不知道哪些产能可以被删除。很多时候团队里 A 同学写了一个“发送邮件”函数B 同学又写了一个“邮件下发”函数都在线上跑都有人调用但没人敢删任何一个。这不是技术问题是管理问题。技能系统的核心价值之一就是给这些能力建立“户口本”让每项能力可追溯、可度量、可下线。第三安全边界需要靠技能系统来落实。没有技能系统时模型的“手”是模糊的它到底有哪些权限、能接触哪些系统说不清楚。有了技能系统之后“技能”就是权限的最小单元。我可以决定某些技能只对特定用户开放某些技能只能在内网环境使用某些技能需要人工审批。这让 agent 的行为边界变得清晰可控。2. 技能定义的规范化把每个技能写成一份“可靠的契约”2.1 一个技能需要哪些要素我在定义技能格式时最终形成了一个相对稳定的结构。每一个技能都包含以下几块缺一不可技能标识全局唯一的 id比如order.query用于日志追踪和权限绑定。技能名称模型看到的短名比如query_order_status尽量用动词 对象 动作的命名方式。技能描述这是重中之重。模型依靠描述来决定是否选用该技能。描述里要写清楚“什么时候用”“怎么用”“参数到底是什么”“千万别用在什么地方”。参数定义用 JSON Schema 严格定义包括类型、是否必填、默认值、枚举值、格式说明。执行逻辑真正的业务代码负责对接外部系统、数据库或工具库。返回结构统一包装成{status, data, error_code, error_message, trace_id}方便模型解读和观测系统归因。使用示例给出两到三个“对话 → 模型选择 → 参数填充 → 实际调用”的完整示例模型可以从示例里学会泛化。版本与元信息版本号、责任人、创建时间、变更记录。这套结构的好处是模型侧、执行侧、观测侧都基于同一份契约工作。技能描述写得越好模型选对的概率越高参数定义越严格执行侧的错误越少返回结构越统一模型第二次生成回答时越不容易跑偏。2.2 一个标准技能的 JSON 定义示例下面我给一个简化但完整的技能定义。这里假设我们做一个“查库存”的技能{ id: inventory.query, name: query_inventory, version: 1.4.0, description: 查询某商品的实时可用库存。当用户询问还有货吗库存多少能不能买时使用。参数 sku 为商品编码必填。注意此技能只读查询不负责下单。, parameters: { type: object, properties: { sku: { type: string, description: 商品唯一编码通常是6到12位字母数字组合。 }, warehouse: { type: string, enum: [east, west, north], default: east, description: 仓库区域默认 east。 } }, required: [sku] }, returns: { type: object, properties: { sku: { type: string }, total_available: { type: integer }, warehouse: { type: string }, last_sync_time: { type: string, format: date-time } } }, examples: [ { user_query: 这款鞋子还有44码吗, inferred_params: { sku: SHOE-44-BLK, warehouse: east }, execution_result: { sku: SHOE-44-BLK, total_available: 12, warehouse: east, last_sync_time: 2024-06-18T10:22:31Z } } ] }这段 JSON 可以直接被加载技能注册中心。需要注意几个细节description里我故意加了“注意此技能只读查询不负责下单”这就是在帮模型划边界。模型在你把边界写清楚之后就不会在用户问“帮我下单”的时候错误调用这个查询技能。2.3 描述文本怎么写模型才爱“选”它实战里我发现描述文本的写法对技能选择准确率的影响非常明显甚至超过参数定义的影响。因为模型在决策时首先读的是描述不是参数。我的经验是描述文本遵循三段式第一段什么时候用。明确触发场景比如“当用户需要查询天气时”。第二段怎么填参数。对最难填的参数给出额外解释必要时给出例子。第三段不能什么时候用。这一步最容易忽略但非常管用。比如“此技能不负责订酒店、不负责查询航班”把相邻技能的边界提前切干净。举个例子我曾经写过一个“发送短信”技能最初的描述只有一句“发送一条短信”。结果模型只要遇到用户说“发个消息提醒我”“帮我通知一下”就调用它哪怕用户上下文里根本没有手机号。我把描述改成使用场景当用户要求向指定手机号发送短信时使用。必填参数为 phone 和 contentphone 必须是11位中国大陆手机号content 不得超过70个字符。注意本技能不适用于微信消息、App 推送、邮件通知也不负责定时发送。改完之后误调用率明显下降。不要觉得这是在“教模型做事”这其实就是在给模型补上下文中缺失的知识。你就把描述当作你在给一个刚入职的实习生写工作说明越具体越好越少有歧义越好。3. 技能注册、路由与调度agent 怎么知道该用哪个技能3.1 技能注册中心与启动注入流程技能系统的第一个基础组件是注册中心。它的工作很简单收集所有可用的技能建立索引供模型从候选列表中进行选择。注册中心在应用启动时执行一次。整个流程大概是扫描技能目录读取所有技能定义文件。对每个定义文件做合法性校验id 唯一性、JSON Schema 规范性、执行函数是否存在。将技能加载到内存中的注册表里同时把技能描述文本拉出来构造模型侧的“技能候选列表”。如果技能数量多额外构建向量索引用于后续语义检索。这段逻辑用 Python 表示会比较直观class SkillRegistry: def __init__(self): self._skills {} def load_from_directory(self, skill_dir: str): for path in skill_dir.glob(*/skill.json): skill_def json.loads(path.read_text()) handler import_handler(skill_def[id], path.parent) skill Skill(skill_def, handler) self.validate(skill) self._skills[skill_def[id]] skill def get_selection_context(self, limit: int 50): items list(self._skills.values())[:limit] return [item.to_llm_selection_format() for item in items]注意一个关键点注册中心不只是加载代码它还是“模型候选列表”的唯一来源。换句话说模型能“看到”哪些技能完全由注册中心决定。如果你想让某个技能暂时下线直接把它从注册中心剔除比改一堆业务代码要安全得多。3.2 两种常见的技能发现方式注册完技能之后下一步是让模型在推理时“发现”正确的技能。我试过两种方式各有利弊。第一种是全量注入把注册中心里所有技能的name description parameters拼成一个候选工具列表放进系统提示词或作为 tool schema 传给模型。这种方式最适合技能数量在 50 个以内的场景。简单、直接、模型决策时能看到完整上下文不会因为检索遗漏而选错。第二种是语义检索优先当技能数量很多比如超过 100 个时全量注入会让提示词变得很长增加 token 开销也会让模型“挑花眼”。这时可以先拿用户的 query 做一次向量检索召回最相关的 TopK 个技能只把这 TopK 个技能的描述交给模型决策。我实际跑过的项目里超过 80 个技能后全量注入的准确率开始肉眼可见地下降而语义检索的 TopK 召回能把准确率稳定在可接受范围。代价是你要额外维护一个向量库、处理 embedding 的更新。并不是所有项目都需要这一步先从小规模做起别一上来就搞复杂的向量检索容易把自己绕进去。两种方式的取舍可以这样判断技能少、调用链路简单的项目用全量注入技能多、调用关系复杂的项目用语义检索。无论哪种都建议给注册中心加一个“候选列表日志”每次模型决策前把实际注入的技能列表记录到日志里方便事后排查。3.3 调度失败的兜底方案模型是概率系统一定会出错。技能调度的错误通常有两类选择错误用户问 A 技能的事模型选了 B 技能。参数错误技能选对了但参数缺失、格式不对、语义不对。针对第一类错误兜底方案是设计一个“re-plan 循环”。当技能执行返回的结果和用户意图明显不符时让模型自己反思一次换一个技能重试。这个循环不能无限跑我一般限制两次重试第三次失败就直接转人工兜底话术比如“我暂时无法处理这个请求请稍后再试或联系人工客服”。针对第二类错误兜底方案是“参数补全”。模型第一次生成的参数可能缺字段比如用户说“查一下北京的天气”但天气技能要求传城市编码模型给的是城市名。这时候不要直接失败而是做一个参数翻译层把用户原始文本里的信息映射成技能要求的标准参数。如果还缺必要参数就让模型发起一次追问“请问您具体要查询哪个城市的天气”兜底方案的设计原则很简单宁可多一次追问也不要让用户看到一句冷冰冰的“调用失败”。3.4 参数填充的几种来源参数从哪来直接决定了技能执行的成功率。我的经验是参数有三个来源按优先级从高到低分别是模型从对话中提取这是最常见的方式。模型读取用户上下文根据技能参数 schema 生成 JSON。适合大多数场景但对模型能力要求高如果模型参数填充不准要回头优化描述和示例。会话级缺省值有些参数是稳定不变的比如用户所在城市、默认仓库、货币单位。在会话开始时由登录态或环境信息确定技能调用时自动填充不需要模型每次猜测。运行态查询有些参数模型无论如何也给不出来必须在执行时实时拉取。比如“查询当前登录用户的余额”这个用户 id 就不是模型能猜的要在技能 handler 里主动从会话上下文里取。参数来源的优先级应该写进技能定义。我在技能 JSON 里增加了param_rules字段标记每个参数来源是llm_extract、session_default还是runtime_query。这样执行侧就知道该怎么拼装最终请求参数而不只是被动等着模型输出。4. 技能库的工程化这是项目能不能长期跑下去的分水岭4.1 文件目录与命名规范技能系统刚起步时人少、技能少怎么放都行。但技能一旦上了二三十个没有规范的目录结构你连某个技能是干嘛的都得靠猜。我现在的标准目录结构是这样的skills/ inventory/ skill.json handler.py tests/ order/ skill.json handler.py tests/ notification/ skill.json handler.py tests/每个技能一个独立目录包含技能定义、执行代码、测试文件。技能 id 和目录名保持一致不允许有“目录叫 inventory但技能 id 叫 stock_query”这种事。命名上我统一用小写英文字母 下划线动词在前、对象在后比如query_inventory、cancel_order、send_email。避免用驼峰命名因为模型在读工具名时下划线命名的语义切分更清晰候选列表里看起来也更整齐。4.2 技能的版本管理与灰度模型的行为会因为技能描述的变化而变化。你更新了一个技能的描述哪怕只是改了一个句子都可能让模型的决策表现产生波动。所以技能定义文件不能随意覆盖要有版本管理。我在每个技能定义里维护version字段比如1.4.0。每次修改描述或参数 schema版本号都要升级。上线流程这样控制先在测试环境加载新版本技能跑一遍评估集。评估集里包含历史真实用户问题和期望的技能选择结果。只有评估通过后才把新版本技能发布到生产环境。生产环境同时保留旧版本技能加一个开关控制实际走哪一版。一旦发现问题直接一键切回旧版本。这套流程听起来繁琐但真的能救命。有一次我改了一个订单技能的参数描述评估集通过率下降了 18%如果不做灰度直接上线用户投诉会立刻炸锅。4.3 技能测试让“会办的事”可回归技能测试和普通接口测试不太一样它有两层。第一层是单元测试面向 handler 本身。参数合法时返回结构是否符合规范、参数缺失时错误信息是否清晰、超时和外部依赖失败时是否能正确降级。第二层是评估测试面向模型决策。这层测试才是技能系统特有的。做法是把一批典型用户问题放进一个模拟对话环境里由测试框架调用大模型接口让模型执行一次完整的“选技能 → 填参数 → 调用”过程最后断言模型选对了技能且参数正确。我在项目里维护了一个很小的评估集大概 40 组样例涵盖每个技能的正向用例、反向用例和边界用例。每次技能描述有改动就跑一遍评估集。通过率达到 95% 以上才允许发布。这 40 组合例的维护成本不高但换来的是“改任何东西都不怕出大问题”的安全感。5. 从模型反馈到技能打磨把运行数据变成技能升级线索5.1 记录哪些指标才有价值技能系统上线跑起来之后最有价值的事就是看运行数据。但别眉毛胡子一把抓我建议重点盯这几类指标调用成功率技能执行成功次数 / 总调用次数。失败时还要记录失败原因代码比如参数错误、外部服务错误、权限不足、超时。技能选择命中率模型选中的技能是不是人工标注中“应该选”的技能。这个需要人工抽检或者结合用户最终是否满意来判断。参数补全次数技能被执行前系统主动补全了参数多少次。如果这个数字很高说明描述还不够清晰或者模型提取能力不够。单技能平均 token 消耗同一个技能系统提示词里注入的描述越简洁token 越少。如果某个技能描述过长导致 token 飙升就要考虑精简描述。技能热榜和冷榜哪些技能被高频调用哪些技能长期无人调用。冷榜技能要么写得更清楚要么直接下线。指标本身不难采集难的是坚持复盘。我每周会花两个小时翻一遍调用日志专门找那些“模型选了技能但用户并不满意”的典型案例。5.2 一个典型的技能迭代循环技能迭代不是一个写代码的过程而是一个“观察 → 假设 → 修改 → 验证”的过程。举个例子假设某个“查询订单”的技能日志里连续出现了用户问“我的包裹到哪了”但模型错误的选了“查询订单”却没有调用“查询物流”。我拿到这个案例后先归类这是“选择错误”不是“执行错误”。然后在技能描述里给“查询订单”加一句“本技能只查订单本身的基本信息和金额不负责物流轨迹物流轨迹请使用查询物流技能。”修改后跑评估集确认物流类问题的命中率上升订单查询的误命中率没有上升就可以发布。整个过程可能只用半天但要养成固定的复盘习惯。5.3 少样本示例与技能组合除了改描述还有两个打磨技能的高效手段值得单独说一说。一个是少样本示例。在技能定义里维护三到五个examples每个示例包含“用户问题 → 期望的技能调用参数”。模型在决策时如果能看到这些示例会显著提高泛化能力。尤其是用户问法比较口语化的技能比如“能送货上门吗”“今天能到吗”示例能把口语表达和技能参数语义建立起映射。另一个是技能组合。复杂任务往往不是一个技能能搞定的。比如用户要“下单并短信通知”实际步骤是“创建订单 → 查询订单状态 → 发送短信”。与其让一个技能把所有事做完不如把三个基础技能都注册好然后在执行层做一个复合流程技能编排三个子技能的调用顺序。这样的好处是每个子技能可以独立复用和维护复合技能负责流程控制。我个人的警醒是把技能层级控制在三层以内尽量不要搞出“技能调用技能后又被另一个技能调用”的深链。嵌套越深排查问题越痛苦模型一次的决策误差会逐层放大。6. 实战中踩过的坑这些问题几乎每个项目都会遇到6.1 最常见的问题模型选错技能选错技能的概率并没有很多人想象的那么低。在我早期项目里10 次调用里至少有 1 次选错这在生产环境是不可接受的。原因很集中两个技能的描述太像了。比如“发送邮件”和“发送站内信”如果描述里都没有强调“只能用在哪”模型基本靠猜。解决办法也很直接在描述里增加“本技能不适用于……”的负面列表。这个方法我从“查询订单/查询物流”冲突中验证过准确率提升非常明显。如果负面列表已经写了还是选错那就考虑两个技能是不是真的需要分开。如果它们做的事情高度重合合并成一个技能反而更稳妥。6.2 参数格式不一致模型是文本模型它输出的参数经常“长得很像但对不上”。比如定义参数count是integer模型可能输出字符串3定义日期是2024-06-01模型可能输出2024年6月1日。我的做法是在技能执行层加一个“参数清洗管道”每个参数定义里可以声明transform规则。比如type: string_to_integer、type: date_normalize、type: enum_fuzzy_match。这样模型输出任意格式时执行层都能先清洗再调用真正的接口。不要指望模型严格尊重 JSON Schema它只是个概率模型我们要做的不是堵漏洞而是加兜底。6.3 技能膨胀与检索效果下降技能数量超过 100 个之后全量注入变得笨重语义检索也会因为技能之间的语义重叠而召回错误。更麻烦的是技能列表一旦进入“管不过来”的状态新技能描述就会越来越敷衍最后变成恶性循环。我的经验是两个对策。一是定期清理每两个月梳理一次冷榜技能和相似技能能合并的合并能删除的删除。二是分层治理把技能分成原子技能、复合技能和流程技能三类。原子技能是真正对接外部系统的最小操作复合技能是几个原子技能的编排流程技能是面向完整业务场景的流程模板。模型只管选复合技能和流程技能原子技能由执行层内部调度避免模型在一次决策里面对几百个底层能力。6.4 调试技能时的效率问题技能在真实对话里出了问题最笨的调试方式是“重新跑一遍完整对话”浪费时间还会被模型随机性干扰。我后来加了一个调试模式在技能系统里支持“单技能直呼”也就是跳过模型调度层直接指定技能 id 和参数调用对应 handler并打印完整返回结构。这样 debug 时你就可以排除模型干扰先确认 handler 本身没问题。确认执行层没问题后再回到完整对话流程里去观察模型选择是否正确。绝大多数问题的根因都先这么一刀切成两半能少走很多弯路。调试模式顺手还能用来做“技能冒烟测试”每天凌晨自动跑一遍所有技能的最小健康检查。当天的技能代码如果有问题你能在用户发现之前就先知道这个价值很大。agent-skills 这件事做久了我的体会是最难的从来不是写技能代码而是把每个技能的描述、参数规范、边界条件打磨到让模型“一看就懂、一选就对”。它像什么呢像你给一个能力很强但缺乏常识的新同事写工作流程。你写得越清楚他干得越靠谱。我自己的建议是别想着第一个版本就做出一个庞大的技能平台。先从 10 个以内的技能跑通闭环把“注册 → 选择 → 调度 → 观测 → 迭代”这条链路走顺然后再慢慢加量。技能不是越多越好而是每一个都清楚、稳定、可救。等到你的 agent 能稳定把“该办的事”办成你会发现真正支撑它的不是大模型而是这一层看似不起眼、实则决定成败的技能系统。
“agent-skills” 这个词最近在圈子里频繁出现我自己在两个智能体项目里反复折腾过它算是踩了不少坑也总结出一些还算能落地的经验。简单说agent-skills 指的是给大模型驱动的智能体配备的“技能库”也就是一组可复用、可编排、可观测的能力模块让 agent 不只会“聊天”还能真正“办成事”。这篇文章我想围绕技能系统的设计、定义、调度、工程化、迭代和排障这几个维度把我在实操中的思路和一手的细节写透。不管你是刚接触智能体开发还是已经在做企业级 agent 应用这篇都应该能给你一些参考。1. 先说清楚agent-skills 到底在解决什么问题1.1 从“会聊天”到“会办事”的关键差距大语言模型本质上是一个“文本生成器”。你问它一个问题它给你一段话你让它算一笔账它可以给你公式但它自己不会调用计算器你让它查一下库存它只能告诉你“我无法直接访问实时数据”。这就是大模型能力边界最尴尬的地方它懂很多但手不够长。技能系统就是来解决这个“手不够长”的问题。它的思路很直白把现实中需要执行的操作封装成一个个“技能”让模型在推理时先“选一个技能”然后我们程序侧去真正执行这个技能再把执行结果回传给模型最终由模型综合结果给出用户可读的回答。生活里有个特别贴切的类比大脑在指挥手写字之前不需要知道每一根手指的每一条肌肉如何收缩。大脑只需要发出“写字”这个指令手会自动完成整套精细动作。对 agent 来说技能就是那套“自动完成的动作序列”模型只需要负责“选动作”和“理解结果”。这个思路真正有价值的地方在于它把“模型擅长的事”和“模型不擅长的事”彻底分开。推理、语义理解、决策交给模型精确计算、数据查询、外部系统交互交给技能执行层。各自做各自最擅长的事整体系统才能稳定。1.2 技能和普通工具调用的区别不少人会觉得“工具调用不就是 function calling 吗模型输出一个 JSON我根据 JSON 调用函数不就行了”过去我也这么认为但做得越深越发现工具调用只是一个“传输协议”而不是一个“能力治理方案”。模型在 function calling 里确实可以输出诸如{tool_name: search_stock, params: {sku: ABC}}这样的结构但真正落地时会遇到一连串问题函数名五花八门有的叫getStock有的叫stock_query模型经常选错。参数格式不统一日期有的传2024-08-01有的传2024/08/01有的传时间戳。函数返回什么结构、失败时抛什么错误没有统一约定。没有人分析哪个函数被调用得多、哪个函数总是失败。技能系统做的就是把“函数调用”升级为“技能治理”。一个技能通常包含完整的身份说明、参数规范、执行逻辑、返回格式、失败处理、使用示例甚至包括版本号和负责人。它不只是让模型能“调用一个函数”而是让整个团队能“维护一批能力”。用表格对比最直观维度普通函数调用技能Skill模型选择依据函数名 简短说明长文本描述 使用示例 边界条件参数规范靠函数定义自发约定JSON Schema 强制约束返回结构各写各的有统一的返回模型和错误码可观测性基本没有每次调用都记录指标和日志版本管理代码仓库管技能版本和运行时版本双重管理可编排性弱技能之间可以互相调用、组合所以当你听到 agent-skills 这个词时别只把它理解成“给 agent 加几个 API”它本质上是“给 agent 建立一套可治理的能力基础设施”。1.3 为什么需要一套技能系统而不是一堆零散函数没有技能系统的 agent 项目初期跑得飞快后期死得很惨。这是我真实的体会。第一模型的选择能力会被“混乱的函数列表”拖垮。你想想大模型在每次对话时要在一长串工具列表里挑出正确的那个。如果这些工具的命名和描述都是随手写的有些写得很模糊有些相互重叠模型的决策质量会肉眼可见地下降。用户说“帮我查一下订单”它可能在“查询订单”和“订单搜索”两个描述差不多的函数之间随机选一个效果自然不稳定。第二技能多了之后没有治理机制你根本不知道哪些产能可以被删除。很多时候团队里 A 同学写了一个“发送邮件”函数B 同学又写了一个“邮件下发”函数都在线上跑都有人调用但没人敢删任何一个。这不是技术问题是管理问题。技能系统的核心价值之一就是给这些能力建立“户口本”让每项能力可追溯、可度量、可下线。第三安全边界需要靠技能系统来落实。没有技能系统时模型的“手”是模糊的它到底有哪些权限、能接触哪些系统说不清楚。有了技能系统之后“技能”就是权限的最小单元。我可以决定某些技能只对特定用户开放某些技能只能在内网环境使用某些技能需要人工审批。这让 agent 的行为边界变得清晰可控。2. 技能定义的规范化把每个技能写成一份“可靠的契约”2.1 一个技能需要哪些要素我在定义技能格式时最终形成了一个相对稳定的结构。每一个技能都包含以下几块缺一不可技能标识全局唯一的 id比如order.query用于日志追踪和权限绑定。技能名称模型看到的短名比如query_order_status尽量用动词 对象 动作的命名方式。技能描述这是重中之重。模型依靠描述来决定是否选用该技能。描述里要写清楚“什么时候用”“怎么用”“参数到底是什么”“千万别用在什么地方”。参数定义用 JSON Schema 严格定义包括类型、是否必填、默认值、枚举值、格式说明。执行逻辑真正的业务代码负责对接外部系统、数据库或工具库。返回结构统一包装成{status, data, error_code, error_message, trace_id}方便模型解读和观测系统归因。使用示例给出两到三个“对话 → 模型选择 → 参数填充 → 实际调用”的完整示例模型可以从示例里学会泛化。版本与元信息版本号、责任人、创建时间、变更记录。这套结构的好处是模型侧、执行侧、观测侧都基于同一份契约工作。技能描述写得越好模型选对的概率越高参数定义越严格执行侧的错误越少返回结构越统一模型第二次生成回答时越不容易跑偏。2.2 一个标准技能的 JSON 定义示例下面我给一个简化但完整的技能定义。这里假设我们做一个“查库存”的技能{ id: inventory.query, name: query_inventory, version: 1.4.0, description: 查询某商品的实时可用库存。当用户询问还有货吗库存多少能不能买时使用。参数 sku 为商品编码必填。注意此技能只读查询不负责下单。, parameters: { type: object, properties: { sku: { type: string, description: 商品唯一编码通常是6到12位字母数字组合。 }, warehouse: { type: string, enum: [east, west, north], default: east, description: 仓库区域默认 east。 } }, required: [sku] }, returns: { type: object, properties: { sku: { type: string }, total_available: { type: integer }, warehouse: { type: string }, last_sync_time: { type: string, format: date-time } } }, examples: [ { user_query: 这款鞋子还有44码吗, inferred_params: { sku: SHOE-44-BLK, warehouse: east }, execution_result: { sku: SHOE-44-BLK, total_available: 12, warehouse: east, last_sync_time: 2024-06-18T10:22:31Z } } ] }这段 JSON 可以直接被加载技能注册中心。需要注意几个细节description里我故意加了“注意此技能只读查询不负责下单”这就是在帮模型划边界。模型在你把边界写清楚之后就不会在用户问“帮我下单”的时候错误调用这个查询技能。2.3 描述文本怎么写模型才爱“选”它实战里我发现描述文本的写法对技能选择准确率的影响非常明显甚至超过参数定义的影响。因为模型在决策时首先读的是描述不是参数。我的经验是描述文本遵循三段式第一段什么时候用。明确触发场景比如“当用户需要查询天气时”。第二段怎么填参数。对最难填的参数给出额外解释必要时给出例子。第三段不能什么时候用。这一步最容易忽略但非常管用。比如“此技能不负责订酒店、不负责查询航班”把相邻技能的边界提前切干净。举个例子我曾经写过一个“发送短信”技能最初的描述只有一句“发送一条短信”。结果模型只要遇到用户说“发个消息提醒我”“帮我通知一下”就调用它哪怕用户上下文里根本没有手机号。我把描述改成使用场景当用户要求向指定手机号发送短信时使用。必填参数为 phone 和 contentphone 必须是11位中国大陆手机号content 不得超过70个字符。注意本技能不适用于微信消息、App 推送、邮件通知也不负责定时发送。改完之后误调用率明显下降。不要觉得这是在“教模型做事”这其实就是在给模型补上下文中缺失的知识。你就把描述当作你在给一个刚入职的实习生写工作说明越具体越好越少有歧义越好。3. 技能注册、路由与调度agent 怎么知道该用哪个技能3.1 技能注册中心与启动注入流程技能系统的第一个基础组件是注册中心。它的工作很简单收集所有可用的技能建立索引供模型从候选列表中进行选择。注册中心在应用启动时执行一次。整个流程大概是扫描技能目录读取所有技能定义文件。对每个定义文件做合法性校验id 唯一性、JSON Schema 规范性、执行函数是否存在。将技能加载到内存中的注册表里同时把技能描述文本拉出来构造模型侧的“技能候选列表”。如果技能数量多额外构建向量索引用于后续语义检索。这段逻辑用 Python 表示会比较直观class SkillRegistry: def __init__(self): self._skills {} def load_from_directory(self, skill_dir: str): for path in skill_dir.glob(*/skill.json): skill_def json.loads(path.read_text()) handler import_handler(skill_def[id], path.parent) skill Skill(skill_def, handler) self.validate(skill) self._skills[skill_def[id]] skill def get_selection_context(self, limit: int 50): items list(self._skills.values())[:limit] return [item.to_llm_selection_format() for item in items]注意一个关键点注册中心不只是加载代码它还是“模型候选列表”的唯一来源。换句话说模型能“看到”哪些技能完全由注册中心决定。如果你想让某个技能暂时下线直接把它从注册中心剔除比改一堆业务代码要安全得多。3.2 两种常见的技能发现方式注册完技能之后下一步是让模型在推理时“发现”正确的技能。我试过两种方式各有利弊。第一种是全量注入把注册中心里所有技能的name description parameters拼成一个候选工具列表放进系统提示词或作为 tool schema 传给模型。这种方式最适合技能数量在 50 个以内的场景。简单、直接、模型决策时能看到完整上下文不会因为检索遗漏而选错。第二种是语义检索优先当技能数量很多比如超过 100 个时全量注入会让提示词变得很长增加 token 开销也会让模型“挑花眼”。这时可以先拿用户的 query 做一次向量检索召回最相关的 TopK 个技能只把这 TopK 个技能的描述交给模型决策。我实际跑过的项目里超过 80 个技能后全量注入的准确率开始肉眼可见地下降而语义检索的 TopK 召回能把准确率稳定在可接受范围。代价是你要额外维护一个向量库、处理 embedding 的更新。并不是所有项目都需要这一步先从小规模做起别一上来就搞复杂的向量检索容易把自己绕进去。两种方式的取舍可以这样判断技能少、调用链路简单的项目用全量注入技能多、调用关系复杂的项目用语义检索。无论哪种都建议给注册中心加一个“候选列表日志”每次模型决策前把实际注入的技能列表记录到日志里方便事后排查。3.3 调度失败的兜底方案模型是概率系统一定会出错。技能调度的错误通常有两类选择错误用户问 A 技能的事模型选了 B 技能。参数错误技能选对了但参数缺失、格式不对、语义不对。针对第一类错误兜底方案是设计一个“re-plan 循环”。当技能执行返回的结果和用户意图明显不符时让模型自己反思一次换一个技能重试。这个循环不能无限跑我一般限制两次重试第三次失败就直接转人工兜底话术比如“我暂时无法处理这个请求请稍后再试或联系人工客服”。针对第二类错误兜底方案是“参数补全”。模型第一次生成的参数可能缺字段比如用户说“查一下北京的天气”但天气技能要求传城市编码模型给的是城市名。这时候不要直接失败而是做一个参数翻译层把用户原始文本里的信息映射成技能要求的标准参数。如果还缺必要参数就让模型发起一次追问“请问您具体要查询哪个城市的天气”兜底方案的设计原则很简单宁可多一次追问也不要让用户看到一句冷冰冰的“调用失败”。3.4 参数填充的几种来源参数从哪来直接决定了技能执行的成功率。我的经验是参数有三个来源按优先级从高到低分别是模型从对话中提取这是最常见的方式。模型读取用户上下文根据技能参数 schema 生成 JSON。适合大多数场景但对模型能力要求高如果模型参数填充不准要回头优化描述和示例。会话级缺省值有些参数是稳定不变的比如用户所在城市、默认仓库、货币单位。在会话开始时由登录态或环境信息确定技能调用时自动填充不需要模型每次猜测。运行态查询有些参数模型无论如何也给不出来必须在执行时实时拉取。比如“查询当前登录用户的余额”这个用户 id 就不是模型能猜的要在技能 handler 里主动从会话上下文里取。参数来源的优先级应该写进技能定义。我在技能 JSON 里增加了param_rules字段标记每个参数来源是llm_extract、session_default还是runtime_query。这样执行侧就知道该怎么拼装最终请求参数而不只是被动等着模型输出。4. 技能库的工程化这是项目能不能长期跑下去的分水岭4.1 文件目录与命名规范技能系统刚起步时人少、技能少怎么放都行。但技能一旦上了二三十个没有规范的目录结构你连某个技能是干嘛的都得靠猜。我现在的标准目录结构是这样的skills/ inventory/ skill.json handler.py tests/ order/ skill.json handler.py tests/ notification/ skill.json handler.py tests/每个技能一个独立目录包含技能定义、执行代码、测试文件。技能 id 和目录名保持一致不允许有“目录叫 inventory但技能 id 叫 stock_query”这种事。命名上我统一用小写英文字母 下划线动词在前、对象在后比如query_inventory、cancel_order、send_email。避免用驼峰命名因为模型在读工具名时下划线命名的语义切分更清晰候选列表里看起来也更整齐。4.2 技能的版本管理与灰度模型的行为会因为技能描述的变化而变化。你更新了一个技能的描述哪怕只是改了一个句子都可能让模型的决策表现产生波动。所以技能定义文件不能随意覆盖要有版本管理。我在每个技能定义里维护version字段比如1.4.0。每次修改描述或参数 schema版本号都要升级。上线流程这样控制先在测试环境加载新版本技能跑一遍评估集。评估集里包含历史真实用户问题和期望的技能选择结果。只有评估通过后才把新版本技能发布到生产环境。生产环境同时保留旧版本技能加一个开关控制实际走哪一版。一旦发现问题直接一键切回旧版本。这套流程听起来繁琐但真的能救命。有一次我改了一个订单技能的参数描述评估集通过率下降了 18%如果不做灰度直接上线用户投诉会立刻炸锅。4.3 技能测试让“会办的事”可回归技能测试和普通接口测试不太一样它有两层。第一层是单元测试面向 handler 本身。参数合法时返回结构是否符合规范、参数缺失时错误信息是否清晰、超时和外部依赖失败时是否能正确降级。第二层是评估测试面向模型决策。这层测试才是技能系统特有的。做法是把一批典型用户问题放进一个模拟对话环境里由测试框架调用大模型接口让模型执行一次完整的“选技能 → 填参数 → 调用”过程最后断言模型选对了技能且参数正确。我在项目里维护了一个很小的评估集大概 40 组样例涵盖每个技能的正向用例、反向用例和边界用例。每次技能描述有改动就跑一遍评估集。通过率达到 95% 以上才允许发布。这 40 组合例的维护成本不高但换来的是“改任何东西都不怕出大问题”的安全感。5. 从模型反馈到技能打磨把运行数据变成技能升级线索5.1 记录哪些指标才有价值技能系统上线跑起来之后最有价值的事就是看运行数据。但别眉毛胡子一把抓我建议重点盯这几类指标调用成功率技能执行成功次数 / 总调用次数。失败时还要记录失败原因代码比如参数错误、外部服务错误、权限不足、超时。技能选择命中率模型选中的技能是不是人工标注中“应该选”的技能。这个需要人工抽检或者结合用户最终是否满意来判断。参数补全次数技能被执行前系统主动补全了参数多少次。如果这个数字很高说明描述还不够清晰或者模型提取能力不够。单技能平均 token 消耗同一个技能系统提示词里注入的描述越简洁token 越少。如果某个技能描述过长导致 token 飙升就要考虑精简描述。技能热榜和冷榜哪些技能被高频调用哪些技能长期无人调用。冷榜技能要么写得更清楚要么直接下线。指标本身不难采集难的是坚持复盘。我每周会花两个小时翻一遍调用日志专门找那些“模型选了技能但用户并不满意”的典型案例。5.2 一个典型的技能迭代循环技能迭代不是一个写代码的过程而是一个“观察 → 假设 → 修改 → 验证”的过程。举个例子假设某个“查询订单”的技能日志里连续出现了用户问“我的包裹到哪了”但模型错误的选了“查询订单”却没有调用“查询物流”。我拿到这个案例后先归类这是“选择错误”不是“执行错误”。然后在技能描述里给“查询订单”加一句“本技能只查订单本身的基本信息和金额不负责物流轨迹物流轨迹请使用查询物流技能。”修改后跑评估集确认物流类问题的命中率上升订单查询的误命中率没有上升就可以发布。整个过程可能只用半天但要养成固定的复盘习惯。5.3 少样本示例与技能组合除了改描述还有两个打磨技能的高效手段值得单独说一说。一个是少样本示例。在技能定义里维护三到五个examples每个示例包含“用户问题 → 期望的技能调用参数”。模型在决策时如果能看到这些示例会显著提高泛化能力。尤其是用户问法比较口语化的技能比如“能送货上门吗”“今天能到吗”示例能把口语表达和技能参数语义建立起映射。另一个是技能组合。复杂任务往往不是一个技能能搞定的。比如用户要“下单并短信通知”实际步骤是“创建订单 → 查询订单状态 → 发送短信”。与其让一个技能把所有事做完不如把三个基础技能都注册好然后在执行层做一个复合流程技能编排三个子技能的调用顺序。这样的好处是每个子技能可以独立复用和维护复合技能负责流程控制。我个人的警醒是把技能层级控制在三层以内尽量不要搞出“技能调用技能后又被另一个技能调用”的深链。嵌套越深排查问题越痛苦模型一次的决策误差会逐层放大。6. 实战中踩过的坑这些问题几乎每个项目都会遇到6.1 最常见的问题模型选错技能选错技能的概率并没有很多人想象的那么低。在我早期项目里10 次调用里至少有 1 次选错这在生产环境是不可接受的。原因很集中两个技能的描述太像了。比如“发送邮件”和“发送站内信”如果描述里都没有强调“只能用在哪”模型基本靠猜。解决办法也很直接在描述里增加“本技能不适用于……”的负面列表。这个方法我从“查询订单/查询物流”冲突中验证过准确率提升非常明显。如果负面列表已经写了还是选错那就考虑两个技能是不是真的需要分开。如果它们做的事情高度重合合并成一个技能反而更稳妥。6.2 参数格式不一致模型是文本模型它输出的参数经常“长得很像但对不上”。比如定义参数count是integer模型可能输出字符串3定义日期是2024-06-01模型可能输出2024年6月1日。我的做法是在技能执行层加一个“参数清洗管道”每个参数定义里可以声明transform规则。比如type: string_to_integer、type: date_normalize、type: enum_fuzzy_match。这样模型输出任意格式时执行层都能先清洗再调用真正的接口。不要指望模型严格尊重 JSON Schema它只是个概率模型我们要做的不是堵漏洞而是加兜底。6.3 技能膨胀与检索效果下降技能数量超过 100 个之后全量注入变得笨重语义检索也会因为技能之间的语义重叠而召回错误。更麻烦的是技能列表一旦进入“管不过来”的状态新技能描述就会越来越敷衍最后变成恶性循环。我的经验是两个对策。一是定期清理每两个月梳理一次冷榜技能和相似技能能合并的合并能删除的删除。二是分层治理把技能分成原子技能、复合技能和流程技能三类。原子技能是真正对接外部系统的最小操作复合技能是几个原子技能的编排流程技能是面向完整业务场景的流程模板。模型只管选复合技能和流程技能原子技能由执行层内部调度避免模型在一次决策里面对几百个底层能力。6.4 调试技能时的效率问题技能在真实对话里出了问题最笨的调试方式是“重新跑一遍完整对话”浪费时间还会被模型随机性干扰。我后来加了一个调试模式在技能系统里支持“单技能直呼”也就是跳过模型调度层直接指定技能 id 和参数调用对应 handler并打印完整返回结构。这样 debug 时你就可以排除模型干扰先确认 handler 本身没问题。确认执行层没问题后再回到完整对话流程里去观察模型选择是否正确。绝大多数问题的根因都先这么一刀切成两半能少走很多弯路。调试模式顺手还能用来做“技能冒烟测试”每天凌晨自动跑一遍所有技能的最小健康检查。当天的技能代码如果有问题你能在用户发现之前就先知道这个价值很大。agent-skills 这件事做久了我的体会是最难的从来不是写技能代码而是把每个技能的描述、参数规范、边界条件打磨到让模型“一看就懂、一选就对”。它像什么呢像你给一个能力很强但缺乏常识的新同事写工作流程。你写得越清楚他干得越靠谱。我自己的建议是别想着第一个版本就做出一个庞大的技能平台。先从 10 个以内的技能跑通闭环把“注册 → 选择 → 调度 → 观测 → 迭代”这条链路走顺然后再慢慢加量。技能不是越多越好而是每一个都清楚、稳定、可救。等到你的 agent 能稳定把“该办的事”办成你会发现真正支撑它的不是大模型而是这一层看似不起眼、实则决定成败的技能系统。
