做了一段时间的Agent开发我最深的体会是别急着堆功能先把技能系统设计好。很多朋友拿到一个agent-skills项目要么一头扎进提示词工程要么上来就接十几个API结果智能体在demo里很惊艳一上真实场景就失灵。Agent的技能体系恰恰是决定它能不能从能聊变成能干活的关键。这篇文章我会从技能的定义标准、注册路由机制到具体的实操案例和排错经验完整拆一遍怎么搭建一套扛得住真实业务的Agent技能系统。适合正在做智能体应用、想把手里的LLM能力真正工程化的开发者参考。1. 先想清楚Agent技能系统的设计逻辑1.1 为什么Agent需要一套独立的技能体系不管你是用LangChain、AutoGen还是自己写编排框架只要涉及到让Agent完成实际任务就一定会遇到一个问题模型本身的知识和能力有限光靠对话和Prompt无法稳定地完成查天气、算数据、调接口、生成报表这类具体动作。打个比方。一个刚入职的实习生你说帮我把这个月的数据整理一下他大概率手足无措。但如果你给他一套明确的岗位SOP手册告诉他遇到什么情况用哪个流程、需要哪些输入、输出长什么样他就能稳定执行。Agent的技能就是这个SOP手册。没有技能的Agent面对复杂指令只能胡猜有了技能它才知道遇到什么情况该掏出什么工具、按什么流程做事。这里要区分两个概念工具调用和技能。工具调用是单次动作比如调用天气API技能则是意图识别、参数解析、动作执行、结果格式化的完整闭环。很多新手以为把函数列表塞给模型就算完事实际上模型确实能把函数调用出来但调用完干什么、结果怎么处理这些环节没有系统的约束输出就很容易翻车。技能体系解决的正是这个完整链路问题。1.2 三类核心技能基础、领域、编排我习惯把技能分成三个层次方便管理也方便复用。基础技能是通用原子能力比如文本摘要、关键词提取、格式转换这类技能不依赖特定业务场景几乎任何Agent都用得上。领域技能是针对具体业务场景封装的能力比如生成电商周报、解析简历、查询订单物流状态这类技能跟业务数据强相关。编排技能是把多个技能按规则串起来比如经营复盘技能可能内部调用了数据查询、异常检测、报告生成三个基础技能。分层的价值在于基础技能可以跨项目复用领域技能可以按业务模块独立迭代编排技能则对应复杂任务的工作流。修改底层技能的实现时只要接口不变上层编排不用动。这套设计让技能库可以像搭积木一样按需组合而不是每来一个新需求就把原来的代码推倒重来。1.3 技能设计的四个核心原则设计技能时我踩过不少坑最后沉淀下来四条原则。单一职责。一个技能只做一件事。不要设计一个全能处理技能因为它既难描述清楚触发条件也容易让模型产生路由混淆。参数最小化。能由模型从上下文推断的字段就不要让用户额外提供。比如技能内部可以根据时间自动确定本周的起止日期就不需要用户手动输入。可观测。每个技能都应该有日志记录记录被哪些意图触发、传入了哪些参数、执行是否成功、耗时多少。没有可观测性的技能体系出问题时根本无从排查。渐进增强。先跑通主干流程再逐步给技能增加边界处理。一上来就想把边缘情况全覆盖技能还没上线维护成本先把人压垮了。2. 技能定义的标准化结构一个技能到底包含什么2.1 技能定义的核心字段拆解要把技能变成机器可以识别和调用的资产得定义一套统一的结构。我目前使用的技能定义包含六个核心字段技能名称、描述信息、参数Schema、执行流程、输出Schema、约束条件。技能名称要短且语义明确比如daily_briefing、calc_expense别用含糊的process_data这种名字。描述信息是整个定义里最关键也最容易写差的部分它直接决定模型能不能在正确时机触发这个技能。参数Schema沿用JSON Schema的写法明确类型和约束。执行流程是技能真正干活的逻辑可以是调API、跑Python脚本也可以是嵌套调用其他技能。输出Schema规定了返回结果的JSON结构保证下游处理的稳定性。约束条件则写明技能的适用范围和副作用比如该技能只接受UTC时间格式、调用该技能会写入数据库。2.2 描述信息怎么写才能提升命中率有段时间我排障排到头秃后来发现90%的技能路由错误都出在描述写得太抽象。比如一个查询账单的技能描述写的是查询用户的账单信息模型在用户说我这个月花了多少钱时常常不触发因为花费和账单这两个词在语义上没被映射起来。踩过几次坑之后我的描述写法改为三段式触发场景、功能声明、负面提示。触发场景用当用户想要...时触发把能想到的自然语义都列出来比如当用户想了解本月消费、查账、核对账单、询问开销明细时。功能声明说明技能能做什么、输入输出是什么。负面提示同样重要写明当用户在讨论账单分期规则、提问政策条款时不要触发这一条能显著降低误触发率。实测下来加上负面提示之后路由准确率能从75%提到90%以上。2.3 参数Schema的设计细节与常见坑参数设计看起来简单实际上最考验经验。先说必填与可选模型不是万能的用户说帮我查订单时没给出订单号你要么把订单号标为可选并设计默认值要么在参数缺失时走追问流程但不能既标必填又没有默认兜底。其次是类型与格式日期字段如果用字符串建议明确写format: YYYY-MM-DD否则模型可能给你四种不同格式。枚举值字段要列全合法值比如[day, week, month]不要只写时间范围让人猜。最后是依赖关系参数A依赖于参数B的场景需要在Schema的dependencies字段里声明否则模型会传出一个缺少前置条件的组合。这里分享一个技巧给每个参数补充一个description告诉模型这个参数应该从用户哪句话里取。比如开始时间参数可以写优先从用户提到的日期中解析未提及时取本周一0点。参数描述越具体抽取越准。3. 技能注册与路由让Agent学会在合适时机出手3.1 技能注册表Agent的能力清单技能定义好了之后需要一个统一的地方登记造册这就是注册表Registry。注册表本质上是一份结构化的技能清单供路由模块在运行时检索。我建议把注册表做成一个独立的JSON文件或数据库表不要硬编码在代码里。注册表至少包含技能ID、名称、描述、参数Schema入口、执行入口、版本号、启用状态。版本号这个字段一定要有我在上线新版本技能后发现效果回退想回滚旧版本因为没有版本号管理而回滚困难那次之后所有技能都强制带版本。注册表的另一个用途是控制能力边界。给Agent配技能时不是越多越好而是按场景漏斗收敛。比如一个客服Agent只注册5个与售前咨询相关的技能就好注册一个写诗技能反而会干扰路由判断。我的经验是一次注册给Agent的技能数控制在20个以内这样可以有效保证路由准确率。技能数量上来之后路由模型的注意力会被稀释容易选错。3.2 路由机制选型LLM路由还是语义路由技能路由就是决定当前用户请求该调用哪个技能。市面上主流有三种做法。第一种是LLM路由把技能注册表的描述信息塞进Prompt让模型返回技能ID和参数。这种方案的好处是能处理复杂语义坏处是Token消耗大、延迟高。第二种是语义路由用Embedding计算用户输入与技能描述之间的相似度取Top K。第三种是混合路由先用语义路由缩小候选范围到3到5个再让LLM精确判定。我实际推荐混合路由。第一步全量技能先用向量相似度召回Top 5候选这步很快且便宜第二步把5个候选技能的详细描述交给LLM做精确选择和参数抽取。这套方案兼顾了准确率和成本。如果是OpenAI系模型直接走Function Calling做LLM路由也很稳如果用的是开源模型本地部署混合路由是性价比最高的方案。3.3 技能编排串行、并行与条件分支当任务需要多个技能协作时编排逻辑就要上场了。最简单的编排是串行比如用户要日报触发daily_briefing内部先fetch_news再summarize最后format_markdown前一个输出是后一个输入。串行适合场景固定、步骤清晰的流水线。并行编排适合多个技能互相没有依赖的情况比如生成一份市场分析报告时可以同时调用竞品信息采集和行业趋势查询两个技能并行执行再合并结果。这里注意并行调用多个LLM技能时Token消耗会成倍增长建议只在真正独立的读者分支上使用。条件分支最灵活也最难调比如如果用户输入包含订单号则查订单否则查库存。这种逻辑可以用规则引擎硬编码也可以交给模型判断。我的建议是把稳定不变的分支写在代码里把开放语义的判断交给模型不要全部依赖模型做逻辑判断否则一旦模型抽风整个流程就断了。4. 实操案例从零实现一个AI日报技能4.1 需求拆解日报技能到底要做什么纸上谈兵没用我拿一个真实的案例来走一遍全流程。假设你要给Agent加一个AI日报技能用户对Agent说帮我生成今天的AI行业日报Agent需要能够抓取当天AI相关的资讯列表、对每篇文章做摘要、按主题聚合输出一份结构化的日报。拆解下来这个任务可以分解成三个子技能fetch_news采集内容、summarize_text生成摘要、format_report生成日报模板。为了保持示例完整我直接用一个复合技能daily_briefing来封装这三个步骤。先定义技能的JSON Schema{ skill_name: daily_briefing, description: 当用户想要生成当日AI行业日报、晨间简报、获取AI领域要闻汇总时触发。该技能会采集资讯、生成摘要并以结构化日报形式输出。当用户仅询问单条新闻细节或要求实时聊天时不要触发。, parameters: { type: object, properties: { date: { type: string, format: YYYY-MM-DD, description: 日报对应的日期优先从用户输入中提取缺省取当前日期。 }, topics: { type: array, items: { type: string }, default: [大模型, AI应用, 智能体], description: 日报聚焦的主题领域从用户输入中提取缺省使用默认主题。 } } }, execution_flow: fetch_news - summarize_text - format_report, output_schema: { type: object, properties: { summary: { type: string }, items: { type: array, items: { type: object, properties: { title: { type: string }, source: { type: string }, summary: { type: string } } } }, trends: { type: array, items: { type: string } } } } }这里有几个细节需要说明。description里的负面提示我写上了当用户仅询问单条新闻细节时不要触发这个会让路由准确率明显提升。topics参数设了默认值模型在用户没有明确指定主题时不会报错。output_schema里固定了summary、items、trends三个字段这样下游不管是推送给用户还是渲染成页面数据结构都是稳定的。4.2 执行流程实现从抓取到格式化实现daily_briefing时我不建议把一个技能的所有逻辑都塞进一个函数里而是让daily_briefing作为编排入口内部调用子技能。fetch_news负责根据topics生成搜索关键词然后请求资讯API比如通过RSS聚合或者搜索服务的返回拿到候选文章列表。这里有个经验拿到列表后不要全量处理先按时间倒序取前20条再做一个去重关键词相同、标题相近的文章手动过滤掉不然摘要环节会浪费大量Token。summarize_text对每篇候选文章截取正文前后文用一个小模型做摘要控制每条摘要不超过80字。如果文章数量多了就做个排序把来源权威、发布时间新、跟主题匹配度高的放前面。format_report把摘要结果填入固定模板生成最终日报。下面是一段简化版的核心逻辑我用Python伪代码风格写出来def daily_briefing(date, topics): # 1. 采集候选文章 candidates fetch_news(date, topics, limit20) # 2. 去重裁剪压缩处理范围 candidates dedup_and_rank(candidates, max_count10) # 3. 逐条摘要 summarized [summarize_text(item) for item in candidates] # 4. 聚合趋势判断 trends extract_trends(summarized) # 5. 格式化输出 return format_report(summarysummarized, trendstrends)4.3 集成测试与路由验证技能实现完之后最重要的一步是验证路由和参数抽取是否正常。拿几个常见说法做测试用户说今天AI圈有什么大事Agent应触发daily_briefingtopics取默认值用户说帮我出一份昨天关于智能体和机器人的简报Agent应触发技能且topics自动解析为[智能体,机器人]date取昨天用户说这篇文章讲了啥Agent不应触发日报技能而是走通用对话或者其他技能。我习惯在测试阶段把路由日志打开。每条用户输入记录触发候选的Top 3技能和得分这样能看到模型在犹豫什么。有一次测试发现用户说来一份早报时模型同时把daily_briefing和另一个weather_report都拉进了候选最后因为描述里的晨间简报字面更近误触发了天气技能。后来我在daily_briefing的描述里补了一句用户提到早报、晨报、行业动态时触发不涉及天气和出行再测就正常了。这再次印证了负面提示的重要性。5. 故障排查与效果调优实录5.1 高频问题技能误触发与路由摇摆技能系统最常见的故障就两类该触发的没触发不该触发的误触发。该触发没触发多半是描述里缺少用户实际口语的映射比如用户说报一下昨天的数描述里只写了查询数据报表语义鸿沟太大。这时把用户历史里真实出现过的说法收集起来定期反哺到技能描述里。不该触发却触发一般是技能描述太宽泛或者多个技能描述重叠。比如同时有周报生成和工作总结两个技能用户说写个总结就可能在两者之间摇摆。解决办法是优先在描述里做区隔两个技能分别强调各自的专属场景实在区隔不开就合并成一个技能用参数区分工作类型。记住一个原则技能边界模糊时优先合并不要靠模型硬扛。5.2 参数抽取与输出格式的稳定性问题参数抽取出错也是常见问题。模型经常把下周解析成下周而不是本周或者把日期格式搞成07/04/2025而不是2025-07-04。我的做法是在参数Schema的description里明确写法规则并在执行流程的第一步跑一个参数校验函数不满足格式时自动按规则修正修正不了再走追问流程而不是把坏参数直接传给下游接口。输出稳定性几乎是所有Agent项目的痛点。LLM生成JSON经常出现多一个逗号、字段名大小写不一致、数组嵌套层级错乱。我踩过几次坑后统一做了三件事第一所有结构化输出都用输出Schema定义并让模型按固定模板返回第二增加一层解析容错遇到非法JSON时先尝试修复而非直接报错第三解析失败重试时把错误信息回传给模型让它知道自己哪里错了重新生成。实测这套流程能把结构化输出的成功率从80%拉到98%。5.3 性能与成本调优的五个方向技能系统上线之后性能和成本往往成为瓶颈。我总结了五个调优方向。上下文裁剪。给模型看的技能描述不要太长每个技能的描述控制在200字以内描述精炼对路由准确率反而有帮助。模型输入的技能列表只保留必要的Schema不要全量塞入。缓存复用。用户经常查询的热门数据比如早报、周报可以按日期做缓存同一份内容只生成一次。小模型分流。摘要、提取关键词这些简单任务用小参数模型执行只有复杂编排和最终决策用大模型。并行化。独立技能之间用并行调用替代串行调用能把总延迟降到原来的三分之一。监控告警。统计每个技能的调用成功率、平均延迟和Token消耗一旦出现异常及时回滚。这五条落实下来我实际项目里的成本下降了约40%响应速度提升了一倍多。5.4 技能迭代与回归测试的实操方法技能不是写一次就完事的它需要持续迭代。但要小心一个问题优化一个技能的路由表现时可能连带影响其他技能的路由。我做过一次改动把某个技能的描述扩充了很多结果把另一个相似技能的调用量挤掉了一半。从那以后我建立了一套简单的回归测试集把过去一个月里真实的用户输入样本收集起来每次修改技能定义后都跑一遍统计路由命中率和参数抽取命中率。这套回归测试集规模不用大300条覆盖各技能类型的样本就够用了。跑一次只要两分钟但能挡住绝大多数回归问题。结合我的经验技能系统做得好的标准不是技能的数量多而是路由的准确率稳。先保证20个以内技能的路由稳定、参数抽取干净、输出格式可控再考虑扩展场景。等新场景积累多了再按业务域拆分新的Agent让每个Agent的技能集更聚焦整体反而更好维护。