刚开始接触“agent-skills”这个项目代号时我以为它只是给智能体塞一堆函数封装让模型能调个计算器、查个天气。真正动手拆开之后才发现它解决的是一个大问题当模型上下文窗口再大也没法把所有业务动作的细节、边界、权限和纠错逻辑都塞进提示词里这时候就需要把“模型会说话”升级成“模型会干活”。这篇文章我会从思路拆解、技能分层、注册路由、组合编排这几个角度把一套可落地的Agent技能库搭建方案讲明白适合正在做智能体应用、苦于提示词膨胀和工具管理混乱的开发者参考。1. 定位与整体思路Agent技能库不是在堆工具而是在建“岗位说明书”1.1 为什么工具调用不够用了很多团队最初给Agent接工具的方式很直接把业务系统里的函数一个个暴露给模型然后在系统提示词里写“你是一个客服助手你有查询订单、修改地址、申请退款这三个工具请根据用户问题调用”。在只有三五个工具时这套方案没问题但工具一旦超过二十个模型就开始频繁选错工具、传错参数系统提示词也会膨胀到几千字维护成本变成灾难。原因在于工具本身是原子的、无状态的。一个工具只描述“我能做什么”却不描述“什么场景下该用我”“用我之前需要满足什么条件”“我失败了怎么补救”。模型在上下文里看到一堆孤立的函数签名本质上是在做一道没有规则说明的多选题选错是很自然的事。技能Skill就是来解决这个问题的。技能把工具、提示片段、前置校验、后置处理、错误恢复策略打包成一组“带场景语义的动作单元”。模型不需要理解每个函数内部怎么写只需要知道“当前用户情绪激烈时优先使用安抚型话术再进入退款流程”这种高层次的业务知识。技能层的存在让Agent从“拿着工具箱的实习生”变成了“携带岗位手册的老师傅”。1.2 技能、工具、提示词三者的边界划分构建技能库最先要想清楚的是分层。我在实际项目里是这么划分的工具层单一、原子、可复用的系统能力。比如“调用HTTP接口”“读写数据库”“执行一段Python代码”。工具不感知业务场景只负责干活。技能层围绕某类任务组织的执行剧本。比如“订单退款”技能会组合查询订单工具、校验状态工具、发起退款工具并在每一步定义异常分支。提示词层模型的角色设定、沟通风格、安全边界。技能不承担人格塑造只承担任务执行。这个边界很关键。曾经我把技能描述写成了“你是最棒的订单处理专家请用温暖的语言回复用户”结果技能复用性极差换到另一个场景就变得不伦不类。技能应该像菜谱只描述食材和步骤不描述厨师的人设。另外还要注意技能粒度的选择。粒度太粗一个技能塞进太多步骤模型无法判断该从哪一步介入调试时也不知道是哪一步出错粒度太细技能数量又会失控。我常用的判断标准是如果一个技能的执行过程可以被一个具备领域知识的新人照着做下来中间不需要再请示领导那粒度就是合适的。2. 技能库的架构设计与技能描述规范2.1 技能层在Agent系统中的位置我把整个Agent系统分成四层模型层推理内核、记忆层短期会话、长期偏好、向量检索、技能层业务动作单元、执行层外部系统联动。模型层和技能层之间通过一个“技能路由”模块连接模型不是直接看到所有技能而是先由一个轻量级检索引擎根据当前任务意图召回候选技能再把候选技能的描述注入上下文。这样做的好处是上下文消耗可控。假设技能库里有100个技能每个技能平均描述200字全量注入需要2万字对很多商用模型来说会吃掉大量context预算而且引入大量无关信息会增加幻觉概率。改为召回模式后每次只注入3到5个技能描述效果明显好转。技能的呼叫流程是意图识别判定用户请求属于哪类任务 → 技能召回从索引中寻找候选技能 → 技能校验检查前置条件和必填参数 → 执行与监控调用技能内部步骤 → 结果回填把执行结果转为结构化数据交给模型组织自然语言回复。这个流程里技能层不是被动等待模型调用的函数列表而是主动参与任务判断的执行单元。2.2 技能描述文件与目录结构每个技能我建议用独立目录承载而不是塞进一个巨大的Python文件。统一的目录结构能降低维护成本也方便后续做权限控制、灰度发布。我的标准结构是skills/ common/ web_search/ http_request/ commerce/ order_query/ order_refund/ address_modify/ data_analysis/ table_load/ table_clean/ statistic_summary/每个技能目录下包含三个文件skill.yaml描述文件给路由和模型看、run.py执行入口给运行时调用、schema.json参数校验规则给参数解析器用。其中skill.yaml是灵魂它决定了模型能不能在正确时刻想起这个技能。一个实际可用的skill.yaml长这样name: order_refund description: 处理用户对已支付订单的退款申请支持全额退款和部分退款。当用户明确提出退款、不想要了、买错了、价格太贵想退差价时使用。 tags: [commerce, refund, 售后] entry: run.py params: order_id: type: string required: true description: 订单编号格式如 ORD20240001 reason: type: string required: false description: 用户填写的退款原因 preconditions: - 订单状态必须是已支付或部分发货状态 - 订单不能处于售后关闭状态 timeout: 30 quality: - 退款金额不得超过实付金额 - 退款原因必须落库这里最容易被忽视的是description字段。我见过很多技能描述写得过于宽泛例如“处理订单相关操作”结果模型在查物流时也把退款技能召回来了。描述应该尽可能列举典型的触发场景和用户说法甚至可以写否定示例“当用户只是查询物流时不要使用本技能”。这些表面上是给模型看的提示词实际上是给路由召回的语义索引。2.3 参数Schema的重要性参数Schema不是简单定义几个字段就行它承担着模型输出纠偏的作用。LLM调用技能时经常犯的错是参数名猜错、参数格式写错、必填项漏传。schema.json里我会定义每个字段的严格类型、枚举范围、正则模式并在运行时做一次校验。{ order_id: { type: string, pattern: ^ORD\\d{8}$, required: true }, refund_amount: { type: number, minimum: 0.01, maximum: 99999 } }校验失败时不要直接抛异常而是把错误信息拼成一条“模型可读的修正建议”回传给大模型重新生成参数。例如“order_id格式不正确正确示例为ORD20240001请重新生成”。这比硬编码正则校验后直接报错要有效得多因为模型具备根据反馈修正输出的能力。3. 技能注册、装载与路由让技能库真正跑起来3.1 技能注册中心与热装载技能不是写进代码里就完事了。我采用注册中心模式系统启动时扫描技能目录解析每个skill.yaml把技能元数据登记到内存索引中。这样可以实现热更新新加一个技能目录后通过一个管理接口触发重新扫描不用重启Agent服务。注册中心的伪代码结构如下class SkillRegistry: def __init__(self): self._skills {} self._tag_index defaultdict(list) self._lock asyncio.Lock() async def load_all(self, base_path: str): async with self._lock: for yaml_path in scan_skill_manifests(base_path): skill await self._load_skill(yaml_path) self._skills[skill.name] skill for tag in skill.tags: self._tag_index[tag].append(skill.name) async def reload(self, skill_name: str None): # 支持单个技能热更新用于线上快速修复 pass async def search(self, query: str, top_k: int 5): # 向量召回 关键词兜底 pass注册中心的另一个职责是处理技能依赖。有些技能会依赖其他技能比如“生成销售周报”技能依赖“读取数据表”技能。依赖关系在skill.yaml里声明装载时做一次DAG检查避免循环依赖。3.2 技能召回策略向量与规则的融合召回是整个技能库最影响体验的环节。纯规则匹配无法覆盖用户复杂说法纯向量检索又可能在冷门技能上召回率不稳定。我实际采用的是两级召回第一级用关键词和标签做粗筛第二级用句向量对用户当前输入与技能描述做相似度计算最终用加权分排序。关键词粗筛的目的是把计算成本压下来。用户问“我的订单怎么还没发货”粗筛找到commerce标签下的候选集再对这个候选集做向量精排。如果直接对全量技能库做向量检索技能很多时不光性能差还容易召回语义相近但场景不符的内容。打分权重上经验和教训是技能描述中否定示例可以显著提升精度。例如“不要用于物流查询”这类句子如果单独建一个negative索引在哪匹配到就扣分召回准确率能提升好几个点。3.3 参数解析与技能执行模型决定调用技能后输出往往是一段JSON或代码片段。参数解析要做的是从模型自由文本输出中提取结构化参数。除了直接解析JSON还要做一层兜底当模型输出不规范时用一个小模型或规则引擎从文本中抽取关键字段。执行阶段最重要的是可观测性。每个技能执行时都要产出结构化日志输入参数、每个内部步骤的耗时、中间结果摘要、最终输出。这些日志不仅用于排查错误还能用来评估技能质量。我习惯给每个技能加一个trace_id贯穿一次完整任务链方便把用户问题、模型决策、技能执行结果串起来复盘。执行超时控制放在技能层而不是工具层。外部接口单次调用可能只要2秒但一个技能内部要串行调用三个接口总耗时就是6秒。技能层设置的超时时间应该覆盖整条链路避免模型等待太久造成响应超时。4. 组合编排把单一技能变成复杂任务执行链4.1 一个完整案例日报自动生成单技能能解决单点操作但真实业务场景往往是多步骤任务。以“自动生成数据分析日报”为例我拆成了四个技能table_load读取业务库表、data_clean清洗缺失值和异常值、statistic_summary计算核心指标、report_write生成日报文本。这四个技能单独拿出来都很简单组合起来才构成完整价值。组合编排有两条路。一条是“模型主导编排”模型根据任务目标自行决定调用顺序另一条是“剧本式编排”在技能内部定义好步骤流模型只负责填入参数。我推荐大多数场景用剧本式编排因为模型主导的任意调用顺序容易遗漏步骤而且排查问题时分不清是模型决策错还是执行错。剧本式编排在run.py里体现class DailyReportSkill(SkillBase): async def execute(self, params, context): table await self.invoke_sub_skill(table_load, params) cleaned await self.invoke_sub_skill(data_clean, {table: table}) stats await self.invoke_sub_skill(statistic_summary, {table: cleaned}) report await self.invoke_sub_skill(report_write, {stats: stats}) return report每一步中间结果都会写入context这样任一步骤失败都可以从context里拿到前一步的数据进行重试而不是从头开始把所有统计再做一遍。4.2 技能链的状态管理与幂等设计串行调用多个技能时最怕的是某个中间步骤重复执行产生脏数据。比如报表生成流程中table_load拉取的是实时订单表如果因为report_write超时导致整条链重跑就可能重复拉取外部接口数据。幂等设计能解决这个问题。我在技能执行入口处做输入哈希把相同输入参数并且还在缓存有效期内的执行结果直接复用。这里的哈希要小心业务数据会随时间变化所以缓存有效期要短同时要加上一个force_refresh参数供关键时刻绕过缓存。状态管理还需要考虑“部分成功”的场景。五个步骤里成功了三个剩下两个失败此时不要把整体标记为失败而是返回一个部分成功状态并附上失败原因。模型拿到部分成功状态后可以选择用已有结果先响应用户同时后台重试失败步骤。这个设计在用户体验上比直接报错好了很多。4.3 技能冲突与优先级仲裁技能库规模上来后技能之间会出现语义重叠。比如“订单查询”和“售后进度查询”都能返回订单状态模型容易混淆。解决方法是建立技能互斥表在同一任务上下文里宣称同域互斥的技能只能命中一个。路由阶段如果两个互斥技能都进了候选列表通过一个优先级配置决定保留哪个。优先级配置没法只用数字搞定需要跟业务规则绑定。我实践下来比较好用的模式是“特异性优先”描述里约束条件越多的技能优先级越高。因为约束条件多说明它更专精更适合具体场景。字符串匹配到多个技能时优先选description包含更多实体词的技能。5. 高频故障与排查实录那些必须提前知道的坑5.1 技能召回不准模型强行调用不相关技能这个问题最常出现尤其是技能数量超过二十个之后。我踩过的重灾区是技能描述里堆了大量同义词但缺少“否定边界”。解决办法是给每个技能补充常见的误触场景并在路由打分里加入负向匹配。另一个好用的排查手段是记录每次路由招召回的前三个候选技能及其得分。如果发现某个技能总是错误命中就意味着它的描述边界太宽需要收敛描述或者增加互斥关系。这种日志驱动优化比凭感觉改写描述要高效得多。5.2 模型返回的参数格式漂移模型在不同会话里可能输出“orderId”“order_id”“订单ID”三种写法。只在schema.json里定义一种命名是不够的。我在参数解析层加了一个字段别名映射表把常见变体统一归一化。同时每次校验失败后的错误提示里会包含正确格式示例模型看到示例后更倾向于在下一次生成中修正格式。5.3 长技能链的累积延迟与Token消耗串行技能越多模型参与的环节就越多每步都要跟模型交互一次延迟自然叠加。针对这个情况我的经验是将不需要模型理解的内部步骤从模型交互中剥离开。只有需要模型做业务判断时才和模型交互纯数据处理步骤让技能内部代码直接执行。具体来说技能内部步骤可以被标注为model_visible: false这意味着中间结果不会回填给模型避免模型过度解读中间数值。这样做通常能把一次完整日报生成的token消耗降下来一半以上。5.4 技能库更新导致旧会话失效热更新技能后正在运行中的会话可能还在按旧技能执行。如果新旧技能参数格式不兼容会直接报错。解决方法是引入技能版本号会话上下文里记录它绑定的是哪个版本热更新时提供平滑迁移旧会话继续使用旧版新会话使用新版。5.5 一手实践速查表问题现象快速对策召回不准用户问A场景模型调B技能补充否定边界描述增加互斥配置参数漂移字段名或格式总变做字段别名映射校验失败给示例提示重复执行链路部分失败重启给关键技能加输入哈希缓存和幂等标识超时串行技能总耗时超标剥离非模型交互步骤增大并发度旧会话出错热更新后技能格式变化引入版本号平滑迁移会话绑定6. 后续扩展让技能库从“够用”变成“好用”技能库建设到一定程度后瓶颈不再是单技能质量而是技能之间的复用效率。一个可复用的做法是把技能输出规范化为标准中间格式比如数据类技能统一输出为带Schema的DataFrame结构这样编排层就能像流水线一样把不同技能插拔组合。再往后可以做技能评估集。针对每个技能维护一批典型输入和期望行为每次技能更新后自动跑一遍回归测试。这套东西初期成本不高但能防住“改了一个技能把其他三个技能搞崩”的回归问题。还有一个容易被忽视的点是技能的可解释性。Agent用完一套技能链后应该能够输出“我调用了哪些技能、每步做了什么、得到了什么结果”的简短履历。这不仅方便用户理解也给后续的优化复盘提供了数据基础。我在实际维护中把技能履历和最终回复一起输出用户信任度和问题定位效率都明显改善。我在实际维护这套技能库的过程中最深刻的体会是技能不能靠一次性堆量建设它应该是运营出来的。上线前做好边界定义上线后盯住路由日志和失败归因持续对技能做拆分、合并和淘汰。真正好用的技能库永远处于不断修剪的状态。