最近在梳理智能体项目时我发现一个很有意思的现象很多团队在搭建 Agent 应用时最头疼的往往不是模型选型也不是 Prompt 调优而是明明模型能力很强为什么落不了地。说到底问题出在技能层——我们把大模型当成一个聪明的通用大脑却没给它配一套趁手的手和脚。这就是 agent-skills 这个概念真正要解决的问题如何为智能体构建一套结构化的、可复用、可调度的技能体系。这篇文章我会结合自己搭建技能库的实践把技能定义、编排、落地和评估整个链路摊开来讲希望能给正在做 Agent 应用的开发者一些可直接参考的经验。1. Agent 技能为什么不能靠堆提示词解决先把话说在前面技能Skills不是一个新造出来的概念但在 Agent 工程里它被赋予了更具体的含义。简单来说技能是让智能体完成某个特定任务的最小可复用单元它封装了任务描述、执行逻辑、输入输出规范以及与外部工具交互的方式。很多人一开始会混淆技能和提示词觉得我只要把工具调用的说明写清楚模型自然就会用。但实际操作一段时间之后你会发现这条路走不通。1.1 提示词是说明书技能是操作手册把提示词当成技能等于你给一个刚入职的实习生发了一份产品说明书却没有给他培训手册和操作规范。说明书能告诉他这个工具有什么功能但没法让他知道什么场景下优先用哪个工具两个工具之间怎么配合出了问题怎么降级处理。而技能体系要解决的就是这些内容它规定了任务的触发条件、执行步骤、需要注意的边界情况甚至包括失败后的重试策略。我在一个模拟项目里做过一次对比实验同样的任务——把用户反馈的 Excel 文件按优先级分类并生成日报用纯提示词方案模型会把数据读错、分类标准漂移而且每次执行的结果差异很大用技能方案把读取表格规则分类生成日报三个技能分别封装再通过编排把它们串起来准确率和稳定性都明显提升。这说明一个核心问题技能的确定性来自流程约束而不是模型的临场发挥。1.2 技能的边界它解决什么不解决什么这里也顺便给技能祛个魅。技能不是万能的它解决的是做事的方式问题而不是理解的能力问题。比如你给模型配上联网搜索技能它就能按规范发起搜索请求、解析结果、标注来源但如果你问的问题本身很模糊它依然可能搜回来一堆无关内容。这属于任务理解层面的问题应该靠意图识别和任务规划来解决而不是硬塞给技能层。所以我习惯把 Agent 的能力分成三层来理解规划层Planning负责理解用户的意图拆解任务决定要做什么。技能层Skills负责具体执行决定怎么做每个技能对应一类明确的操作。工具层Tools技能内部真正调用的外部接口比如数据库、API、文件系统。这个划分帮我避免了很多设计上的混乱。规划层可以保持灵活让模型发挥推理能力技能层则要追求稳定和可控一旦编写完成就不该有随机性工具层是纯执行只需要保证接入规范和错误处理到位。2. 技能定义层把自然语言能力翻译成可执行规格聊完了概念直接进入实操。技能定义是整个体系的地基定义得好不好直接决定后续的编排和复用是否顺利。我的经验是一个合格的技能定义至少包含五个组成部分技能描述、输入参数、执行逻辑、输出规范、异常处理。2.1 如何写出模型能理解又不会误解的技能描述技能描述的作用是让 Agent 在该用的时候想起它。这里最常见的错误是描述太抽象比如处理数据——模型根本不知道这个技能具体覆盖什么场景或者描述太长把执行逻辑都写进去反而干扰了技能分发时的判断。我的写法遵循一个简洁公式[适用场景] [具体行为] [产出物]。举一个实际的例子技能名称batch_classify_feedback 技能描述适用于用户反馈量较大超过50条且需要按预定义规则分类的场景。 行为读取输入文件中的每一条反馈文本按照规则列表匹配分类输出带类别标签的表格。 产出结构化分类结果包含原始文本、命中规则、类别标签、置信度说明。这样写的好处是Agent 在任务规划阶段很快就能判断这个技能是否匹配当前需求匹配不上时它也不会强行调用。我在实践里发现把描述控制在一百五十字以内、避免形容词、多用限定条件的写法分发准确率比长篇描述要高一截。2.2 参数格式与 Json Schema给技能装上接口约束技能要能被可靠调用参数就必须有严格的格式约束。我通常用 JSON Schema 来定义每个技能的入参不是某个工具特有而是一种通用规范。举一个技能查询订单状态的参数定义{ name: query_order_status, description: 根据订单号查询当前的物流状态和异常信息, parameters: { type: object, properties: { order_no: { type: string, pattern: ^[A-Z]{2}\\d{10}$, description: 订单编号格式为两位大写字母加十位数字 }, customer_id: { type: string, description: 客户编号用于权限校验 } }, required: [order_no, customer_id] } }反过来输出也要有规范。我习惯让每个技能都返回一个统一的包装结构{ status: success, data: { ... }, meta: { execution_time_ms: 230, sources: [db:order_2024], next_action_hint: order_dispatch } }这个结构看起来没什么技术含量但它让后续的编排层可以用统一的方式处理结果不用为每个技能单独写适配逻辑。特别是next_action_hint这个字段它是技能之间配合的关键信息后面讲编排的时候还会提到。2.3 语义化命名与版本管理技能库越做越大的隐藏成本技能库规模小的时候命名无所谓规模一大命名就成了隐性成本。我见过一个项目技能库里同时存在handle_data、data_process_v2、process_csv_data这几个功能高度重叠的技能调用时全靠模型猜结果经常串。现在我的做法是命名采用动词 对象 场景的格式比如summarize_daily_report、extract_invoice_total。每个技能维护一个版本号重大变更时递增主版本小的参数调整递增次版本。Agent 默认调用最新稳定版但保留历史版本用于回滚。技能之间如果存在功能重叠我会在描述里显式写明本技能不支持场景 X请使用技能 Y给模型明确的指引。版本管理这个细节看似琐碎但在迭代频繁的项目里它决定了技能库是越用越顺还是越用越乱。3. 运行时编排技能路由、上下文传递与冲突消解技能定义做完相当于准备好了乐高积木——每一块都规范统一但它们不会自己拼起来。真正让技能发挥价值的是运行时编排。这也是 agent-skills 体系里最考验设计功底的部分。3.1 技能分发如何避免把每一个任务都变成一场盲选技能分发Skill Routing解决的是到底该调用哪个技能的问题。我在实践中试过两种方案一种是把技能列表全部塞给规划层让模型每次执行时自行选择另一种是在规划层之前加一个轻量的分发器先做一次规则匹配缩小候选范围。在小规模项目里前一种方案是可行的。技能一多全部塞给模型会导致两个问题一是 Token 消耗直线上升二是模型在弱相关技能之间容易犹豫影响响应速度和质量。后来我改成规则预筛 模型决策的混合方案分发器基于技能描述里的关键词做一次粗筛选出 3 到 5 个候选技能再让模型从候选里做最终选择。这样既保留了模型的判断能力又避免了大量无关技能的干扰。3.2 技能协作模式串行、并行与条件跳转实际任务里单个技能往往不够需要多个技能配合完成。我归纳出三种最常用的协作模式对应不同的场景流水线模式Pipeline多个技能按固定顺序执行前一个的输出作为后一个的输入。适合数据清洗、报告生成这类流程固定的任务。条件路由模式Router根据某个技能的输出结果决定接下来走哪条分支。适合意图分支明确的业务场景比如如果检测到高冲突情绪转人工处理否则自动回复。并行扇出模式Fan-out同一个输入同时分发给多个技能处理最后汇总结果。适合需要多维度分析的场景比如同时做情感分析、主题提取、风险识别。三种模式没有绝对的优劣通常一个真实任务会混合使用它们。关键在于编排层要把这些协作关系用显式的规则或流程图表达出来而不是依赖每轮任务都让模型从头规划一遍。显式的协作关系意味着稳定模型自主规划意味着灵活两者要找到平衡点。3.3 上下文传递别让技能变成一座座信息孤岛技能之间的信息传递是编排里最容易出问题的地方。我踩过一个很典型的坑技能 A 从输入文件里提取了客户名单技能 B 需要根据这个名单去做批量查询但我没有规定 A 的输出格式里客户名单放在哪个字段B 拿到数据之后解析错了位置导致整批查询失败。后来我规定所有技能之间的信息交换必须遵循一个约定的上下文协议大致包含三类内容全局可见的共享上下文包括业务术语表、会话历史摘要、用户画像摘要这些信息所有技能启动时都会加载。技能输出的结构化数据必须放在data字段里并且要符合自己的输出 schema。不确定的信息不得藏在描述性的文本里必须显式声明为meta.next_action_hint或meta.sources。这个约定在一开始看起来只是多写几个字段的事但运行一段时间后就发现它大大降低了编排层的编码复杂度。技能之间不需要互相猜测对方的输出结构一切都有明确的契约。4. 技能落地实例从业务拆解到回填验证的完整链路理论讲了这么多用一个实际的例子把流程串起来。我最近在模拟环境里为工单智能助手搭建了一套技能体系就把它当作 case study 讲一遍。4.1 业务拆解把模糊需求拆成可执行的技能清单需求方给的原始描述只有一句话做一个能自动处理工单的助手。这句话里没有技术细节所以我从业务流程反向拆解最终得到一组技能清单extract_ticket_info从用户提交的原始文本里提取工单编号、问题类型、优先级等信息。check_order_status调用订单系统 API查询关联订单的状态。escalate_to_manual当系统判定无法自动解答时转交给人工客服准备好转交摘要。draft_reply_message基于工单信息和查询结果生成给用户的回复草稿。log_ticket_history记录整个处理过程便于后续审计。这件事里最花时间的是什么该拆分什么该合并的判断。我的标准很简单能独立提升复用性的拆开流程内强绑定的保留在一起。比如check_order_status单独拆出来是因为售后场景里其他地方也会用到而提取工单信息 生成回复草稿虽然是一个完整任务但它们只在这个流程里使用可以保留为一次编排中的两个步骤。4.2 每个技能的内部实现规则、模型与代码的合理分工技能内部并不一定非要调大模型合理分工更重要。我为extract_ticket_info设计了规则优先 模型兜底的策略工单编号的提取用正则表达式因为格式固定用规则又快又准问题类别的判断用模型因为用户表达方式多样规则写不完。类似地check_order_status表示解决体力活直接靠代码调用 API根本不经过模型层。这个分工背后的逻辑是能用确定性方法解决的问题就不要引入模型的随机性。模型应该做它擅长的事——理解语义、生成文本、处理不确定场景确定性的解析和计算应该用传统代码实现。这既提高了准确率也降低了 Token 成本同时让每个技能的行为更加可预测。4.3 技能测试与回填验证跑通只是起点回头验才算完成技能写完之后我没有直接拿去用而是做了一轮回填验证拿历史人工处理的工单数据作为测试集模拟一次次任务流程把技能系统给出的结果和人工结果做比对。比对的重点有三个正确性提取的信息是否准确分类是否符合人工标准。流程完整性编排过程中是否出现技能未触发、重复触发或卡死的情况。异常处理模拟订单系统超时、用户输入缺失等场景观察技能系统能否优雅降级。结果确实发现了一批问题比如extract_ticket_info在某些特殊文本格式下会漏提取信息escalate_to_manual转交时摘要不够完整。这些问题靠人工测试也能发现但回填验证的好处是能量化发现问题的比例和频率。最终使用一批带标签的数据跑完一轮之后我对技能体系的信心才真正建立起来。5. 评估与迭代技能不是写一遍就能用的最后一个想重点聊的话题是评估。很多团队做到Demo 能跑通就宣布完成了但距离稳定可用还有很长一段路。技能体系的评估和普通模型评估不太一样它既要评测单技能的执行质量又要评测整体编排的流畅度。5.1 单技能评估用自动化用例守住质量底线我为每个技能都建立了一个独立的测试用例集测试用例来源包括人工编写、线上真实数据脱敏回放、以及历史工单数据。评估维度通常包括成功率任务完成的比例比如查询订单状态是否成功返回结果。准确率结果内容的正确程度比如分类标签是否准确、提取信息是否完整。无异常率测试过程中是否抛出未捕获异常或出现超时。副作用检查技能是否做了超出任务范围的操作比如只读技能是否误写了数据库。这个用例集是技能迭代的护城河。每次改技能我都会先跑一遍全量用例回归通过才会考虑上线。自动化评估的成本很低收益却极为明显。5.2 端到端评估从用户视角检验整套编排单技能都稳定不等于整体流程没问题。端到端测试我模拟了一次完整对话用户提交一条工单反馈系统先通过extract_ticket_info提取信息再调用check_order_status查询状态最后用draft_reply_message生成回复草稿。我关注的指标除了正确性还有另外几个维度响应延迟技能调用链条越长延迟越容易失控需要关注每个节点耗时。多轮一致性用户接着追问时系统能否记住前文的上下文而不是重新读一遍数据。优雅降级当某个技能临时不可用时整个流程是否会自动调整还是直接告警失败。端到端测试中发现的一个有趣问题是draft_reply_message生成的回复草稿语气偏书面用户后续追问率反而更高。这暴露了一个此前忽略的点技能的目标不仅是完成操作还要符合业务场景的表达规范。于是我在该技能的描述里补充了回复风格简明、口语化、面向普通用户同时给生成结果加了一个语气校验步骤问题才得以解决。5.3 可观测性没有观测数据技能迭代就是瞎猫碰死耗子技能运行起来之后必须要有完整的日志和指标收集否则出问题只能靠猜。我现在在每个技能的入口和出口都会记录结构化日志包含执行时长、调用参数、返回结果摘要、异常堆栈等字段。这些日志有四个主要用途问题定位用户报故障时能快速还原调用链找到是哪个技能出错。成本分析统计每个技能的 Token 消耗和调用量找出耗占比高的环节考虑规则化替换。触发率分析哪些技能长期没有被调用可能是描述不够精准导致模型没识别到也可能是技能本身冗余。质量监测定期抽样技能运行日志人工评估结果的准确性回填进自动化用例集。我曾经在日志里发现extract_ticket_info的技能调用频率低到异常排查之后发现是描述里用了太多内部黑话模型并不能理解那个场景描述。调整描述措辞之后调用量立刻恢复了正常。这就是可观测性直接带来收益的例子。6. 技能库治理规模变大之后必须面对的四个问题当技能数量超过二十个做技能这个动作本身就开始变成一个需要管理的工程项目。这个阶段最常见的四个问题我提前讲一下省得大家走着走着才撞上去。6.1 技能重复与覆盖率先盘点再动手别闷头造轮子我在一个中型项目里就吃过重复技能的亏。不同的开发成员各自觉得自己写的技能更贴合需求结果同一个功能出现了三个版本参数风格不同输出格式不统一编排层面对这些并存技能时常无所适从。现在的流程是先做技能盘点再决定新增还是复用技能库维护一张清单记录每个技能的职责、入参出参、依赖工具、负责人、测试覆盖情况。新增技能前对照清单查重确认没有重叠才能立项。注意这个动作不是为了限制创新而是为了维持底层技能的整洁让上层应用可以稳定建筑在同一个底座上。6.2 技能依赖管理技能之间也会打架技能 A 依赖工具接口的一代版本技能 B 已经升级到了二代如果接口规则不兼容A 和 B 同时存在就会导致调用链不稳定。我的做法是在技能清单里维护一个依赖关系表标记每个技能依赖的外部工具名称和版本范围。当外部工具升级时先查询受影响技能列表跑一遍回归再统一升级。这有点像传统工程里的依赖管理不过在 Agent 场景里很容易被忽视——因为技能的本质是逻辑定义很多人下意识觉得改个接口不会影响逻辑。等到线上报错时才发现一次工具升级波及了七八个技能才来临时补兼容层就非常被动了。6.3 安全与权限边界技能能做的事必须受控技能一旦能连接外部系统权限边界就成了底线问题。我给技能的权限控制设定了几条明确规则技能声明所需的最小权限范围运行环境只授权申请过的权限未声明的操作一律拒绝。涉及写操作数据写入、状态变更、调接口出库等动作的技能必须有二次确认环节。高危操作批量删除、转账、权限变更等技能默认不可用需要单独灰度审核。顺带提一个很多人想不到的点这类权限控制的规则不应该通过模型推理来执行而是应该在技能框架层面强制校验。哪怕只是在描述里写了本技能只能读取订单状态也不能指望模型自觉。执行环境的硬性拦截才是唯一的可靠防线。6.4 技能退役没有删除机制技能库会越来越臃肿技能表现不佳或者被替代之后果断下线比继续保留更健康。一个技能如果连续多周调用量为零或者反复出现同一类质量问题我就会把它标记为待退役走一个简单的下线流程先停用入口观察两周是否触发回归问题如果稳定就从库中移除如果业务上还存在潜在需求会先问清楚回归条件再决定是否保留归档。这个机制保证技能库存是活跃的、有生命力的实体而不是一个越堆越满又没人敢动的仓库。7. 写在最后的几个实战心得体会文章写到这里框架性内容基本都讲完了。最后分享几个比较个人的感受算是对前面内容的侧面补充。第一个体会是技能设计和业务理解是强绑定的。刚开始搭技能体系的时候我花了很多时间在研究技术方案但真正让技能体系变得好用的其实是花时间去看业务方到底怎么处理工单、怎么定义紧急怎么区分可自动处理和必须转人工。技术模型不会告诉你这些东西只有业务场景能给你答案。建议先跟业务同学蹲几天现场把真实的处理流程和决策准则记录下来再回来抽象技能效率远高于边搭边猜。第二个体会是技能体系引入的额外成本不容小觑。技能定义和编排带来了可控性但它本身的维护成本也很现实。技能库需要版本管理、测试用例、日志监控、权限控制每一项都不是白来的。这些小工程在规模小的时候显得重但在跨过临界点之后它们反而是省力气的关键。如果你只打算做一个快速 Demo那不需要技能体系来约束一旦要推向生产环境技能体系的规范化工作一步都不能省。第三个体会是保持给未来留口子的心态。我现在做技能定义时会多想一步如果未来业务方要求调整逻辑哪一部分最容易变这部分能否通过参数或配置来解耦尽可能让变动落在配置层而不是每次改技能都要发一版新代码。这些听上去像是很遥远的工程哲学但项目迭代三个月以上你回头补课的成本会远高于一开始多花的那半天设计时间。最后一个具体的操作建议如果你真的要动手搭技能库先不要追求大而全。挑一条价值最高、链路最短的业务场景用技能体系把它完整地跑起来感受从拆解、定义、编排到测试的完整节奏。这一步走顺了后面横向扩展就是水到渠成的事。毕竟技能体系的目的是让 Agent 更可靠地干活而可靠性这个东西是试出来的不是设计出来的。