这两年做AI应用开发最让我头疼的不是模型能力不够而是同样的脏活累活得反复干。你让智能体去查天气、发邮件、调数据库、解析日志每个场景都要重新写提示词、调试工具调用、处理异常情况代码堆了不少换个场景又得从头来。后来我梳理了一个思路与其让模型每次临场发挥不如把高频操作沉淀成一套可复用的技能库让智能体像工具箱一样按需取用。这套方法论我现在管它叫agent-skills也是这篇文章想聊透的核心内容。用大白话说agent-skills就是给AI智能体设计一套“肌肉记忆”。不是让模型每次都从零推理该怎么做而是提前封装好一批经过验证、边界清晰、可独立调用的能力模块。智能体接到任务时先判断该调哪个技能再通过参数传递去执行最后把结果回填给模型做下一步决策。这么做的好处非常直接任务完成率显著上升因为关键动作不再是靠模型“猜”出来的开发效率也翻了倍新场景往往是已有技能的重新排列组合排查问题也变得简单到底是意图识别错了、参数传错了还是执行体报错每一层都能单独验证。这篇文章适合正在做智能体应用、搞AI工作流自动化、或者想给自己产品接入大模型能力的朋友。不管你是用现成的Agent框架还是从零手写一套调度逻辑这套关于技能拆解、注册、编排和调试的方法都能直接抄作业。我会按自己的实践经验来展开把设计思路、落地步骤和踩过的坑都交代清楚。1. 为什么需要技能体系从单次对话到任务闭环1.1 智能体最常见的翻车现场先还原一个实际场景。我让智能体帮我做一份销售周报它需要完成这样几件事从数据库拉原始订单数据做聚合统计算出各区域销售额生成趋势图再把图表和结论写成一段汇报文字。听起来不复杂但每次执行都会有意想不到的状况。最常翻车的环节是数据查询。模型不知道你这套系统里订单表叫什么名字、字段是什么结构只能靠猜猜出来的SQL常常语法没错但逻辑不对比如把金额单位搞混、没排除退款订单、时间范围筛错。第二个翻车点是工具参数。有一次我让智能体调用Python环境跑脚本它把脚本内容作为参数传进去又把另一个环境变量也塞到同一个参数位里结果执行直接报错。第三个翻车点是没有中间态检查。智能体拿到原始数据后直接生成结论完全没有意识到这个数据可能已经是脏数据后续所有分析都建立在错误基础上。这些问题不是偶然的模型抽风而是架构层面缺失了“技能”这个抽象层。如果没有一个明确的、经过预先设计的技能边界模型每走一步都要现场决策怎么查、怎么算、怎么检任何一个环节的不确定性都会被放大。技能体系的核心作用就是把这些高风险、高重复的操作固化成“默认正确”的模块模型不需要理解内部实现只需要学会“在什么情况下调用哪个技能、传什么参数”。1.2 技能体系到底解决什么问题技能体系解决的本质上是“模型能力”和“业务确定性”之间的鸿沟。大模型的强项是语言理解和意图推理弱项是按严格逻辑执行多步操作。你让模型写一段营销文案它写得很好你让模型一张表不差地去核对账目它容易走神。把业务操作封装成技能是把模型的智能从“操作层”提升到“决策层”。模型不再去猜SQL怎么写、API参数怎么拼、文件往哪里存而是面对一个精简的菜单提取销售数据、生成统计图表、格式化报告文本。它需要做的选择从“几千个代码token中写对”降维成“从几个技能里选对”这个难度差了好几个量级。技能体系的第二个价值是沉淀与复用。一个团队踩过无数坑才调通的查询逻辑、数据清洗规则、报表模板不应该每次都让模型重新发明一遍。把这些经验固化到技能里后续所有智能体都能共享。新人接手项目时也只需要看技能注册表就能理解这个系统能做哪些事不需要翻遍整个代码库。第三个价值是风险控制。技能可以设置前置校验和后置校验没权限的操作直接拒绝计算结果异常直接告警。这比在提示词里写“请小心操作”可靠得多——校验逻辑是代码层面的硬性约束不依赖模型的临场判断。1.3 技能与工具、工作流、插件的边界做技能设计时最容易被问到的几个概念区别技能和工具调用有什么不同和工作流编排有什么不同和插件生态又是什么关系我的理解是这样工具调用是最底层的能力单元比如“执行一段Python代码”“调用某个REST API”它不关心业务语义。技能则是工具调用和业务语义的结合层比如“分析销售数据”这个技能内部可能包含数据查询、格式清洗、缺失值处理、聚合计算多个工具调用但对外只暴露一个业务意图。工作流是更高层的编排逻辑规定了多个技能的执行顺序、条件分支和循环逻辑比如“每周一早上9点执行、先拉数据再出图表最后发邮件”就是一个固定工作流。插件则可以理解为技能的打包分发格式——一套技能、配置和依赖的外部封装。你可以把自己的技能包发布出去让别人用也可以下载别人的技能包集成进自己的智能体。所以这四者的关系是工具是手脚技能是完整的动作工作流是套路组合拳插件是打包好的动作集。构建agent-skills体系重点是把工具组装成技能这一层做扎实工作流可以在上面灵活编排插件化是后续自然演化的方向。2. 核心拆解一套可落地的技能体系长什么样2.1 技能的三大组成元信息、执行体、校验器我在设计技能时坚持每个技能都必须包含三大块元信息、执行体、校验器。缺任何一块都会在后面某个时刻出问题。元信息是给模型看的“使用说明书”。一个技能能不能被正确调用很大程度上取决于元信息写得够不够清楚。我见过太多技能描述写得含糊比如“处理数据”这种模型完全不知道什么时候该用它、需要提供什么参数。合格的元信息长这样技能名称要具体比如“sales_data_query”而不是“data_process”描述要说明适用场景和不适用场景比如“用于按时间范围/区域/品类维度查询销售明细数据不包含订单退款处理”参数Schema要精确到每个字段的类型、取值范围、是否必填、字段间依赖关系。执行体是真正干活的部分。它可以是一个Python函数、一个Shell脚本、一个外部API调用也可以是一个子智能体的处理流程。执行体的关键要求是“无状态”——不依赖上一次调用的遗留变量每次执行都是独立完备的。这样技能才能被并发调用、被多个任务复用、被安全地放进各种编排结构里。校验器是容易被忽略但极其重要的部分。前置校验检查参数是否合法比如查询起始日期不能晚于截止日期、用户ID必须是数字且存在后置校验检查执行结果是否合理比如返回的记录数不能为零、计算出的汇总值必须落在合理区间、接口响应码必须是200。我一开始没有认真做校验器后来发现模型经常传参传得“看起来合理其实是错的”没有校验环节的话错误会一路传导到最终结果。2.2 技能粒度的抉择一次函数调用还是完整子任务技能粒度是设计中最容易来回摇摆的问题。粒度太粗一个技能内部塞了太多逻辑复用性差、可调试性差粒度太细技能数量爆炸模型做选择时的负担反而更重。我常用来判断的标准有三个。第一个是“这个技能是否围绕一个完整的业务意图”“给客户发提醒短信”是一个完整意图“计算字符串长度”不是一个完整意图。第二个是“参数是否足够简洁”“查询订单数据”需要传入时间范围和查询维度这是简洁的“生成一份包含图表、表格和文字分析的完整PPT”需要传几十个参数说明它粒度太粗了应该拆成“生成图表”“生成表格”“生成文字段落”等子技能。第三个是“能否被其他场景复用”——如果这个技能只能在某一个任务的特定环节里用那它很可能粒度不对考虑拆小或者抽象化。举个例子我在做一个智能客服系统时一开始设计了一个“回答用户问题”的大技能结果发现这个技能没法复用、没法测试、也没法优化。后来拆成“查询订单状态”“查询物流进度”“生成退款申请”“转接人工客服”四个子技能每个都清晰短小组合起来反而能应对更多用户问题。技能的粒度最终是服务于“可复用”和“可维护”这两个目标的。2.3 技能注册表的统一Schema设计当技能数量超过10个之后就需要一个统一的注册表来管理。注册表的核心是一份标准Schema记录每个技能的基本信息、调用方式、依赖关系和生命周期。我习惯用JSON Schema做底层格式。每个技能条目至少包含技能ID、名称、版本号、描述、参数Schema、触发条件、权限要求、超时设置、关联技能列表。用版本号管理技能迭代特别重要你改了技能的入参格式历史任务里还没执行完的记录还能按旧版本逻辑走不至于直接断掉。还有一个容易被忽略的字段技能的“清晰度标记”。这是我自己的土办法——在注册表里给每个技能标一个置信度分数。新上线的技能初始分低只有当它被模型正确调用的成功率稳定超过某个阈值后才标记为高可信技能。这个标记可以帮助我们决定哪些技能可以放给模型自由选择哪些技能只能在特定工作流里被显式调用避免模型在不可靠的技能上浪费机会。3. 从零开始搭建自己的技能库3.1 第一步先跑通一个最小闭环不需要一上来就设计几十个技能也不要先搭复杂的管理系统。我推荐的做法是选一个你日常最高频的任务把它拆解成三到五个技能然后手写一个最简单的调度器先跑通“意图识别—技能选择—参数填充—执行—结果返回”这个闭环。以我之前做的“日报生成器”为例它的任务是每天早上自动汇总昨天的核心运营指标生成一份图文日报。我只设计了三个技能指标查询、图表生成、日报排版。指标查询从数据库取数图表生成把数据变成柱状图和折线图日报排版把图表和文字说明拼成一份Markdown文档。最小闭环的调度器也不用写得很复杂核心就三个环节。第一是意图映射把用户输入的自然语言转换成技能ID和参数可以请模型做这个映射也可以写规则匹配初期规则匹配更可控。第二是技能执行按注册表找到对应函数传入参数执行。第三是结果落盘把技能返回的结构化结果保存成统一格式传给下一个环节。用最小闭环跑通之后你对技能应该长什么样就会有具象认知技能之间的边界是不是清晰、参数的传递是不是顺畅、结果的结构化程度够不够高。这些感觉只有实际跑一遍才体会得到光靠设计文档空想很难一次到位。3.2 第二步技能编排——让模型学会“技能路由”当技能数量超过一定规模核心问题就从“怎么写技能”变成了“怎么让模型选对技能”。这一步关键是技能路由也就是意图到技能ID的映射。我试过几种方式各有适用场景。最省事的方式是依赖模型的Function Calling能力。把技能的描述和参数Schema以结构化方式提供给模型模型在理解用户意图后返回一个函数调用请求我们负责执行。这个方案的优点是不用自己维护匹配逻辑模型天然擅长理解自然语言意图缺点是函数多了之后模型会随机误选功能相似的技能需要靠描述优化来缓解。第二种方式是向量化召回。把所有技能的描述和示例做向量化存储收到用户请求时先做相似度检索把最相关的几个技能作为候选集再让模型在候选集里选一个。这个方案适合技能特别多超过100个的场景先缩小范围提升精确度。第三种方式是规则引擎兜底。对于一些高频确定性指令“查天气”“定闹钟”这类直接用关键词匹配路由到固定技能不走模型速度快且零失误。实际上成熟系统通常三种方式混合使用规则处理高频兜底向量召回缩小候选集模型做最终决策。我自己的经验是要在注册表里给每个技能写清“优先调用条件”和“禁止调用条件”。比如“订单退款申请”技能只允许已登录用户调用客服坐席模式下优先使用自助服务模式下不允许触发。这个信息直接在描述里告诉模型能显著降低误配概率。3.3 第三步带状态的技能执行器技能本身是无状态的但实际的业务任务几乎都有状态流转。比如“生成月度经营分析报告”这个任务包含多个步骤取数、清洗、计算、出图、生成结论、排版输出。每一步依赖前一步的结果中间任何一步失败都要能回退或重试。我建议实现一个带状态管理能力的技能执行器。它负责维护一个任务状态对象Task Context包含任务ID、当前执行到哪个技能、每个技能的入参和出参、错误信息和重试次数。技能与技能之间不直接传值而是通过状态对象读写数据。这样做的好处是每个技能都是黑盒替换内部实现不影响其他部分。状态对象我一般用字典结构存关键字段包括task_id、current_step、step_results、pending_params、error_log。执行到某个技能时执行器先从状态对象里取出所需参数技能执行完毕后再把结果写回去再根据预定义的DAG有向无环图决定下一步走哪个技能。这个过程类似流水线每个工位只干自己那件事产品经过一个个工位被加工出来。还要处理失败重试。比如查询外部API时网络抖动导致超时应该自动重试并指数退避但如果是参数非法导致执行体报错重试没有意义应该把错误信息返回给模型让模型修正参数或换一条执行路径。判断哪个环节值得重试是执行器设计里一个重要细节。4. 实操记录给智能体装“数据分析技能”的全过程4.1 需求与技能定义拿一个真实场景来走一遍完整流程。我正在给一个内部运营平台做智能分析助手需求是这个助手能用自然语言回答关于平台运营数据的问题比如“上周华东区的新增用户数是多少”“最近30天各品类的转化率趋势如何”“对比上个月本月退款率上升了还是下降了”。我把这些需求拆成了五个技能metric_query查询单个指标在一段时间内按维度分组后的数值metric_trend查询指标在时间维度上的趋势数据segment_compare对比两个或多个维度分组之间的指标差异anomaly_detect检测指标序列中的异常波动点insight_summary基于查询结果生成自然语言分析结论每个技能都对应一个领域内的基础能力相互之间边界清晰。metric_query和metric_trend的区别是前者要分组维度后者固定按时间展开。segment_compare可以复用metric_query的底层查询逻辑但对外暴露的入参不同业务语义也更明确。4.2 技能注册表与代码实现以metric_query技能为例我给出一个精简但可运行的设计。先是注册表条目{ skill_id: metric_query, name: 运营指标分组查询, version: 1.2.0, description: 查询指定运营指标在给定时间范围内按维度分组的数值支持按日/周/月聚合。适用于回答\某段时间内某指标达到多少\的问题。不适用于多指标对比和趋势分析。, parameters: { metric: {type: string, enum: [new_users, active_users, refund_rate, conversion_rate], required: true}, start_date: {type: string, format: date, required: true}, end_date: {type: string, format: date, required: true}, dimension: {type: string, enum: [region, channel, category, all], default: all}, granularity: {type: string, enum: [day, week, month], default: day} }, prechecks: [ {type: param_range, field: start_date, rule: not_later_than(end_date)} ], timeout_ms: 5000 }参数设计里有一个经验是能用枚举绝不用自由文本。metrics和dimension都用枚举模型就不太会传来一个不存在的指标名。即使模型偶尔自由发挥校验器会直接拦截。执行体的核心逻辑如下这是一个简化版但思路可参考的伪代码def metric_query_executor(params): validate_params(params) sql build_query_sql( metricparams[metric], startparams[start_date], endparams[end_date], dimensionparams[dimension], granularityparams[granularity] ) df warehouse_client.query(sql) result { metric: params[metric], rows: df.to_dict(orientrecords), row_count: len(df) } if result[row_count] 0: raise QueryEmptyError(指标在时间范围内无数据可能原因无新增记录或日期范围错误) return result这里我把数据查询的SQL拼装逻辑完全封装在技能内部模型完全不感知SQL的存在。它只需要知道想查指标时调用metric_query传时间范围、指标名、维度即可。这大大降低了模型犯错的空间。4.3 技能编排与联调过程定义完技能后我搭建了一个测试工作流来验证效果。工作流是这样的用户提问 → 意图识别与参数抽取 → 技能路由 → 技能执行 → 结果格式化 → 生成最终回复。我用本地测试集跑了二十个真实业务问题覆盖正常查询、边界条件比如查一个没有数据的日期范围、以及容易混淆的意图比如用户问的是对比还是单值查询。第一轮跑下来的问题集中在参数抽取上模型有时把“上周”理解成“最近7天”但业务上“上周”是周一到周日。后来我调整了技能描述明确声明“支持自然语言时间内部自动转换”同时在校验器里增加日期合理性检查问题明显减少。联调过程中最有价值的设置是为每个技能增加“dry-run模式”。在dry-run模式下技能不执行真实的数据库查询而是打印出将要执行的SQL和参数让我能快速确认技能路由是否正确、参数抽取是否准确。这个模式对排查问题帮助特别大建议在开发早期就加上。5. 常见问题与排查技巧实录5.1 模型为什么总是选错技能这是技能体系上线后最常遇到的问题。表现是模型明明该调用A技能却调用了B技能或者直接说“我无法完成”而没有尝试任何技能。我排查这类问题的顺序是这样的。第一步检查技能描述是否区分度足够。如果两个技能描述里都出现“查询”“指标”“分析”这类词汇模型混淆是很正常的。我一般的做法是描述前面直接写核心触发场景把相似技能的差异化描述明确写出来。比如“metric_query”描述里强调“查单个指标的具体值”“metric_trend”描述里强调“看指标随时间变化的规律”。第二步检查示例是否到位。给模型看一两个该技能的典型输入输出示例比写十句抽象描述更有效。可以在注册表里加一个“examples”字段包含典型的问题和对应的参数填充结果模型少了很多发挥空间。第三步考虑是不是技能数量太多。模型在候选超过一定数量时误选率会上升。如果经过前两步优化还是不行考虑先做一层硬规则前置过滤用关键词把候选中范围缩小到5-8个再交给模型决策。我发现技能超过20个时这一步几乎必做。5.2 技能描述与评测指标描述写得不好直接影响技能召回和参数抽取质量。我总结了几个必须写清楚的部分技能职责、适用场景、非适用场景、参数语义、返回值结构、异常示例。特别要注意的是“非适用场景”它的作用和“适用场景”同等重要能有效避免过度调用。为了客观评估技能质量我建了一套简单的评测指标指标定义目标值技能路由准确率正确召回技能数/总测试集提问数≥95%参数填充完整率必填参数正确填充的任务数/总任务数≥98%执行成功率技能执行未报错且通过后置校验的任务数/总任务数≥93%端到端任务完成率整条工作流产出合格最终结果的任务数/总任务数≥85%这些指标不必一次达到很高但每次迭代都要有对照。上线前用固定测试集跑一遍记录基线改动技能描述或注册表后再跑一遍看指标有没有变化。如果你改了一个技能描述导致路由准确率下降就能立刻知道问题出在哪里而不是等着用户投诉。5.3 排查实录一个典型的技能调试过程分享一个真实的排查过程帮助你理解上面这些内容怎么串起来。有一次运营反馈说问答助手回复“本月退款率相比上月下降了”但实际运营数据是上升的。这个错误不小我着手排查。第一步我从执行日志里找是哪条路径产生了这个结论。日志显示模型先调用了segment_compare技能对比了上月和本月的退款率技能返回的数值是本月4.2%、上月3.8%这一步是对的。然后模型调用insight_summary技能生成结论结论却写成了“下降了”。问题出在模型解读数值时看反了方向。定位到问题之后我检查insight_summary技能的输入输出设计。发现它接收的是对比数值和方向标记但方向标记是从用户提问里抽取的根本没有参考实际数值。就是说模型先心里想了个“下降”再去找证据完全搞反了。修正方案是在技能描述里强制要求生成结论前必须先引用对比数值确认是正差还是负差后再下方向判断。同时我在技能里加了一个后置校验当结论方向与数值方向不一致时自动返回错误并要求重新生成。这个案例说明了一个核心经验技能的边界要清晰但技能与技能之间的“信息语义”也要连贯。不只是把A技能的出参作为B技能的入参还要确保B技能能理解A技能出参的业务含义。模型在中间环节的推理越多出错的可能越大设计上要尽量把“必须正确”的部分通过校验器固化成硬约束。6. 更深一层技能体系的演进与扩展技能体系不是静态的至少我自己用下来几乎每个项目都在不断调整技能边界。一个重要方向是把自然语言指令也变成技能。常规技能是接收结构化参数但有些场景需要模型保留更多自由度比如“把这段描述改写成更适合在社群发布的文案”。这时候可以把“按需改写文案”定义成一个技能内部调用一个子模型来做这样上层的主策略依然一致不会因为某个自由度的任务破坏整体编排逻辑。另一个演进方向是建好技能的依赖关系。技能不全是最底层的函数也可以由其他技能组合而成。比如“生成竞品分析周报”这个技能内部会调用“查询竞品价格”“抓取竞品更新动态”“生成对比表格”三个子技能但对外只暴露一个接口。技能有层次整体架构才会更稳定也更容易做细粒度的维护和优化。再就是技能的作用域和权限控制。早期我所有技能对所有智能体一视同仁后来发现数据敏感度不同技能权限也应该区分。现在会在技能注册表里加一个“visibility”字段标注哪些技能只能被内部管理系统调用哪些可以开放给面向用户的智能体。这个控制做在代码层而非提示词层安全性靠谱得多。最后建议有条件的话把技能的运行日志和性能数据积累起来。哪个技能调用频率最高、哪个技能平均耗时最长、哪个技能失败率持续偏高这些数据是迭代最重要的参考。没有数据支撑的技能体系优化方向全凭感觉有了数据每一步改动都有依据。我自己就是靠这些日志发现insight_summary技能的失败率在持续升高才及时定位到上述那个方向判断问题的。按这个思路把技能体系搭建起来之后我最大的体会是智能体的能力边界不完全取决于模型本身有多强更取决于你为它准备的技能库有多扎实。模型负责聪明技能负责可靠两者配合才是真正能上生产环境的智能应用。