如果你最近在折腾AI Agent大概率对 agent-skills 这个概念不陌生。它听起来很简单但真正动手做的时候很多人会被到底什么是技能、技能和提示词有什么区别、一个技能包应该长什么样这些问题卡住。我最初接触 agent-skills 时也踩了不少坑后来因为要给团队搭一套可复用的智能体能力层才慢慢把这件事捋清楚。这篇文章就把我对 Agent 技能的完整理解、定义方法、落地流程以及后续维护的经验一起梳理出来希望能帮你少走弯路。1. 为什么技能成了智能体落地路上的关键卡点1.1 从会聊天到能干活的转变先聊一个现象。很多团队第一次做 Agent 时习惯把大模型当成一个超级聪明的对话机器人给它一堆工具函数然后觉得它什么都能干。结果任务一复杂就崩要么模型不知道该在哪个环节调用哪个工具要么工具返回了一大堆数据但模型不知道哪段才是关键要么中途用户改了一个条件整个流程直接断掉。这里的问题不是大模型不够聪明而是我们根本没有把如何完成一类任务告诉它。聊天是自由联想干活是有章法。干活这件事需要把经验、流程、约束、验收标准都固定下来。而 agent-skills 就是干这个的把一类常见的任务封装成一个带输入输出协议、带执行步骤、带边界约束的技能包。有了技能包之后智能体遇到对应任务时不是从头零散地推理而是像一个老员工一样按照一套成熟的打法去执行。我自己对技能的定义是一个能被智能体反复调用、能独立完成一类目标、同时能输出结构化结果的最小能力单元。它必须有明确的适用范围、明确的执行路径、明确的成功和失败标准。没有这些所谓技能就只是换了个名字的提示词。1.2 技能、提示词、工具函数和插件的边界不少人在网上争论 Agent 技能和大模型提示词、工具调用有什么区别。我实际做下来它们之间的边界其实非常清楚区别主要看下面这张表概念核心载体解决什么问题局限性提示词 Prompt文本指令告诉模型本次交互的目标和语气一次性无状态不包含执行验证工具函数 Function可执行的 API 调用把某个外部能力暴露给模型只负责单步操作不管流程插件 Plugin按外部系统组织的功能集合通常围绕一个软件或 API 做功能封装偏重系统集成缺少任务级编排Agent 技能 Skill任务流程 约束 协议 示例让智能体稳定完成一类完整任务需要提前设计、测试和维护这样对比就很清楚了。工具函数回答的是你能做什么技能回答的是你要怎么做完这件事。插件回答的是我接入了哪个系统技能回答的是什么样的任务归我管任务做到什么程度算合格。提示词是这一句怎么说技能是这一类怎么打。我见过一个很典型的反面案例有人把十来个复杂的业务流程全部写进一个超长系统提示词结果模型经常把不同流程的规则混在一起。后来我们把每个流程拆成一个独立技能每个技能只负责自己的输入输出和内部步骤模型被路由到对应技能后准确率一下子提升了不少。这就是技能存在的最大价值隔离复杂度和风险。1.3 一个技能包到底应该包含什么在我看来一个完整的 Agent 技能包至少要有四个部分触发条件与适用范围什么情况下该用这个技能什么情况下不该用。这是路由的基础。输入输出协议使用者需要提供什么参数技能完成后返回什么结构。协议要尽量稳定否则上层没法编排。执行逻辑内部拆成哪几步每步调什么模型、什么工具步骤之间怎么传递信息。反馈修正路径失败之后怎么办输出不确定时如何标注置信度哪些情况需要人工介入。有人会问技能内部还要不要写提示词当然要写但提示词只是技能内部的一环。技能描述、参数定义、步骤编排、错误处理这些部分才是它和普通提示词拉开差距的地方。后面我会专门讲怎么把这四部分落到可维护的代码和配置文件里。2. 一套可复用的 Agent 技能定义方法2.1 命名、触发条件和适用边界先定下来我做技能定义时第一件事不是写实现而是先给技能定一个清晰的名字和边界。技能命名我推荐领域_动作_对象的格式例如order_query_status、finance_voucher_audit、docs_summarize_long。这样在智能体的技能路由表里扫一眼就知道它是干什么的。触发条件不要写得太抽象。比如当用户想了解订单情况时就不够因为了解订单情况可能涉及查询、修改、取消、申诉多个技能。更好的写法是触发条件包含用户明确提到订单号、查询物流、询问发货时间。不适用情况用户想修改订单内容应路由给order_modify用户想投诉应路由给order_after_sales。这样写清楚之后技能路由的准确率会高很多。很多人图省事把触发条件写成一两句话结果智能体经常同时命中好几个技能又要多一轮消解反而更慢。2.2 输入输出契约把自由度焊死把可能性留给内部这是我在 agent-skills 实践中收益最大的一条原则。技能的输入和输出必须严格定义技能内部的实现可以灵活多变但对外契约要稳定。输入参数我一般分三类必填参数没有它任务无法开始。可选参数有则锦上添花没有则走默认逻辑。上下文参数从上一环节继承的临时数据例如已确认的用户身份ID、当前会话的语言偏好。每个参数都要写类型、取值范围、示例值、默认值。比如时间范围这种参数如果只有 start 和 end没写明格式技能内部解析时很容易出错。我会把格式约束直接写进协议里并且在入口做校验不合法直接返回参数错误码而不是等到执行到一半才发现。输出结果我统一采用结论 证据 置信度 待确认项的结构{ conclusion: 订单已发货预计明天到达, evidence: [ {source: order_api, field: ship_time, value: 2025-01-08 10:22:00} ], confidence: 0.92, needs_review: false }这个结构的价值在于上层 Agent 不用再去猜这个结果可不可信。拿到低置信度结果时它会自动决定追问用户或转人工。输出结果结构化也是后面做技能评估和自动测试的基础。2.3 技能内部的三段式结构感知、决策、执行每个技能内部我习惯拆成三段感知、决策、执行。这个结构和人类做事的逻辑是一致的。感知阶段负责把输入参数和外部状态整理成内部可用的信息。比如查询库存技能感知阶段会先调用库存服务拿到最新库存列表把它们整理成一个紧凑的摘要而不是把原始数据全部塞给大模型。决策阶段负责做判断库存充足走正常发货流程库存不足则根据补货规则决定是给用户推荐替代品还是返回缺货标记。这里的判断不一定每次都要问大模型能用规则就用规则只有规则覆盖不了的情况才让模型参与。执行阶段负责落地调用下单接口、生成回复文案、把结果写回数据库。执行完成后还要自检一遍确认这一步真的做成功了再进入反馈修正路径。把技能内部拆成三段还有一个好处每段都可以独立做单元测试。感知不对就修解析逻辑决策不对就调规则和提示词执行不对就查接口调用排查效率高很多。3. 从零搭建一个技能库的完整流程3.1 先用任务清单反推技能树搭建技能库的第一步不是写代码而是盘点任务。我会把一个业务域的常见用户请求全部列出来然后做脱水处理把表达不同但本质相同的请求归并成一个任务。举个例子一个电商客服 Agent 会面对这些请求我的订单到哪了发货了没为什么昨天买的东西还没物流信息这三句话本质上是同一个任务查询订单物流状态。归并后变成一个技能。而帮我改下收货地址就是另一个任务往往还涉及订单状态校验不能和查询混在一个技能里。任务清单整理完之后再按对象和动作分组画技能树。表格是我常用的整理方式对象查询类操作类分析类订单query_order_statusmodify_orderanalyze_delay_reason售后query_after_salescreate_returnassess_risk商品query_product_detailupdate_stockrecommend_alternatives先画技能树再动手写实现。不要一上来就埋头写代码否则技能之间的关系理不清很容易做出大量重复造轮子的技能。3.2 把技能定义成可以反复调用的模块技能定义我会用一个清单文件加一段实现代码来管理。清单文件描述技能元的元信息实现代码负责真正的执行逻辑。一个极简但完整的配置大概长这样name: order_query_status description: 查询订单当前状态、物流信息和预计送达时间 trigger_when: - 用户提供订单号并询问物流进度 - 用户询问发货时间 not_trigger_when: - 用户想要修改订单内容 input: order_id: type: string required: true format: ^ORDER\\d{10}$ example: ORDER20250108001 user_id: type: string required: true context: true output: conclusion: string evidence: array confidence: number needs_review: boolean steps: - check_order_ownership - fetch_logistics - format_reply fallback: - on_unowned_order: return_error_code - on_api_timeout: retry_twice实际使用时我会在这里加一个implementation字段指向具体的执行代码文件或者用工作流引擎把 steps 对应到具体算子。配置和代码分离是为了让运营同学也能维护技能描述而不用直接碰代码。3.3 状态管理与上下文窗口控制技能执行过程中最容易被忽略的问题是状态管理。尤其是长任务比如根据用户过去三个月的购买记录生成消费报告这个任务涉及大量中间数据。如果全放在对话上下文里窗口很容易爆还会让模型注意力涣散。我的做法是引入工作记忆区。技能执行过程中产生的中间结果只保留摘要放在上下文里完整数据放在本地缓存或者内存对象中。模型每一步拿到的不是原始记录而是一份结构化摘要例如已获取用户近三个月订单 47 条总金额 8620 元 类目分布食品 31%日用品 27%电子产品 42% 异常情况有 2 笔订单发生退货。这样模型既知道宏观情况又不会被 47 条订单明细淹没。等真正需要看某笔订单时再通过一个查询技能精准拉取。上下文窗口控制的核心原则就是能不放大段原始数据就不放尽量放加工后的知识。3.4 技能测试矩阵不仅要测正常路径还要测打断技能上线前一定要做测试矩阵。我见过太多只测正常路径就上线的技能一到线上就暴露问题。我的测试矩阵至少包含四类正常路径输入合法参数验证技能按预期步骤执行并返回正确结构。异常路径参数缺省、格式错误、依赖服务超时验证技能是否返回标准错误码。打断恢复用户中途变换需求技能能否保存进度并响应新指令。噪声数据输入里夹杂无关信息例如用户把两个订单号写在一句话里技能能不能拆分。打断恢复这个测试很关键。比如用户说先帮我查一下快递然后顺便把收货地址改了。好的技能编排应该先把查询任务完成把结果存下来再进入修改地址的流程而不是因为需求变了就丢掉前面的上下文。我在测试矩阵里专门留了一条任务切换不丢上下文的用例每次发版前都必须过。4. 技能编排与多技能协作的实战细节4.1 技能路由先匹配规则再问大模型技能多了之后第一个问题就是怎么决定该用哪个技能。最省事的办法是让大模型从技能列表里选但实践下来技能一多模型选择准确率就会下降而且每次请求都会消耗不少 token。我的做法是两层路由。第一层走硬规则用关键词、正则、参数名这些确定性规则做粗筛。比如用户消息里出现订单号且动词是查直接命中查询技能。第二层才是模型介入如果粗筛置信度不高或者命中多个候选再把候选技能的描述和用户消息一起交给大模型让它选一个最合适的。硬规则引擎不需要多复杂一张路由表加上简单的匹配函数就够。关键在于路由结果要记录日志。后期如果发现某个任务的准确率低就可以通过日志反推是规则写得不好还是技能描述不够清晰。4.2 多步任务的中间结果传递和断点续跑多技能协作时最怕中间结果丢失。比如一个售后服务流程先查订单再判断是否符合退货政策最后生成退货单这三个技能之间是有依赖关系的。如果第二步失败了第一步的结果不应该被扔掉。我设计了一个简单的任务对象专门用来跨技能传递数据{ task_id: task_78f9ab, current_step: assess_return_policy, carried_data: { order_id: ORDER20250108001, order_status: shipped, policy_check: null } }每个技能执行完都把结果写回 carried_data并更新 current_step。这样即使流程中断也可以从 current_step 处恢复而不是从头再来。断点续跑还有一个好处用户随时回来问一句上次办到哪了Agent 可以直接读取任务对象回答不用再重新推一遍。4.3 给技能加日志和回放技能排错的时候日志是命根子。但很多人写日志只会打印一句话出了问题时根本不够用来推演。我给每个技能都加结构化日志每条日志包含技能名、任务ID、步骤名、耗时、输入摘要、输出摘要、异常信息。日志格式固定为 JSON 行方便后续按任务ID聚合回放。一次排查的过程大概是先根据用户反馈找到 task_id再把这个任务所有日志按时间排出来看哪一步的输入输出不符合预期。这套日志体系还有一个额外价值它是绝佳的评估数据来源。后面做技能优化时我经常从日志里抽样分析失败案例看看是路由错了、参数错了还是技能内部步骤没执行对。没有日志所谓优化就只能是盲人摸象。5. 技能维护、评估与灰度上线的避坑记录5.1 版本升级为什么会破坏旧任务增量兼容原则技能一旦被多个上层任务复用就不能随便改。我吃过一个亏某个查询技能原本返回confidence字段后来我觉得这个名字不合适改成score只改了代码没有做兼容处理。结果三个依赖它的任务全部报错因为上层逻辑还在读confidence。自那之后我定了一条增量兼容原则技能对外契约只能增加字段不能删除和改名如果必须破坏兼容要给技能升大版本并且同时保留旧版本至少一个完整发布周期。技能 schema 的每个字段都写在版本记录里哪个版本加的、为什么加、谁加的清清楚楚。5.2 评估技能效果的三个可操作指标技能上线之后怎么知道它好不好我看三个指标。第一个是完成率技能成功完成任务的比例。这里要注意正确姿势不能只统计代码没报错。技能跑完了但结论明显不对比如用户问发货时间技能返回了已签收这不算完成。为了统计这个我要求技能输出必须带 confidence低置信度的结果单独标记人工复核后再计入完成率。第二个是返工率用户对结果不满意重新发起相同任务的占比。返工率高说明技能对用户意图的理解有偏差或者输出格式不符合用户预期。第三个是平均调用成本一次完整技能调用消耗的 token 数、API 调用次数和总耗时。优化技能时如果完成率不下降但成本降下来了就是好优化。三个指标要连在一起看。有时候降低 cost 很容易比如少传点上下文但完成率可能跟着掉。我一般按完成率优先、返工率第二、成本最后的顺序取舍。5.3 一个省事的灰度发布办法技能发版不像普通代码发布那么自由因为技能是给大模型用的同一个技能往往同时跑在很多任务里。我的做法是给技能加一个 version 参数线上请求默认走稳定版内部测试走候选版。灰度流程很简单先在小流量上跑候选版比如 5% 的请求用 5.2 的三个指标对比候选版和稳定版。候选版完成率不低于稳定版成本没明显上升再逐步扩大到 20%、50%、100%。任何一个节点指标异常就把 version 参数切回稳定版整个过程不需要改代码只改路由配置。这个方法听起来普通但真的很管用。我见过有人把技能优化直接全量发布出问题后再回滚中间损失的线上任务和用户信任是没法弥补的。6. 把技能沉淀成团队公共资产6.1 技能仓库怎么组织才不吵架当团队里有多个业务线都在做 Agent技能共享就成了刚需。技能仓库如果没组织好一定会出现互相覆盖、命名冲突、职责不清的情况。我们目前用的目录结构是按域划分的skills/ common/ format_datetime/ extract_user_intent/ order/ query_status/ modify_order/ finance/ voucher_audit/common 目录放通用技能业务域目录放各自领域的技能。每个技能目录里必须有 README写明负责人、适用范围、输入输出示例、最近变更原因。没有 README 的技能不允许合并进主干。6.2 命名空间、权限和依赖管理技能多了还得解决依赖问题。有些技能会调用其他技能比如modify_order会依赖query_order_status来校验订单状态。我要求所有依赖必须显式声明不能在技能描述里默认应该有人在前面查过了。权限方面技能仓库对每个业务域开放读写权限但跨域修改要提评审。比如 finance 域的技能想调用 order 域的订单数据接口必须走跨域申请审计日志要能追溯谁在什么时间用了什么数据。这块不做好技能共享就是空谈因为没人敢把自己域的核心能力暴露出去。6.3 从技能包到技能市场我的一点思考技能库做到一定规模后很自然会往技能市场方向走。我现在理解这件事的本质是把常见任务的处理经验标准化、包装化让不同的 Agent 都能直接接入。技能市场的核心不是代码分发而是协议统一和信任建立。技能提供方要承诺输出质量消费方要能验证技能表现平台要维护统一的 schema 和评测标准。我个人在实际操作中体会最深的一点是不要一开始就想做一个大而全的平台。先把三五个高频业务场景做成高质量技能跑通测试、灰度、评估、共享的闭环再慢慢扩大范围。技能这种东西质量比数量重要得多。一个每天都在被调用、不断被修正的高质量技能价值远超一百个躺在仓库里吃灰的演示代码。最后再分享一个小技巧每次给技能做优化时保留一套老任务回归用例。这套用例不用多覆盖每个技能的典型路径和典型异常就够了。有了它你就可以大胆改技能改完跑一遍回归心里就有底。我在做 agent-skills 这套体系时最有帮助的就是这个回归用例它让我避开了很多看似不相关、实际互相牵连的坑。