在Agent应用开发这条路上我踩过最大的坑不是模型能力不够而是技能调用这一层被严重低估了。很多人一开始觉得只要把工具函数写好、prompt里列明白Agent就能好好干活。结果真跑起来才发现技能描述不规范、参数对不上、失败之后没有回退机制整个流程一碰就碎。agent-skills这个项目就是我在这个背景下梳理出来的一套技能体系工程化方案从技能定义、注册、调用到编排、评测、踩坑复盘把Agent“会什么”这件事彻底结构化。这篇文章就把我实际搭建这套技能体系的全过程、关键决策和调试经验完整写出来包括技能清单的schema设计、注册路由机制、组合编排策略、评测集构建以及大量只会在生产环境里撞见的疑难问题。不管你是刚开始接触Agent开发的新手还是已经在生产环境里被技能调用折磨过几轮的工程师这份沉淀应该都能给你一些直接的参考。1. 内容整体设计与思路拆解1.1 从“工具列表”走向“技能体系”最早做Agent应用的时候我的做法和大家差不多把要调用的函数全部写在一个tools数组里然后在system prompt里写“你可以使用以下工具”让模型自己挑。前期demo跑起来确实挺唬人但一到真实场景就原形毕露工具一多模型开始选择困难工具描述写得不够细模型就开始瞎传参数某个工具返回报错模型不但不会处理反而会把报错当成知识告诉用户。后来我尝试过把工具说明改成更详细的文本比如给每个接口写上一大段用法提示结果prompt越来越臃肿token消耗上去了模型的准确率反而下降。这时候我开始反思一个根本问题我们到底是在给Agent“提供工具”还是在给Agent“培养技能”这两件事有本质区别。单一的工具函数只是能力的最小原子单元而技能是一个完整的、可复用的、带约束条件的执行单元。技能应该包含能力描述、参数定义、前置条件、执行逻辑、失败回退策略甚至还要有性能指标。agent-skills这个项目就是把这个思路落地的过程整套体系围绕“Agent能做什么、怎么做、什么时候做不了、做不了怎么办”来设计。1.2 技能与工具、插件、工作流的边界划分这里务必要把概念边界划清楚因为很多协作场景里大家沟通混乱就是因为几个术语说得不是一回事。工具Tool最底层的原子操作比如“查询汇率”“发送邮件”“读取文件”。一个工具一般只做一件事不涉及多步骤决策。技能Skill由工具组合而成的能力单元可能包含前置校验、参数加工、多个工具编排调用、结果格式化比如“完成一笔跨境支付”这个技能内部可能要调用汇率查询、账户校验、风控审核、支付执行等多个工具。插件Plugin更偏向于第三方能力的集成封装比如一个浏览器插件套件里面可能同时包含搜索、截图、读取页面等多个技能。工作流Workflow面向固定业务场景的流程编排流程是预定义好的Agent在里面主要负责按序执行。在我的项目设计里技能是核心抽象层级插件负责承载第三方集成工作流作为特定场景下的组合技能特殊形态。这个分层模型的好处是原子工具可以被多个技能复用技能可以做独立测试和独立版本管理而工作流不会和工具逻辑耦合在一起改一处崩全部。1.3 技能层到底解决了什么问题我梳理了一下技能层主要解决四类问题第一是感知清晰化。模型通过技能清单知道“我会什么”每个技能的描述要让模型在判断时不需要猜。第二是执行可靠化。每次调用有参数校验、超时控制、幂等设计、错误分类与回退策略不确定被视为可接受而不是直接崩坏。第三是组合复杂化。单个技能解决不了的问题可以通过编排层把多个技能串成执行链由Agent动态决策。第四是迭代工程化。技能可以独立发版、灰度、回滚评测集可以单独给每个技能打分不用每次整体回归一锅端。做过生产级Agent的人应该都懂这四个问题一旦解决整个系统的稳定性和可维护性会上一个台阶。接下来我逐个环节拆解实操细节。2. 技能定义与注册把“会什么”变成机器可读的结构2.1 技能清单一份让大模型不猜的说明书技能体系的第一步是给Agent一份技能清单。这份清单不是给人看的文档而是要被塞进模型上下文、让模型在每次决策时参考的说明书。因此它的设计目标只有一个降低模型的理解成本。我在agent-skills里把每个技能的生命周期分为注册、分发、调用、反馈四个环节而清单文件是注册环节的核心产物。一份技能清单通常长这样skills: - id: fx_quote name: 实时汇率查询 description: 查询指定货币对的实时汇率支持USD/CNY、EUR/CNY等常见货币对。当用户询问“现在美元兑人民币多少”“100欧元等于多少人民币”时使用。 category: finance version: 1.3.2 enabled: true author: trading-team contact: oncall-finance timeout_ms: 3000 tags: [finance, rate, realtime] parameters: - name: base_currency type: string required: true description: 基础货币代码ISO 4217三位大写字母 example: USD enum: [USD, EUR, GBP, JPY, HKD, CNY] - name: quote_currency type: string required: true description: 目标货币代码ISO 4217三位大写字母 example: CNY - name: amount type: number required: false description: 兑换金额如果提供结果会附带换算金额 example: 100 output_schema: type: object properties: rate: type: number description: 实时汇率 converted_amount: type: number description: 换算后的金额 updated_at: type: string description: 数据时间有人可能会问description写这么细致有必要吗我的答案是很有必要。control实验我做过不止一次同样是查询汇率这个技能描述写得含糊的时候模型经常在用户问“日元兑人民币”时错误地调用EUR/CNY把参数边界、枚举值、触发场景写清楚之后选错技能的频率直接下降了一个数量级。这里有个小技巧description里一定要写“什么时候用”用具体场景去触发模型的调用意图。别只是写“查询实时汇率”要写清楚“当用户询问当前汇率、换汇金额、跨境支付折算时使用”。模型判断的是语义匹配场景化描述比抽象描述好用得多。2.2 注册中心与技能发现机制技能清单本身是静态文件但生产环境里技能是动态演进的。我后面做了一步很重要的事情把技能清单从代码中拆出来单独做了一个技能注册中心。注册中心本质上就是一个带版本管理和健康检查的服务端存储。技能上线流程是这样的开发者在仓库里提交技能的YAML定义和实现代码CI跑完静态校验和单测通过之后注册中心更新该技能的版本索引。Agent启动或者配置刷新时从注册中心拉取最新的技能清单。这个机制让我解决了一个很让人头疼的问题prompt长度有限不可能把所有技能描述都塞进去。注册中心支持按领域分组、按标签过滤Agent层可以按会话场景动态加载对应的技能子集。比如闲聊场景只需要加载general类技能金融客服场景加载finance和customer_service类。技能发现变成了一次有索引的数据库查询而不是全量扫描。实测下来上下文占用能减少60%以上模型的选择准确率也同步提升——信息少了噪音就少了反例就会变少。值得一提的是技能发现还要处理版本兼容。老会话如果正在使用1.3.2版本的汇率技能新版本1.4.0上线时不能直接把旧会话的调用切到新版本否则可能出现参数不兼容。我的方案是在技能注册中心里维护一个会话级技能版本快照会话创建时锁定版本会话结束释放。这个机制避免了很多线上诡异问题尤其是长周期会话场景。2.3 技能描述分层的深层逻辑技能描述不能只靠一版文案打天下。我在实践中把技能描述拆成了三层第一层是一句话摘要给模型快读判断“这个技能和我当前任务相不相关”通常就是name加一句话description。第二层是结构化清单包括参数、枚举、输出、限制条件模型需要调用时再详细读取。第三层是使用手册包含调用示例、边界情况说明、常见错误码和回退建议这些内容平时不进入模型上下文只有Agent决定调用这个技能时才按需注入。这种分层思路借鉴了计算机体系结构里的多级缓存思想访问频率最高的摘要层数据量最小、加载最快参数和细节在需要时再paged in。如果你把所有技能的使用手册都塞在system prompt里上下文爆炸只是时间问题。实操层面我建议给每个技能配备一段usage_notes字段内容大概包括正确调用示例、常见错误示例、失败时的建议动作。这个字段不进技能摘要但它会在技能被选中之后作为system消息的一部分追加进上下文让模型在执行时“临阵磨枪”。有位做客服Agent的朋友试了这个方法后反馈参数传错的概率明显降低因为模型能看到“上个版本在这里犯过什么错”。3. 技能调用的三个关键环节3.1 路由分发如何让Agent选中正确的技能技能清单定义好之后下一个核心问题就是路由分发。这里说的路由不只是“让模型自己选”而是“让合适的技能以合适的方式被选中”。纯靠模型自由选技能结果往往不太可控——尤其是在几个技能边界模糊的时候。我的做法是引入了一个轻量级的意图路由器作为前置分发层。意图路由器本身是一个小模型或者分类器它先对用户输入做粗粒度意图识别把负载限定到2-3个候选技能上再把候选技能清单交给大模型做最终决策。举一个实际案例用户说“帮我查一下上周的销售数据然后画个折线图发到群里”。如果纯靠大模型从一百个技能里选它确实大概也能选对但延迟会高、token消耗会高而且偶尔会把“数据查询”和“报表发送”搞混。有了意图路由器前置筛选后候选技能直接被压到bi_data_query和bi_chart_generate两个大模型在这两个里做最终决定准确率和响应速度都有明显提升。路由分发还有一个细节容易被忽略技能冲突消解。有些技能功能上确实有重叠比如“查询订单物流”和“查询快递物流”用户说“我的快递到哪了”两个技能都触发。我建议在路由层为每个技能加一个priority字段重叠场景下默认选优先级高的同时在高优先级技能不可用时自动fallback到低优先级技能。这个设计很像DNS的优先级机制非常简单却非常管用。3.2 参数校验与兼容策略技能路由选对了下一步参数校验是重灾区。模型传参经常出现的问题有该传字符串的传了数字、枚举值拼错、时间格式不对、缺失必填项。这些问题如果完全交给模型自觉企业级应用是不敢上线的。我在技能调用管线上加了一道参数校验网关。所有模型传过来的参数先经过JSON Schema校验不合法就直接拦截返回结构化的参数错误码同时附上正确的参数格式说明给模型一次自纠错的机会。这个做法有两点好处一是避免脏参数打到下游业务系统二是给模型明确的反馈信号让它下次学会正确传参。校验之后还有一层兼容策略要做。有些模型在不同版本下对参数的格式理解不一样比如有的版本喜欢传中国货币符号“CN¥”而不是“CNY”有的会把时间直接传“明天”而不是日期字符串。我的做法是在参数网关里做格式规范化枚举值做映射、时间做标准化、金额做精度规整。经过这层处理的参数下游系统拿到的永远是干净统一的格式不需要每个业务系统各自做防御式解析。3.3 结果归一化与异常回退调用完成只是开始返回值能不能被模型理解才是真正的考验。我在项目里养成了一个习惯所有技能返回的结果必须经过归一化处理再交还模型。归一化包含两层意思。第一层是结构归一不管内部业务数据多复杂统一封装成{status, data, error_message, suggestion}结构。第二层是语义归一数据量大的时候给出模型友好的摘要比如查询一个月订单记录不能直接把几千条明细全塞给模型而是先统计出关键指标、挑出异常记录让模型基于摘要做回答。异常回退这块我最想分享的是**graceful degradation优雅降级**思维。技能调用失败不等于整个对话失败应该给技能配备多条降级路径。比如实时汇率接口超时了可以降级到缓存汇率缓存也没有就降级到告知用户“数据获取失败已使用最近一个交易日收盘汇率”。我遇到过这样一个事故汇率服务整体不可用由于实时接口和缓存接口走的是同一个上游缓存也拿不到数据当时Agent直接把错误信息原样抛给用户用户还以为是系统崩了。后来我设计了错误分类机制区分瞬时错误超时可重试、持久错误接口签名变了需人工处理、数据过期可用旧数据兜底。不同错误类型对应不同的回退动作。现在再遇到上游故障技能层会自动返回兜底数据并在回复里明确提示“当前为缓存数据”用户感知平稳很多。4. 技能编排从单体技能到组合执行4.1 技能依赖与执行顺序管理单体技能只能解决单点问题真实业务场景里Agent经常需要串联多个技能才能完成任务。比如“帮我查一下人民币对美元的汇率高于7.2就把上个月的营销预算表下载下来发到summer的邮箱”这个需求涉及汇率查询、预算数据下载、邮箱发送三个技能还有条件判断。如果每个技能独立调用、全凭模型临场发挥链路一长就容易断。技能编排层要解决的核心问题是依赖管理。我构建了一张技能依赖图每个技能声明自己的前置技能和输出依赖。编排引擎拿到任务后先做依赖分析生成一个可执行的调度计划。比如任务“汇率高于阈值则发送邮件”编排引擎会识别出三个技能节点其中发邮件依赖汇率判断的结果。调度计划就是并行执行汇率查询和预算下载等待汇率结果判断是否触发邮件发送。这种显式的依赖声明确保了执行路径可预测、可追踪、可回放而不是黑盒地靠模型自由发挥。4.2 上下文与中间结果的传递策略技能编排最容易被忽略的是中间结果传递。技能A输出的数据往往是技能B需要的输入参数如果设计不好每执行一步都要请模型重新理解和抄写上下文容易抄错不说还会累积token开销。我采用的方案是共享上下文总线。每个技能的输入输出结构都注册到总线上技能B声明requires: skill_A.output.rate编排引擎在执行完技能A后自动把rate字段提取出来填入技能B的参数。这个过程中模型不需要介入做信息搬运传递通过结构化的数据流完成准确率和效率都提升明显。做过账务系统的朋友应该能直接联想到ETL管道技能编排本质上就是面向Agent执行的语义级ETL只不过输入不是数据库表而是用户的开放域意图。这里我建议一开始就建立起每个技能输入输出schema的版本管理不然编排链路成熟之后改一个技能的出参格式下游十个技能的测试都得跟着重跑。4.3 并发、超时与重试机制编排引擎的调度策略直接影响用户体验。有些场景可以并行有些场景必须串行还有的场景要做条件分支和循环。我踩过不少坑总结下来有三组参数最值得好好配置超时控制每个技能都必须有独立超时时间不能全都默认等5秒。查询类的控制短时间生成报表类可以给更长时间。总编排超时也要设置上限避免用户等了半天才收到“操作失败”。重试策略瞬时错误才允许重试重试次数建议不超过2次。持久错误直接走降级路径不要闷头重试浪费资源。并发限制同一个会话内不要无限制并发技能尤其是涉及写操作和第三方接口调用时要给并发度设一个上限。我一般把默认上限设为3避免一次多技能并行把下游系统打崩。有条件分支时编排层一定设计成静态声明动态选择的机制。静态声明所有可能的分支路径动态选择根据技能的返回结果判断走哪条分支。AI不是actuator但有时候我们需要给模型足够的确定性护栏这个机制就是给“模型做决策”这件事加一个轨迹记录仪出了问题能回溯路径。5. 评测与调试技能体系的工程闭环5.1 技能级评测集的设计很多Agent项目号称做了测试实际上就是拿两三个用户问题跑一下人工看看反馈出问题了大眼瞪小眼。真正能撑住迭代节奏的技能体系必须有技能级的自动化评测集。我给每个技能建立了一套三层的评测用例集功能层这个技能在正常参数下能不能返回正确结构的结果。针对汇率技能就测USD/CNY、EUR/CNY、异常币种代码写死断言跑CI自动校验。语义层用真实用户说法测技能选择是否准确。例如“美刀对人民币多少”应该路由到汇率技能而不是货币转换之类的其他技能。对抗层构造边界和恶性输入例如用户问“人民币兑美元但没给金额”或“查询三个货币对的汇率”看技能是否能优雅处理或引导澄清。刚开始做评测集时会觉得很费功夫但这是硬投资。一套扎实的评测集让后续每次技能改动都能在几分钟内得知有没有破坏原有能力。我把这套方案跑通之后迭代效率至少快了一倍因为敢改了——跑完评测集心里就有底。5.2 重放式调试与日志追踪Agent技能调用链路太长出了Bug都很难复现。用户说刚才某个回答不对你把当时的prompt、参数、上下文全都丢了上哪查去所以我在项目里从一开始就强制要求全链路trace记录。每条Agent请求都会生成一个trace_id从用户输入、意图识别候选、路由选择结果、技能调用参数、下游响应、编排分支记录到最终输出全部以结构化日志形式落盘。调试时只要拿着用户的反馈定位trace_id直接重放当时的上下问和参数就能在本地把问题复现出来。重放式调试还有一个高级玩法把用户线上真实问题和好答案做成回归样例库每天用最新代码回放一遍。有次我调整了某个技能的prompt模板自以为效果变好了结果重放测试发现三个老场景全部翻车——如果不是有这个自动重放机制这个问题至少会在线上潜伏一两周才被用户撞见。日志追踪的字段设计建议遵循一个原则凡是运行时要判断问题的依据都要记。不要心疼存储一次故障定位的成本远超几天日志的存储费用。后来进一步做了可视化的trace链路面板可以将每条请求的技能调用路径用瀑布图展示对排查编排类问题帮助很大。5.3 安全与权限Agent技能的红线技能可以访问数据和执行动作权限设计如果不到位整个系统就是裸奔状态。做Agent技能安全我有几条铁律第一技能权限最小化。每个技能只申请自己必要的权限范围比如“发送邮件”技能只具备指定收件人发送的权限不允许任意修改收件人列表。技能运行在独立的沙箱或服务账号下不共享管理员权限。第二输入输出双向过滤。输入侧要拦截prompt注入类攻击恶意提示词试图诱导Agent执行未授权的技能时输入过滤器要能识别并拦截。输出侧要防止数据泄露比如技能查询结果里包含敏感字段归一化阶段就完成脱敏模型拿到的永远是脱敏后的数据。第三敏感操作二次确认。涉及资金、权限、对外发布类操作编排层必须配置human-in-the-loop确认节点。技能执行到这一步会暂停等人工确认通过后继续执行。这在B端场景里特别重要既保护了用户资产也保护了Agent开发团队。第四全量审计日志。所有技能调用记录至少保留180天关键的财务或者权限操作保留更长时间。审计日志不可篡改出了问题支持追责和复盘。安全这块宁可过度设计不要亡羊补牢。6. 踩坑实录从技能崩坏到稳定运行6.1 高频问题速查表最后这部分我把这一年多实操中遇到的高频问题整理成一份速查表每个问题的症状、原因和解决方案都直接对齐希望帮你节省排查时间。问题常见原因解决方案模型总是选错技能技能描述太抽象缺少场景触发词在description里补“当用户说X时使用”句式参数总传错格式参数schema缺少枚举和示例参数定义加enum和example网关做格式规整调用报错但用户感知为“系统卡死”异常直接抛给模型无回退策略统一错误分类搭缓存兜底和降级路径污编排链路一长就断依赖关系没有显式声明建技能依赖图编排引擎生成调度计划技能升级后老会话不正常版本变更没有做会话级隔离会话启动时锁定技能版本快照上下文越来越臃肿技能全量描述重复注入做三级技能描述按需加载手册级内容并发调用把下游打爆并行度没有限流编排引擎限制会话内技能并发上限线上问题无法定位链路日志缺失全链路trace落盘结构化管理6.2 三条最值得记住的实战经验第一技能描述决定Agent的天花板。很多人以为模型能力是瓶颈实际跑下来发现大多数失败源于技能描述不清导致模型理解偏差。打磨描述文案投入的每一分钟都会直接体现在线上成功率上。第二评测集不是可选项。我可以很坦白地说没有技能级评测集的时候我根本不敢乱动线上技能配置。自打建好“功能层语义层对抗层”的评测集之后技能迭代从“如履薄冰”变成了“常规操作”。这块硬功夫越早做越省钱。第三编排要可视化。技能调用链路一旦超过三个节点光靠日志文本已经很难看清全局了。把每个会话的技能调用路径像工单一样展示出来——哪些并发、哪些串行、哪个环节超时、哪一步走了降级——问题一步定位不需要从头猜。可视化这块看起来像做产品功能实际上是在救开发者的命。最后再分享一个小技巧给每个技能加一个“自检模式”。自检模式下技能会用特殊标记参数模拟一次完整执行返回链路中每个环节的耗时和结果。新技能上线前先跑一遍自检再放给真实用户很多低级问题在自检阶段就暴露了不用等线上反馈。这个习惯帮我拦下了至少六成上线后的回归问题强烈建议做成技能开发流程的固定一步。