如果你也在做大模型 Agent一定见过这种场景系统提示词越写越长里面塞满各种工具的使用说明、参数格式、注意事项模型还是经常把日期传错、把 A 工具和 B 工具搞混、出了问题根本没法定位。我们内部这个代号叫 agent-skills 的项目就是为了解决这一整类问题。它不是一个重框架不搞复杂的 Agent 状态机只做一件事把技能从提示词里拆出来用一套轻量的注册、发现、执行、编排机制让 Agent 知道自己有哪些技能、什么时候该用、怎么用才不翻车。这篇文章是我在落地这个项目几个版本后的完整复盘包含技能文件设计、路由命中、安全边界、失败恢复和组合编排的实操细节适合正在做 Agent 应用、工具调用层、自动化工作流的开发者参考。1. 为什么我决定把技能从Prompt里拆出来1.1 硬编码技能的三种死法早期版本里我们把所有工具说明直接写进 system prompt用如果用户问销量就调用 query_sales如果问库存就调用 query_stock这种伪代码描述。刚开始只有四五个工具效果还行等工具涨到三十个以上问题集中爆发。第一是 prompt 爆炸。每个技能描述平均 150 字30 个就是 4500 字加上历史消息直接逼近上下文窗口模型注意力被严重稀释连基础指令都开始不稳定。第二是复用困难。A 业务写死的技能B 业务要复用只能复制粘贴改一个字段就要动全局提示词回归测试成本极高。第三是没法灰度。技能逻辑升级只能整体替换 prompt出问题只能整体回滚没法对单个技能做小流量验证。这三条里最要命的是第一条。上下文一长模型开始选择性失明明明工具列表里有 query_stock它偏用 query_sales 去查库存参数还对不上。我们当时花了大量时间调 prompt 措辞结果只是按下葫芦浮起瓢。1.2 agent-skills不是工作流引擎只是一层技能适配层开始设计 agent-skills 时我们明确不想做成工作流引擎。工作流引擎关心的是节点、状态流转、人工审批agent-skills 关心的是模型该如何发现并调用一个可执行技能。它更像是模型和业务代码之间的一层适配层管好四件事技能注册表、语义路由、执行沙箱、编排器。注册表统一管理技能描述语义路由决定面对当前任务时调哪个技能执行沙箱负责权限隔离、超时、重试和留痕编排器负责组合技能之间的数据传递。业务逻辑仍然留在技能内部agent-skills 不碰核心算法。另外还有一个现实原因不同模型平台自带的函数调用机制在参数解析方式、返回格式上有差异如果直接把技能塞给各家平台的 function calling后面换模型时到处都要改。agent-skills 定义了一套偏中立的技能描述和调用协议底层适配层可以分别接不同模型上层技能基本不动。很多团队一上来就上重框架状态机、图数据库、可视化编排全安排上结果模型生成的流程和图定义对不上排错排到怀疑人生。我们的经验是先从这四件事做起撑不住再加复杂度大多数场景其实不需要重框架。1.3 开工前立的三条铁律在写第一行代码前我们定了三条原则后面所有设计都围绕它们展开。第一技能必须自描述。每个技能除了实现代码还要带一份结构化说明文件包含做什么、什么时候用、输入输出格式、依赖谁。自描述是路由和复用的基础没有它模型只能靠猜。第二模型只能看到技能的使用说明看不到实现细节。这样做一方面减少 token另一方面避免模型被内部实现带偏比如看到实现里有缓存就自作主张跳过调用。第三任何技能调用都要可观测、可回滚。入参、出参、耗时、花费、错误信息全部留痕技能版本支持一键切换。没有可观测性的技能库上线就是埋雷。这三条看起来简单但后面几次大坑都跟没遵守它们有关。下面我会逐个展开。2. 技能文件结构一个技能到底长什么样2.1 manifest字段设计少一个字段后面都难受技能清单manifest是 agent-skills 的元数据核心。每个技能目录下至少有一个 manifest.json统一描述“这个技能是什么、什么时候用、怎么调用”。我们最终在用的字段大概是这样id全局唯一标识用于路由和执行定位name给模型看的中文短名description一句话说明核心功能走路由时的首选信息when_to_use明确适用和不适用的边界条件防止模型误调用input_schema / output_schema用 JSON Schema 描述参数结构permission技能需要的权限级别比如只读、可写、不可信timeout单次执行超时retry_policy重试策略dependencies组合技能依赖的其他技能version当前生效版本owner维护人便于告警和评审早期我们漏了 owner 和 when_to_use结果技能出问题找不到负责人描述也与实际行为有偏差。后来加了 when_to_use模型的误调用率明显下降。原因很简单模型在调用前多了一道“边界检查”信号知道什么情况下不该用比单纯知道怎么用更重要。2.2 为什么输入校验必须用JSON Schema很多人习惯在技能函数里写 if not isinstance(arg, str) 这种判断但这只覆盖了类型。模型生成的参数经常是“看起来合法但语义不对”比如 month 传成“2025年3月”而不是“2025-03”。如果不清洗业务代码直接背着脏数据跑结果错了还不知是哪一环出的问题。我们用 JSON Schema 做两层校验第一层在路由和解析之后立即检查类型、格式、枚举值、必填项第二层在真正执行业务逻辑前做一次幂等校验。校验不通过时不会直接报错而是把校验失败原因作为“修正信号”返回给模型让模型重新生成参数。这个“校验—反馈—重试”的回路实际效果比让模型自己思考参数合理得多。这里有个关键点校验失败信息要写得像“给模型的提示”而不是“给开发者的异常日志”。比如写成“start_date 需要是 YYYY-MM-DD 格式你传入的是 2025年3月1日”模型很容易理解并修正写成“ValueError at line 3”模型基本没法用。2.3 一个真实技能示例销售趋势查询与摘要拿内部销售看板助手的一个技能举例结构是skills/query_sales_trend/ manifest.json execute.pymanifest.json 核心内容如下{ id: query_sales_trend, version: 2, name: 查询销售趋势, description: 查询指定时间范围的销售趋势返回销售额、订单量、客单价序列, when_to_use: 当用户询问销售额、订单量、增长趋势、日环比、周同比时使用需要先确认日期范围不要用它查询库存或客户明细, input_schema: { type: object, properties: { start_date: {type: string, format: date}, end_date: {type: string, format: date}, granularity: {type: string, enum: [daily, weekly, monthly]} }, required: [start_date, end_date] }, permission: read_only, timeout: 5 }execute.py 内部就是查数仓、算指标、返回 DataFrame 转 JSON。这些逻辑原本藏在 prompt 描述里现在被隔离成一个可独立测试的函数。写到这里想强调一点技能边界要小一个技能只做一件事。我们早期做过一个“查询经营数据”技能扛了 30 个参数最后路由经常命中它但用不对参数后来拆成 8 个小技能问题少了一半。2.4 原子技能、组合技能、系统技能的分类逻辑agent-skills 把技能分为三类原子技能不可再拆直接落地到单个函数比如查库存、发消息、调外部 API。组合技能内部声明依赖哪些原子技能并定义好数据传递顺序比如“生成竞品分析报告”依赖“搜索资讯”“抓取页面”“调用摘要模型”。系统技能agent-skills 内置的技能管理能力比如列出技能、查看技能状态、开关某个技能。系统技能对外开放后可以让 Agent 自己诊断但要配只读权限。分类不是为了炫设计而是为了权限和重试粒度。原子技能失败可以单独重试组合技能失败要整链路回滚系统技能失败只影响诊断不能拖累主流程。有了这个分层上线后的告警定位成本低了很多。3. 技能注册、发现与路由Agent怎么知道该用哪个技能3.1 启动时全量扫描 vs 运行时动态注册agent-skills 第一版用的是启动时扫描技能目录根据 manifest 生成技能清单和函数索引。好处是简单、可预测坏处是新增技能要重启服务。后来加了运行时动态注册接口允许在管理后台“上线”一个新技能系统会校验 manifest 合法性再放进注册表。两种方式不是替代关系而是分层核心技能走启动扫描保证基础能力永远在试验技能走动态注册方便快速验证。动态注册有个坑如果新技能的 description 跟已有技能重叠路由会出现“摇摆”时而选 A 时而选 B。解决办法是注册时做一次描述相似度检查重叠度超过阈值就拒绝上线强制改名。这个机制被我们内部叫“技能名查重”。3.2 语义描述怎么写命中率天差地别路由环节本质是让模型从技能清单中选出最合适的一个所以技能的 description 必须站在“用户问题”的视角去写而不是站在“实现功能”的视角。同一个技能两种写法对比差“query_sales_trend 函数参数 start_date, end_date, granularity通过 HTTP 接口查询 mysql 数据库”好“当用户需要查看任意日期范围内的销售额、订单量、客单价或分析日环比、周同比、月度变化趋势时使用”前者把读者当成了开发者后者把读者当成了“正在处理用户问题的模型”。这个差异在实测中非常明显。同样的 100 个真实用户问题只改描述技能命中率从 62% 提到 91%。措辞里的动词和场景名词是关键像“查看”“分析”“对比”“趋势”这类词要尽量覆盖用户会用的表达。3.3 路由器先按概率排序再按约束过滤agent-skills 的路由分两步。第一步把用户问题和技能清单一起交给模型让模型输出“每个技能的使用概率理由”。第二步按概率从高到低排序再用硬约束过滤。硬约束包括技能是否启用、权限是否够、依赖是否满足、输入是否可解析为合法参数。过滤后取 Top1 作为调用目标如果 Top1 概率低于 0.5或者校验返回错误两次则进入澄清流程直接问用户而不是硬调。有人问为什么不直接让模型输出技能 ID。实测下来让模型输出概率分布比输出唯一 ID 要稳因为即使唯一 ID 选错了概率分布里的第二名可以作为降级选项而且理由文本可以写入审计日志事后排查时能看到模型为什么选了它。3.4 一组实测数据描述改写前后命中率对比下面是我们内部测试集的一组数据100 个来自真实用户的问题均匀覆盖 8 个技能。改动只有两个重写 description 和补 when_to_use。指标改前改后技能 Top1 命中率62%91%平均重试次数3.21.4路由逻辑失败率18%6%每任务路由 token约 1200约 900重试次数下降说明参数校验错误少了token 下降是因为减少了对错误技能的无效尝试。最关键的是模型不再出现“用销售技能查库存”这种离谱错误。路由这层看似简单但它决定了后续所有环节能不能省心。4. 技能执行的安全边界与失败恢复4.1 可信度分级不是所有技能都该直接执行agent-skills 给每个技能打上可信度等级受信任、低信任、不可信。受信任技能一般是内部只读查询入参经过严格校验后可以直接执行低信任技能比如发邮件、改写数据库需要二次人工确认或走审批接口不可信技能比如解析外部网页、执行用户上传的表达式必须在沙箱里跑限制资源、网络、文件系统。这个分级直接影响执行引擎的调度策略。我们用了一个简单的策略表只读技能放行有副作用的技能默认“干跑模式”先不落库返回预览结果让用户确认无法验证来源的技能直接拒绝。分级还决定了超时和重试参数只读技能超时 5 秒重试 1 次写操作超时 10 秒不重试避免重复提交。4.2 超时、重试与熔断配置每个技能可以在 manifest 里单独写 timeout 和 retry_policy不写则套用全局默认。全局默认大概是只读 5 秒、重试 1 次写操作 10 秒、重试 0 次外部 API 8 秒、重试 2 次、间隔递增。熔断是另一个容易被忽略的层。同一技能连续失败超过 5 次熔断器打开随后 5 分钟内不再调用它而是直接走降级逻辑。我们遇到过一个外部天气 API 间歇性故障本来只是上游不稳结果因为一直重试硬是把 Agent 主任务拖到超时。上了熔断之后技能失败会在 2 秒内被发现并切到降级方案用户基本无感。4.3 全链路留痕入参、出参、耗时、Token开销执行层会在技能调用前后各埋一个点记录调用链 ID、技能 ID、版本、入参、出参摘要、状态码、耗时、Token 消耗、重试次数。数据写到独立的审计表不跟业务表混在一起。这些痕迹有三个用途一是排障用户说“刚才结果不对”我们能定位到具体路径二是质量监控定期统计各技能的失败率、平均延迟、成本占比识别需要重构的技能三是模型行为分析比如查看哪些描述让模型误入歧途。有一次我们发现某个技能的调用量突增一查是描述里多了“如果用户没说明时间范围默认最近 30 天”模型开始频繁代填参数后来把这句话删掉调用量恢复正常。4.4 技能失败时的降级链一个技能失败不是终点agent-skills 支持在 manifest 里声明 fallback。降级链可以是同功能的不同实现比如查询销售数据失败后降级到只查前一天全量汇总也可以是替代表达方式比如实时行情失败就返回缓存快照并标注时间。设计降级链最重要的是控制长度最多三级。超过三级链路本身的判断成本已经超过“直接告诉用户暂时不可用”的成本。我们还规定降级分支也要留痕并在最终回复里主动标注“这是降级数据”。用户对数据时效是有预期的不标注反而更伤信任。5. 技能编排从单技能到多技能协作5.1 组合技能通过依赖声明而不是代码胶水组合技能不写“先调 A 再调 B”的硬编码。我们在 manifest 的 dependencies 里声明需要哪些子技能以及它们之间的数据流约束。agent-skills 的编排器根据依赖关系生成一张简单的执行顺序图。顺序规则只有两条被依赖者先执行无依赖关系的技能按注册顺序执行。这样设计的好处是替换子技能实现时不需要改编排代码。比如“生成竞品报告”依赖“搜索资讯”和“抓取页面”后来把“抓取页面”从自研爬虫换成第三方解析接口只需要替换技能目录里的实现报告能力保持不变上游技能完全无感。5.2 数据在技能间传递的统一信封格式组合技能执行时前一个技能的输出会作为后一个技能的输入。为了避免技能之间因为字段命名不同而互相等待agent-skills 规定所有技能输出必须包一层标准信封{ ok: true, data: { ... }, meta: { data_date: 2025-04-01, source: query_sales_trend, elapsed_ms: 230 } }meta 里放数据日期、来源、耗时data 才是业务数据。信封不是形式主义。一次排查中我们发现两个技能使用的日期字段一个叫 date一个叫 day模型在中间做了一次“理解性转换”结果把日期格式弄错。改成统一信封后技能之间传递的是结构化字段不再依赖模型转述。某个技能只要声明消费字段就能从信封里取缺字段直接报错而不是猜测。5.3 分支逻辑放哪一层我最后放在Agent编排层组合技能内部要不要写 if 判断我们的经验是不要。分支逻辑应放在 Agent 编排层由模型根据用户意图决定走哪条技能链组合技能只负责固定的顺序流水线。原因是模型适合做“要不要做 A”的决策不适合做“HBase 里查不到就走 ES”这种技术容错。实际项目里我们把技能链拆成“主链 旁路”主链是固定顺序的组合技能旁路是可选的增强技能。模型拿到用户请求后先规划主链再判断是否追加旁路。比如“竞品分析”主链是搜索 抓取 摘要旁路可以是“查内部定价”或“拉取库存数据”视问题而定。这样既保留了模型决策的灵活性又不像完全自由编排那样不可控。5.4 案例自动生成绩效异动分析报告拿一个内部场景串一遍。用户说“帮我看下上个季度哪些商品销量异动比较大”。agent-skills 的路由先匹配到“绩效异动分析”组合技能。主链依次执行查询销售趋势原子技能得到日/月粒度指标计算环比与异常点原子技能输出异动商品 ID 列表和幅度查询商品主数据原子技能把 ID 映射为名称和类目调用大模型摘要生成原子技能把这几天变化写成人话。每个技能的输入输出都是信封前一步的输出直接作为下一步的部分输入Agent 编排层只需在步骤间补充用户提供的限定条件。整个过程 20 秒左右大部分耗时在查询和摘要生成编排器本身的调度开销不到 1%。这在我们原来硬编码 prompt 的方案里几乎不可能实现——那时候所有环节都靠模型“自由发挥”结果中间坏一步就只能从头再来。6. 复盘最值得记住的五个教训6.1 技能不能写得太聪明第一版技能设计时我们试图让技能内部自动纠错识别到日期格式不对就自动改识别到用户问的是库存就自动跳到查询库存技能。结果就是黑盒套黑盒出了问题完全不知道是模型决策错还是技能内部自作主张。后来统一原则技能只做“按输入执行并返回结果”所有判断交给模型或 Agent 编排层。笨技能反而好排查。6.2 校验约束不是越多越好JSON Schema 加得太细同样有问题。开始我们要求时间格式必须精确到日期且必须落在合法业务周期内结果模型生成的参数频繁校验失败重试两次还失败就直接拒绝用户问题明明很简单却办不成事。后来把必填项减到真正影响正确性的字段其余用宽松类型加自动归一化。校验的目的是挡住脏数据不是给模型设路障。6.3 技能更新要支持热切换与灰度技能代码更新时最怕“删旧上新”一刀切。我们现在每个技能目录保留最近两个版本manifest 里用 version 字段标识当前生效版本。管理后台可以给某个技能指定灰度组比如先切 10% 流量到新版本观察平均耗时和错误率稳定后再放到 100%。一次因为新版本查询逻辑少处理了周末数据灰度阶段立刻发现异常回滚只用了十几秒没有影响主流程。6.4 接入前后的一组对比数据我们以一个内部经营分析助手为样板做了接入前后对比任务覆盖查数、对比、异动解释、报告生成四类。接入 agent-skills 之前任务整体成功率约 70%平均每任务调用轮数偏高接入后整体成功率提升到 94%单轮调用占比明显提高失败任务主要集中在外部 API 超时和权限确认环节。成功率提升的主要来源不是执行更快而是“选错技能”的情况几乎消失了。说明把技能说明结构化、让模型先选后调比在提示词里堆功能描述更符合模型的推理习惯。6.5 后续扩展方向这个项目目前还在迭代后续有几个方向在推进一个是把技能描述 embedding 化用向量检索做预筛后再交给模型精排降低长技能列表对上下文的压力另一个是支持技能间的并行执行因为组合技能里有多个无依赖的子技能现阶段还是串行往后可以显著缩短整体耗时还计划做一个技能质量评分面板自动归因失败技能并给出描述修改建议。如果正在做 Agent 技能化的朋友建议从最小闭环开始先拆三五个技能跑通注册、路由、执行、留痕再一步步加组合和灰度。别上来就追求大而全的编排框架技能层最先要解决的永远是“模型别选错、选了能跑对、跑错能查到”这三件事。