企业官网建设流程全解析

如果你最近在折腾AI Agent，大概率对 agent-skills 这个概念不陌生。它听起来很简单，但真正动手做的时候，很多人会被"到底什么是技能、技能和提示词有什么区别、一个技能包应该长什么样"这些问题卡住。我最初接触 agent-skills 时也踩了不少坑，后来因为要给团队搭一套可复用的智能体能力层，才慢慢把这件事捋清楚。这篇文章就把我对 Agent 技能的完整理解、定义方法、落地流程以及后续维护的经验一起梳理出来，希望能帮你少走弯路。

1. 为什么"技能"成了智能体落地路上的关键卡点

1.1 从"会聊天"到"能干活"的转变

先聊一个现象。很多团队第一次做 Agent 时，习惯把大模型当成一个超级聪明的对话机器人，给它一堆工具函数，然后觉得它什么都能干。结果任务一复杂就崩：要么模型不知道该在哪个环节调用哪个工具，要么工具返回了一大堆数据但模型不知道哪段才是关键，要么中途用户改了一个条件，整个流程直接断掉。

这里的问题不是大模型不够聪明，而是我们根本没有把"如何完成一类任务"告诉它。聊天是自由联想，干活是有章法。干活这件事，需要把经验、流程、约束、验收标准都固定下来。而 agent-skills 就是干这个的：把一类常见的任务，封装成一个带输入输出协议、带执行步骤、带边界约束的技能包。有了技能包之后，智能体遇到对应任务时不是从头零散地推理，而是像一个老员工一样，按照一套成熟的打法去执行。

我自己对技能的定义是：一个能被智能体反复调用、能独立完成一类目标、同时能输出结构化结果的最小能力单元。它必须有明确的适用范围、明确的执行路径、明确的成功和失败标准。没有这些，所谓技能就只是换了个名字的提示词。

1.2 技能、提示词、工具函数和插件的边界

不少人在网上争论 Agent 技能和大模型提示词、工具调用有什么区别。我实际做下来，它们之间的边界其实非常清楚，区别主要看下面这张表：

这样对比就很清楚了。工具函数回答的是"你能做什么"，技能回答的是"你要怎么做完这件事"。插件回答的是"我接入了哪个系统"，技能回答的是"什么样的任务归我管，任务做到什么程度算合格"。提示词是"这一句怎么说"，技能是"这一类怎么打"。

我见过一个很典型的反面案例：有人把十来个复杂的业务流程全部写进一个超长系统提示词，结果模型经常把不同流程的规则混在一起。后来我们把每个流程拆成一个独立技能，每个技能只负责自己的输入输出和内部步骤，模型被路由到对应技能后，准确率一下子提升了不少。这就是技能存在的最大价值：隔离复杂度和风险。

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 会面对这些请求：

• 我的订单到哪了
• 发货了没
• 为什么昨天买的东西还没物流信息

这三句话本质上是同一个任务：查询订单物流状态。归并后变成一个技能。而"帮我改下收货地址"就是另一个任务，往往还涉及订单状态校验，不能和查询混在一个技能里。

任务清单整理完之后，再按"对象"和"动作"分组画技能树。表格是我常用的整理方式：

先画技能树，再动手写实现。不要一上来就埋头写代码，否则技能之间的关系理不清，很容易做出大量重复造轮子的技能。

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 这套体系时，最有帮助的就是这个回归用例，它让我避开了很多看似不相关、实际互相牵连的坑。