在搞大模型应用落地的时候我见过太多的半成品Agent项目了演示视频一个比一个亮眼一上真实业务场景就哑火。绝大多数问题并非模型能力不够而是“脑子”里根本没有一套可复用、可编排、能被语言模型稳定调用的技能包。说白了就是没把“agent-skills”这个基础层做扎实。所谓agent-skills我给出的定义是面向大模型智能体Agent封装的高度结构化、具备输入输出约束、可被模型在推理过程中动态触发的原子能力集合。它跟传统软件的函数库大不相同函数的签名和类型是给编译器看的Agent技能则是给大模型的上下文窗口看的。一份好的技能必须让模型在一两次推理内就能判断“该不该调、怎么调、结果怎么反馈”。这篇文章不会去整那些花哨的概念理论我直接把我自己在这个方向上的完整思考、设计取舍、踩坑过程以及最终稳定下来的实操方案全部摊开来讲。项目代号就叫“agent-skills”你可以直接把它当作一份可复现的工程笔记来读。1. 整体设计与思路拆解把“模型能力”变成“工程能力”1.1 为什么要专门抽象一层技能而不是让模型随手写代码很多人一开始会把“Agent能调工具”和“Agent具备技能”混为一谈。这里有个本质区别能调工具说明函数有入参出参具备技能意味着模型能理解这个工具在什么业务场景下使用、输入该带什么格式、输出如何处理、失败之后如何降级。举个例子业务方要求Agent查一个销售数据看板。写一个查询函数当然不难但Agent面对的是模糊需求“帮我看看最近卖得怎么样。”如果只有查询函数模型需要自己去猜维度、猜时间范围猜错概率很高。但如果把它包装成一个“TrendAnalysis”技能技能描述里写明“适用于销售趋势汇总与波动归因”输入参数明确给出时间口径、指标维度、粒度选择输出结果要求以JSON格式返回同比与环比模型在做规划时就会把这当作一个完整“能力单元”来调用效果完全不一样。所以这套设计的第一准则就是技能是连接模型意图与外部系统的语义契约这个契约要足够机器可读但更得足够模型可读。这跟面向对象设计有点类似但服务的对象是模型而不是程序员。1.2 三层技能架构基础原子、业务编排、跨域路由我在构建agent-skills时没有把大中小技能堆在一个平铺目录里而是划分成三层。原子技能层Atomic Skills负责单点能力的封装。典型的如“查天气”“发邮件”“读数据库”输入输出高度标准化不掺入任何业务逻辑。编排技能层Orchestration Skills由多个原子技能组合而来负责处理一个相对完整的业务流程。比如“新客户自动开户流程”需要依次调用资质核验、OCR证件提取、客户管理系统插桩、欢迎信发送。路由技能层Routing Skills这是一种特殊的技能本身不执行业务它负责根据用户请求判断后续路由到哪个编排技能或者原子技能组合。模型天生擅长分类与判别给它一个清晰的“技能路由表”能够显著降低误调用的概率。这三种技能在工程上会落地成不同的文件与描述模板模型通过一套统一接口来感知它们的差异。在设计阶段就明确它们的边界省去了后头大量互相打架的麻烦。1.3 一个让我反复推翻又改回来的设计技能描述必须“人话优先”刚开始做agent-skills时我把技能描述写得和传统的OpenAPI文档一样通篇是以接口参数为核心的说明结果模型的表现并不理想。后来对比分析才发现模型在函数调用模式下对“参数名”、“类型”这些信息敏感度很高但对技能层的元信息比如使用场景、成功标准反而出奇的看重。我做过一组对照实验相同的查询数据库技能第一版描述是“execute_sql(sql_string) 执行SQL查询并返回结果”。第二版描述是“本技能适用于数据分析师用户提出任意数据查询需求时输入合法的SQL语句技能会执行查询并返回结果集如果SQL语法错误则返回错误提示且不会执行任何写操作”。同一个评测集后者在任务完成率和意图匹配准确率上分别提升了大约8个点和17个点。这给我的经验是写技能的元描述时把它当作用户说明文档来写而不是接口文档。模型虽然是对概率的拟合但它需要足够自然的语义线索来触发正确的技能。这个认知贯穿了后续全部设计也建议你一开始就接受它。2. 核心细节解析与实操要点技能定义、参数契约与提示词完整解构2.1 一个标准Agent技能定义里必须包含哪些字段技能定义文件是整个功能落地的关键我把自己的技能模板拆解开看大致包含七个核心字段。每个字段都有其不可替代的意义。字段作用设计要点skill_name技能唯一标识符命名必须语义明确且自成体系我习惯使用名词短语如database_retriever避免使用短横线和编号后缀description给模型的自然语言说明需写清适用场景、不适用场景、输入要求、失败返回样式input_schema入参的形式化定义JSON Schema属性名尽量写全称避免缩写output_schema出参形式定义同样使用JSON Schema要求模型按预定结构消费返回信息prompt_template实际执行时注入模型的原生提示词不只是一个静态模板需预留上下文注入点供编排层填充allowed_tools允许该技能内部调用的工具白名单这是安全边界的重要实现方式也减少无效工具对模型决策的干扰error_handler技能执行失败时的降级处理策略可以是规则表达式也可以是另一个技能的名称每个技能文件我都会配套两个额外文件一个是examples.yaml放两到三组典型的调用输出示例另一个是tests/目录下的单元测试用例用模拟数据跑一遍技能的调用成功率。不要小看这些辅助文件它们承载的是“连贯性的基准”让技能质量的回归成为一件有依据的事。2.2 参数契约设计的两条铁律显式优先与默认值兜底在设计输入参数时两条铁律一定要刻在脑子里。第一入参最好显式化。不要指望Agent自己补全背景信息。比如一个“天气查询”技能你定义参数city必填模型就会主动去问用户是哪个城市。如果你定义city可空模型会在用户没提时直接传一个空值或者瞎猜一个这非常可怕。所以凡是业务上必须有的信息统统设成必填。第二接口要有默认值兜底。比如查询时间范围很多实际的业务场景都有默认口径。你在参数定义里写明time_range为可选默认是“近7天”模型在不确定时就会直接使用默认值不会反复追着用户问交互体验流畅一个量级。配合output_schema中的枚举约束还能降低模型自由发挥的空间。我踩过的最严重一次坑是在某个模拟客服项目中把user_name参数设为可选模型每次都要询问用户姓名而业务上这个字段在大多数场景根本不需要。后来把该参数从入参中删除改为在技能执行前通过系统上下文里的会话信息自动注入问题迎刃而解。因此你也要认真审视哪些参数应该由用户告诉模型哪些应该由系统直接注入不要把这两类混在同一个schema里。2.3 编写技能提示词的经验技巧别让模型猜测你的意图技能内部的prompt_template与系统提示词风格不同它更像一个局部限定环境。我的写法一般包含四个段落角色与边界说明、执行步骤序列、输出约束、检查清单。下面是一段我封装“技能编排引擎内部逻辑检查技能”时用到的模板已脱敏处理保留核心结构你现在是一个技能自检器。你要分析用户给定的技能描述与输入输出样例 判断该技能在以下三个维度上是否成立 1. 意图匹配度技能描述是否清晰是否存在可能被其他技能误触发的模糊表达。 2. 参数完备度输入参数是否覆盖所有业务必备信息是否存在隐含依赖。 3. 输出可用性输出schema是否能被下游步骤直接消费是否包含行数、状态码等必要元信息。 如果发现任一维度不达标请给出具体修改建议并指明是描述、参数还是输出结构的问题。 不要修改代码只输出分析和建议。类似这种“元技能”在实际项目中的价值极大。Agent不仅可以执行业务任务也能对这些技能本身做检查。稍微延伸一步你甚至可以做一个“技能修正Agent”每次技能执行失败或被用户投诉时自动进入诊断模式输出修正建议再由开发人员确认。这套机制一旦跑起来技能库的维护成本能下降一大截。2.4 给技能加上版本与淘汰机制技能不是一次写完就一劳永逸的。大模型的能力在迭代业务语义也在变化。我对每个技能都会维护一个版本字段并且在技能变更后进行回归试运行确保影响范围内没有其他技能被带崩。很长一段时间里我都在思考“什么时候该淘汰一个技能”而不是“什么时候该加技能”。淘汰的依据往往是调用日志。如果一个技能连续两周调用成功率都很低或者调用次数少到可以忽略就应该审视它的存在价值。我习惯保留一个retired目录而不是直接删除这样一旦业务场景复发随时可以恢复而不是从头再写一遍。3. 实操过程与核心环节实现从零搭建一个可运行的Agent技能库3.1 技能库目录规范与加载逻辑规范的目录结构能极大降低后续的维护负担。我的agent-skills项目目录如下agent-skills/ ├── atomic/ │ ├── data_query/ │ │ ├── SKILL.md │ │ ├── schema.json │ │ ├── prompt.md │ │ ├── examples.yaml │ │ └── tests/ │ └── text_process/ ├── orchestration/ │ ├── customer_analysis/ │ │ └── skill.yaml │ └── report_generation/ ├── routing/ │ └── super_router/ ├── shared/ │ └── error_handlers.py ├── loaders/ │ └── yaml_loader.py └── registry.json每个原子技能至少包含上文提到的SKILL.md和schema.json。registry.json是技能注册中心记录了所有技能的名称、版本、位置、依赖关系、启用状态。加载时我的工具函数会依次读取registry.json将每个技能解析成一个统一的技能对象放进内存池。这种设计的最大好处是重启加载非常快并且可以热插拔。用Python实现一个简化的技能加载器可以参考下面这段代码已简化便于理解import json from pathlib import Path class SkillRegistry: def __init__(self, registry_path: str): with open(registry_path, r, encodingutf-8) as f: self.registry_data json.load(f) self.skills {} def load_all(self, base_dir: Path): for entry in self.registry_data[skills]: skill_path base_dir / entry[path] skill_obj self._parse_skill(skill_path, entry) self.skills[skill_obj.name] skill_obj return self.skills def _parse_skill(self, path, entry): # 实际代码会解析 SKILL.md 与 schema.json # 此处示意结构 return { name: entry[name], version: entry[version], path: path, description: (path / SKILL.md).read_text(encodingutf-8), input_schema: json.loads((path / schema.json).read_text(encodingutf-8)) }3.2 一个完整示例设计“销售数据趋势分析”编排技能为了让你直观感受到从零搭建技能库的流程我拆解一个我在某模拟经营分析系统里做过的编排技能“销售数据趋势分析”。它由三个原子技能组成sales_query查询原始销售数据、stats_calculator计算同比环比、plain_text_generator生成自然语言摘要。首先在registry.json中注册该技能{ name: sales_trend_analyzer, version: 2.1.0, type: orchestration, dependencies: [sales_query, stats_calculator, plain_text_generator], path: orchestration/sales_trend_analyzer, enabled: true }其次编写SKILL.md的描述部分。这里的关键是写明“什么情况不适用”技能销售数据趋势分析 用途当用户询问销售表现、增长下降趋势、某区域或某产品线的销售波动原因时调用本技能。 不适用场景如果用户只是查询单个订单或单个客户的成交详情请直接调用sales_query不要使用本技能。 流程 1. 根据用户诉求补充时间范围、粒度周/月/季度、维度产品线/区域/渠道。 2. 调用sales_query获取原始明细数据。 3. 调用stats_calculator计算环比、同比以及贡献度。 4. 调用plain_text_generator生成趋势摘要。 输出要求返回结构化数据段含统计指标与自然语言摘要段。再来定义schema.json中的入参{ type: object, properties: { time_range: { type: string, enum: [last_7d, last_30d, last_90d, last_year], description: 分析时间段默认last_30d, default: last_30d }, granularity: { type: string, enum: [day, week, month], description: 统计粒度默认month }, dimension: { type: string, enum: [product_line, region, channel, overall], description: 分析维度默认overall } }, required: [] }实际开发中我会把required设为空数组因为所有参数都有默认口径模型可以根据对话历史自行判断。但我的默认值设计得足够合理就算参数全部为空也能跑出一个总体趋势概览。3.3 让模型正确触发编排技能路由配置是关键有了技能还不够Agent得能定位到它。我在routing层做了一个叫做“超级路由”的技能它本质是一个分类器。每当模型收到用户请求时先经过路由层的检索匹配再决定要不要进入某个业务技能。路由配置使用一种语义描述数组routes: - skill: sales_trend_analyzer trigger_patterns: - 销售 - 增长 - 下降 - 同比 - 环比 - 哪个产品线最好 avoid_patterns: - 单个订单 - 客户详情 - skill: customer_profiler trigger_patterns: - 客户画像 - 偏好分析 - 消费习惯路由层不直接输出完整技能执行计划它更像是给技能加了个“门卫”。这样做的直接收益是多个技能描述相似时模型不会被高相似度的文本干扰同时avoid_patterns的设定可以拦截很多不该触发的情况显著降低错误调用率。3.4 调用链路实践技能执行中的故障转移当一个编排技能内部的原子技能执行失败时直接报错是最愚蠢的做法。我在所有编排技能的末尾都放了一个异常出口核心思路只有一条降级不失败。举个例子在某次模拟分析中sales_query因源数据库连接异常而失败导致后续计算一并进行不下去。我设计的错误处理器会自动切换到缓存库查询如果命中缓存则直接继续如果没有缓存则生成一份“数据暂不可得”的叙述性结果并给用户提示请稍后重试。为了支撑这种降级逻辑每个编排技能都带有一份fallback_chain.yaml声明技能的备用数据源和兜底输出模板。fallback_chain: - try: cache_query on_failure: next - try: summary_without_data output: 暂时无法获取最新数据请稍后重试这条链路的价值在于用户感受到的是“系统在努力处理”而不是“系统崩溃了”。Agent项目跑业务时稳定性感知比花哨能力更能积累信任评分。4. 常见问题与排查技巧实录Agent技能跑不稳的根源在哪4.1 问题一模型始终不调用指定技能这是出现频率最高的一类问题。现象是技能明明已经注册测试时用提示词也能成功但一到连贯对话里模型就开始“自由发挥”要么拒绝调用要么把技能当作闲聊回复的一部分。我的排查顺序一般分三步。第一步检查技能描述是否与用户实际意图的距离过远。我见过一个案例技能名是“信息抽取”但描述里通篇在讲“将文本中的实体抽取并以JSON形式输出实体类型包括personorganizationlocation”实际用户问的是“这段话里提到了哪几家公司”模型很难把“organization”和“公司”建立强关联。改成“该技能从用户给出的任意文本中提取公司名称、人名、地名并输出结构化结果”后调用率立刻上去了。第二步检查技能描述是否太长太啰嗦。模型上下文窗口有限如果路由阶段给到所有的技能描述超过一定量级后模型的注意力会被稀释。我的做法是在路由层做一次向量检索只把相似度最高的前五个技能描述放到模型可见的候选集里而不是把所有技能一股脑塞给它。第三步检查示例是否太少。我在开发中定的经验是每个技能至少给三组“典型用户提问技能调用参数期望输出”的示例。这比在描述里反复强调“请调用本技能”有效得多。4.2 问题二技能输出格式不稳定下游解析报错模型输出是概率性的即便在output_schema中定了JSON结构仍然会出现字段缺失、嵌套结构错位等情况。后来我启用了双重保障。第一重保障是解析容错层。所有技能的输出不直接交给下游程序而是先走一个统一的解析器把模型输出的文本做一次规范化遇到缺字段时根据default_value进行填充遇到非法枚举时给出一个UNKNOWN占位。第二重保障是强制JSON模式。现在不少模型API支持在请求级别指定输出格式比如强制要求JSON对象。只要这项能力可用我建议毫不犹豫开启。技能内部的提示词也会额外注明“只输出JSON不要包含markdown代码块标记。”从实测数据看加上这两重保障后输出解析的失败率从早期的百分之十几降到了百分之一以下整个系统的稳定性有了质的提升。4.3 问题三多技能组合时上下文污染编排技能内部调用多个原子技能时前一个技能的输出会塞入上下文后一个技能看到的可能是一堆无关数据。模型的能力有限被无关信息干扰后输出质量暴跌。我的解决方案是“隔离上下文”。每个原子技能都有独立的上下文管理区间在执行完一个技能后它返回的只是一个“结构化摘要”而不是把原始输出全部追加到主对话上下文。比如sales_query返回明细表格但主对话中只保留统计摘要总行数、总金额、日期范围、最大最小值。真正需要详细数据的环节由下游技能通过内部状态去读取原始数据集避免上下文被撑爆。这套做法虽然增加了实现复杂度但在长多轮对话中效果极其明显不会出现聊到后面模型突然“失忆”的尴尬场面。4.4 技能质量参差不齐时如何优雅迭代技能库发展到一定规模后为了提高迭代效率我会把技能的运行日志进行可视化按“调用次数”“成功率”“用户反馈率”三个维度排序。每周挑一个维度垫底的技能深入优化而不是全面铺开优化。有一次我发现某个技能调用成功率一直徘徊在75%左右仔细排查后才发现问题出在它的输入样例中混入了一个不存在的地名。修正样例之后成功率直接跃升至92%。有时候问题根本不在模型而在脏数据。把技能当作软件模块对待每一条输入输出样例都要纳入回归测试这是最扎实的改进路径。5. 实战心得从“能跑”到“能稳定跑”的几条额外经验5.1 技能注册中心要有状态标签除了enabled和disabled之外我在registry.json里还会维护一个experimental标签。新写的技能先标记为实验性允许在非生产环境试用跑顺之后再转正。这样既能快速验证新想法又不会因为半成品技能污染生产环境的模型决策。5.2 编写技能时不要忘掉“不需要技能”的答案很多技能在写描述时只写了“什么时候用”忘了写“什么时候不用”。Agent误调用的一个重要原因就是描述里没有负面约束。现在我在每个技能的SKILL.md里都加了一段“不适用场景”并且会在示例中放一个不该调用本技能的短对话。模型在实际推理时对这类负面线索的敏感度其实非常高。5.3 把人工反馈作为最高的评判标准自动化评测指标再丰富也比不上真实用户的一句话“它回答得好准”或者“它咋答非所问”。我给Agent产品加了一个很轻量的反馈按钮长按出现三个选项“好用”“不好用”“答非所问”。一旦用户提交反馈对应的技能调用日志就会打上标签进入优化队列。这个机制虽然原始却是我迭代技能库最重要的数据来源之一。5.4 最后分享一个小技巧给技能库做“压力测试”写好了技能集别急着上线我会专门拿一批极端输入去“攻击”它。比如超长文本、无意义符号串、包含大量隐晦指代的问题。这些输入不会真正出现在大部分业务里但它们能暴露技能边界在哪里。模型面对这些输入时要么误触发某个技能要么产生幻觉这些都是在正常测试集里很难发现的问题。提前把这些问题暴露出来并优化技能描述比上线后被用户碰到要好上一百倍。agent-skills这条路我从零开始搭过几轮每次推倒重来都能更深一层理解“模型优先”的工程理念。它不复杂但很繁琐不需要高深数学但极度依赖对模型行为的敏感度。如果你也在做Agent落地的项目建议你先别急着堆砌炫酷场景耐下性子把技能层打扎实后面的一切都会顺很多。 
长河君 · 2026/10/13 16:47:24 · 阅读 1.2k 大模型Agent落地：构建可复用的技能层（agent-skills）
在搞大模型应用落地的时候我见过太多的半成品Agent项目了演示视频一个比一个亮眼一上真实业务场景就哑火。绝大多数问题并非模型能力不够而是“脑子”里根本没有一套可复用、可编排、能被语言模型稳定调用的技能包。说白了就是没把“agent-skills”这个基础层做扎实。所谓agent-skills我给出的定义是面向大模型智能体Agent封装的高度结构化、具备输入输出约束、可被模型在推理过程中动态触发的原子能力集合。它跟传统软件的函数库大不相同函数的签名和类型是给编译器看的Agent技能则是给大模型的上下文窗口看的。一份好的技能必须让模型在一两次推理内就能判断“该不该调、怎么调、结果怎么反馈”。这篇文章不会去整那些花哨的概念理论我直接把我自己在这个方向上的完整思考、设计取舍、踩坑过程以及最终稳定下来的实操方案全部摊开来讲。项目代号就叫“agent-skills”你可以直接把它当作一份可复现的工程笔记来读。1. 整体设计与思路拆解把“模型能力”变成“工程能力”1.1 为什么要专门抽象一层技能而不是让模型随手写代码很多人一开始会把“Agent能调工具”和“Agent具备技能”混为一谈。这里有个本质区别能调工具说明函数有入参出参具备技能意味着模型能理解这个工具在什么业务场景下使用、输入该带什么格式、输出如何处理、失败之后如何降级。举个例子业务方要求Agent查一个销售数据看板。写一个查询函数当然不难但Agent面对的是模糊需求“帮我看看最近卖得怎么样。”如果只有查询函数模型需要自己去猜维度、猜时间范围猜错概率很高。但如果把它包装成一个“TrendAnalysis”技能技能描述里写明“适用于销售趋势汇总与波动归因”输入参数明确给出时间口径、指标维度、粒度选择输出结果要求以JSON格式返回同比与环比模型在做规划时就会把这当作一个完整“能力单元”来调用效果完全不一样。所以这套设计的第一准则就是技能是连接模型意图与外部系统的语义契约这个契约要足够机器可读但更得足够模型可读。这跟面向对象设计有点类似但服务的对象是模型而不是程序员。1.2 三层技能架构基础原子、业务编排、跨域路由我在构建agent-skills时没有把大中小技能堆在一个平铺目录里而是划分成三层。原子技能层Atomic Skills负责单点能力的封装。典型的如“查天气”“发邮件”“读数据库”输入输出高度标准化不掺入任何业务逻辑。编排技能层Orchestration Skills由多个原子技能组合而来负责处理一个相对完整的业务流程。比如“新客户自动开户流程”需要依次调用资质核验、OCR证件提取、客户管理系统插桩、欢迎信发送。路由技能层Routing Skills这是一种特殊的技能本身不执行业务它负责根据用户请求判断后续路由到哪个编排技能或者原子技能组合。模型天生擅长分类与判别给它一个清晰的“技能路由表”能够显著降低误调用的概率。这三种技能在工程上会落地成不同的文件与描述模板模型通过一套统一接口来感知它们的差异。在设计阶段就明确它们的边界省去了后头大量互相打架的麻烦。1.3 一个让我反复推翻又改回来的设计技能描述必须“人话优先”刚开始做agent-skills时我把技能描述写得和传统的OpenAPI文档一样通篇是以接口参数为核心的说明结果模型的表现并不理想。后来对比分析才发现模型在函数调用模式下对“参数名”、“类型”这些信息敏感度很高但对技能层的元信息比如使用场景、成功标准反而出奇的看重。我做过一组对照实验相同的查询数据库技能第一版描述是“execute_sql(sql_string) 执行SQL查询并返回结果”。第二版描述是“本技能适用于数据分析师用户提出任意数据查询需求时输入合法的SQL语句技能会执行查询并返回结果集如果SQL语法错误则返回错误提示且不会执行任何写操作”。同一个评测集后者在任务完成率和意图匹配准确率上分别提升了大约8个点和17个点。这给我的经验是写技能的元描述时把它当作用户说明文档来写而不是接口文档。模型虽然是对概率的拟合但它需要足够自然的语义线索来触发正确的技能。这个认知贯穿了后续全部设计也建议你一开始就接受它。2. 核心细节解析与实操要点技能定义、参数契约与提示词完整解构2.1 一个标准Agent技能定义里必须包含哪些字段技能定义文件是整个功能落地的关键我把自己的技能模板拆解开看大致包含七个核心字段。每个字段都有其不可替代的意义。字段作用设计要点skill_name技能唯一标识符命名必须语义明确且自成体系我习惯使用名词短语如database_retriever避免使用短横线和编号后缀description给模型的自然语言说明需写清适用场景、不适用场景、输入要求、失败返回样式input_schema入参的形式化定义JSON Schema属性名尽量写全称避免缩写output_schema出参形式定义同样使用JSON Schema要求模型按预定结构消费返回信息prompt_template实际执行时注入模型的原生提示词不只是一个静态模板需预留上下文注入点供编排层填充allowed_tools允许该技能内部调用的工具白名单这是安全边界的重要实现方式也减少无效工具对模型决策的干扰error_handler技能执行失败时的降级处理策略可以是规则表达式也可以是另一个技能的名称每个技能文件我都会配套两个额外文件一个是examples.yaml放两到三组典型的调用输出示例另一个是tests/目录下的单元测试用例用模拟数据跑一遍技能的调用成功率。不要小看这些辅助文件它们承载的是“连贯性的基准”让技能质量的回归成为一件有依据的事。2.2 参数契约设计的两条铁律显式优先与默认值兜底在设计输入参数时两条铁律一定要刻在脑子里。第一入参最好显式化。不要指望Agent自己补全背景信息。比如一个“天气查询”技能你定义参数city必填模型就会主动去问用户是哪个城市。如果你定义city可空模型会在用户没提时直接传一个空值或者瞎猜一个这非常可怕。所以凡是业务上必须有的信息统统设成必填。第二接口要有默认值兜底。比如查询时间范围很多实际的业务场景都有默认口径。你在参数定义里写明time_range为可选默认是“近7天”模型在不确定时就会直接使用默认值不会反复追着用户问交互体验流畅一个量级。配合output_schema中的枚举约束还能降低模型自由发挥的空间。我踩过的最严重一次坑是在某个模拟客服项目中把user_name参数设为可选模型每次都要询问用户姓名而业务上这个字段在大多数场景根本不需要。后来把该参数从入参中删除改为在技能执行前通过系统上下文里的会话信息自动注入问题迎刃而解。因此你也要认真审视哪些参数应该由用户告诉模型哪些应该由系统直接注入不要把这两类混在同一个schema里。2.3 编写技能提示词的经验技巧别让模型猜测你的意图技能内部的prompt_template与系统提示词风格不同它更像一个局部限定环境。我的写法一般包含四个段落角色与边界说明、执行步骤序列、输出约束、检查清单。下面是一段我封装“技能编排引擎内部逻辑检查技能”时用到的模板已脱敏处理保留核心结构你现在是一个技能自检器。你要分析用户给定的技能描述与输入输出样例 判断该技能在以下三个维度上是否成立 1. 意图匹配度技能描述是否清晰是否存在可能被其他技能误触发的模糊表达。 2. 参数完备度输入参数是否覆盖所有业务必备信息是否存在隐含依赖。 3. 输出可用性输出schema是否能被下游步骤直接消费是否包含行数、状态码等必要元信息。 如果发现任一维度不达标请给出具体修改建议并指明是描述、参数还是输出结构的问题。 不要修改代码只输出分析和建议。类似这种“元技能”在实际项目中的价值极大。Agent不仅可以执行业务任务也能对这些技能本身做检查。稍微延伸一步你甚至可以做一个“技能修正Agent”每次技能执行失败或被用户投诉时自动进入诊断模式输出修正建议再由开发人员确认。这套机制一旦跑起来技能库的维护成本能下降一大截。2.4 给技能加上版本与淘汰机制技能不是一次写完就一劳永逸的。大模型的能力在迭代业务语义也在变化。我对每个技能都会维护一个版本字段并且在技能变更后进行回归试运行确保影响范围内没有其他技能被带崩。很长一段时间里我都在思考“什么时候该淘汰一个技能”而不是“什么时候该加技能”。淘汰的依据往往是调用日志。如果一个技能连续两周调用成功率都很低或者调用次数少到可以忽略就应该审视它的存在价值。我习惯保留一个retired目录而不是直接删除这样一旦业务场景复发随时可以恢复而不是从头再写一遍。3. 实操过程与核心环节实现从零搭建一个可运行的Agent技能库3.1 技能库目录规范与加载逻辑规范的目录结构能极大降低后续的维护负担。我的agent-skills项目目录如下agent-skills/ ├── atomic/ │ ├── data_query/ │ │ ├── SKILL.md │ │ ├── schema.json │ │ ├── prompt.md │ │ ├── examples.yaml │ │ └── tests/ │ └── text_process/ ├── orchestration/ │ ├── customer_analysis/ │ │ └── skill.yaml │ └── report_generation/ ├── routing/ │ └── super_router/ ├── shared/ │ └── error_handlers.py ├── loaders/ │ └── yaml_loader.py └── registry.json每个原子技能至少包含上文提到的SKILL.md和schema.json。registry.json是技能注册中心记录了所有技能的名称、版本、位置、依赖关系、启用状态。加载时我的工具函数会依次读取registry.json将每个技能解析成一个统一的技能对象放进内存池。这种设计的最大好处是重启加载非常快并且可以热插拔。用Python实现一个简化的技能加载器可以参考下面这段代码已简化便于理解import json from pathlib import Path class SkillRegistry: def __init__(self, registry_path: str): with open(registry_path, r, encodingutf-8) as f: self.registry_data json.load(f) self.skills {} def load_all(self, base_dir: Path): for entry in self.registry_data[skills]: skill_path base_dir / entry[path] skill_obj self._parse_skill(skill_path, entry) self.skills[skill_obj.name] skill_obj return self.skills def _parse_skill(self, path, entry): # 实际代码会解析 SKILL.md 与 schema.json # 此处示意结构 return { name: entry[name], version: entry[version], path: path, description: (path / SKILL.md).read_text(encodingutf-8), input_schema: json.loads((path / schema.json).read_text(encodingutf-8)) }3.2 一个完整示例设计“销售数据趋势分析”编排技能为了让你直观感受到从零搭建技能库的流程我拆解一个我在某模拟经营分析系统里做过的编排技能“销售数据趋势分析”。它由三个原子技能组成sales_query查询原始销售数据、stats_calculator计算同比环比、plain_text_generator生成自然语言摘要。首先在registry.json中注册该技能{ name: sales_trend_analyzer, version: 2.1.0, type: orchestration, dependencies: [sales_query, stats_calculator, plain_text_generator], path: orchestration/sales_trend_analyzer, enabled: true }其次编写SKILL.md的描述部分。这里的关键是写明“什么情况不适用”技能销售数据趋势分析 用途当用户询问销售表现、增长下降趋势、某区域或某产品线的销售波动原因时调用本技能。 不适用场景如果用户只是查询单个订单或单个客户的成交详情请直接调用sales_query不要使用本技能。 流程 1. 根据用户诉求补充时间范围、粒度周/月/季度、维度产品线/区域/渠道。 2. 调用sales_query获取原始明细数据。 3. 调用stats_calculator计算环比、同比以及贡献度。 4. 调用plain_text_generator生成趋势摘要。 输出要求返回结构化数据段含统计指标与自然语言摘要段。再来定义schema.json中的入参{ type: object, properties: { time_range: { type: string, enum: [last_7d, last_30d, last_90d, last_year], description: 分析时间段默认last_30d, default: last_30d }, granularity: { type: string, enum: [day, week, month], description: 统计粒度默认month }, dimension: { type: string, enum: [product_line, region, channel, overall], description: 分析维度默认overall } }, required: [] }实际开发中我会把required设为空数组因为所有参数都有默认口径模型可以根据对话历史自行判断。但我的默认值设计得足够合理就算参数全部为空也能跑出一个总体趋势概览。3.3 让模型正确触发编排技能路由配置是关键有了技能还不够Agent得能定位到它。我在routing层做了一个叫做“超级路由”的技能它本质是一个分类器。每当模型收到用户请求时先经过路由层的检索匹配再决定要不要进入某个业务技能。路由配置使用一种语义描述数组routes: - skill: sales_trend_analyzer trigger_patterns: - 销售 - 增长 - 下降 - 同比 - 环比 - 哪个产品线最好 avoid_patterns: - 单个订单 - 客户详情 - skill: customer_profiler trigger_patterns: - 客户画像 - 偏好分析 - 消费习惯路由层不直接输出完整技能执行计划它更像是给技能加了个“门卫”。这样做的直接收益是多个技能描述相似时模型不会被高相似度的文本干扰同时avoid_patterns的设定可以拦截很多不该触发的情况显著降低错误调用率。3.4 调用链路实践技能执行中的故障转移当一个编排技能内部的原子技能执行失败时直接报错是最愚蠢的做法。我在所有编排技能的末尾都放了一个异常出口核心思路只有一条降级不失败。举个例子在某次模拟分析中sales_query因源数据库连接异常而失败导致后续计算一并进行不下去。我设计的错误处理器会自动切换到缓存库查询如果命中缓存则直接继续如果没有缓存则生成一份“数据暂不可得”的叙述性结果并给用户提示请稍后重试。为了支撑这种降级逻辑每个编排技能都带有一份fallback_chain.yaml声明技能的备用数据源和兜底输出模板。fallback_chain: - try: cache_query on_failure: next - try: summary_without_data output: 暂时无法获取最新数据请稍后重试这条链路的价值在于用户感受到的是“系统在努力处理”而不是“系统崩溃了”。Agent项目跑业务时稳定性感知比花哨能力更能积累信任评分。4. 常见问题与排查技巧实录Agent技能跑不稳的根源在哪4.1 问题一模型始终不调用指定技能这是出现频率最高的一类问题。现象是技能明明已经注册测试时用提示词也能成功但一到连贯对话里模型就开始“自由发挥”要么拒绝调用要么把技能当作闲聊回复的一部分。我的排查顺序一般分三步。第一步检查技能描述是否与用户实际意图的距离过远。我见过一个案例技能名是“信息抽取”但描述里通篇在讲“将文本中的实体抽取并以JSON形式输出实体类型包括personorganizationlocation”实际用户问的是“这段话里提到了哪几家公司”模型很难把“organization”和“公司”建立强关联。改成“该技能从用户给出的任意文本中提取公司名称、人名、地名并输出结构化结果”后调用率立刻上去了。第二步检查技能描述是否太长太啰嗦。模型上下文窗口有限如果路由阶段给到所有的技能描述超过一定量级后模型的注意力会被稀释。我的做法是在路由层做一次向量检索只把相似度最高的前五个技能描述放到模型可见的候选集里而不是把所有技能一股脑塞给它。第三步检查示例是否太少。我在开发中定的经验是每个技能至少给三组“典型用户提问技能调用参数期望输出”的示例。这比在描述里反复强调“请调用本技能”有效得多。4.2 问题二技能输出格式不稳定下游解析报错模型输出是概率性的即便在output_schema中定了JSON结构仍然会出现字段缺失、嵌套结构错位等情况。后来我启用了双重保障。第一重保障是解析容错层。所有技能的输出不直接交给下游程序而是先走一个统一的解析器把模型输出的文本做一次规范化遇到缺字段时根据default_value进行填充遇到非法枚举时给出一个UNKNOWN占位。第二重保障是强制JSON模式。现在不少模型API支持在请求级别指定输出格式比如强制要求JSON对象。只要这项能力可用我建议毫不犹豫开启。技能内部的提示词也会额外注明“只输出JSON不要包含markdown代码块标记。”从实测数据看加上这两重保障后输出解析的失败率从早期的百分之十几降到了百分之一以下整个系统的稳定性有了质的提升。4.3 问题三多技能组合时上下文污染编排技能内部调用多个原子技能时前一个技能的输出会塞入上下文后一个技能看到的可能是一堆无关数据。模型的能力有限被无关信息干扰后输出质量暴跌。我的解决方案是“隔离上下文”。每个原子技能都有独立的上下文管理区间在执行完一个技能后它返回的只是一个“结构化摘要”而不是把原始输出全部追加到主对话上下文。比如sales_query返回明细表格但主对话中只保留统计摘要总行数、总金额、日期范围、最大最小值。真正需要详细数据的环节由下游技能通过内部状态去读取原始数据集避免上下文被撑爆。这套做法虽然增加了实现复杂度但在长多轮对话中效果极其明显不会出现聊到后面模型突然“失忆”的尴尬场面。4.4 技能质量参差不齐时如何优雅迭代技能库发展到一定规模后为了提高迭代效率我会把技能的运行日志进行可视化按“调用次数”“成功率”“用户反馈率”三个维度排序。每周挑一个维度垫底的技能深入优化而不是全面铺开优化。有一次我发现某个技能调用成功率一直徘徊在75%左右仔细排查后才发现问题出在它的输入样例中混入了一个不存在的地名。修正样例之后成功率直接跃升至92%。有时候问题根本不在模型而在脏数据。把技能当作软件模块对待每一条输入输出样例都要纳入回归测试这是最扎实的改进路径。5. 实战心得从“能跑”到“能稳定跑”的几条额外经验5.1 技能注册中心要有状态标签除了enabled和disabled之外我在registry.json里还会维护一个experimental标签。新写的技能先标记为实验性允许在非生产环境试用跑顺之后再转正。这样既能快速验证新想法又不会因为半成品技能污染生产环境的模型决策。5.2 编写技能时不要忘掉“不需要技能”的答案很多技能在写描述时只写了“什么时候用”忘了写“什么时候不用”。Agent误调用的一个重要原因就是描述里没有负面约束。现在我在每个技能的SKILL.md里都加了一段“不适用场景”并且会在示例中放一个不该调用本技能的短对话。模型在实际推理时对这类负面线索的敏感度其实非常高。5.3 把人工反馈作为最高的评判标准自动化评测指标再丰富也比不上真实用户的一句话“它回答得好准”或者“它咋答非所问”。我给Agent产品加了一个很轻量的反馈按钮长按出现三个选项“好用”“不好用”“答非所问”。一旦用户提交反馈对应的技能调用日志就会打上标签进入优化队列。这个机制虽然原始却是我迭代技能库最重要的数据来源之一。5.4 最后分享一个小技巧给技能库做“压力测试”写好了技能集别急着上线我会专门拿一批极端输入去“攻击”它。比如超长文本、无意义符号串、包含大量隐晦指代的问题。这些输入不会真正出现在大部分业务里但它们能暴露技能边界在哪里。模型面对这些输入时要么误触发某个技能要么产生幻觉这些都是在正常测试集里很难发现的问题。提前把这些问题暴露出来并优化技能描述比上线后被用户碰到要好上一百倍。agent-skills这条路我从零开始搭过几轮每次推倒重来都能更深一层理解“模型优先”的工程理念。它不复杂但很繁琐不需要高深数学但极度依赖对模型行为的敏感度。如果你也在做Agent落地的项目建议你先别急着堆砌炫酷场景耐下性子把技能层打扎实后面的一切都会顺很多。