企业官网建设流程全解析

看到 agent-skills 这个标题，我第一反应是：终于有人愿意把“给智能体配技能”这件事单独拎出来讲了。它既不是一张技能清单，也不是一个炫酷的功能合集，而是我在几次智能体项目里反复踩坑之后，沉淀下来的一套技能工程方案。大模型负责“想”，技能层负责“做”，agent-skills 就是连接两者的那层关键接口。很多团队做智能体应用，模型选得挺强，提示词写得也细，但真正跑起业务来还是经常“只会聊天，不会干活”，问题往往就出在技能层没设计好。这篇文章我会从概念讲到实操，一步步拆解 agent-skills 的技能怎么设计、怎么实现、怎么编排、怎么排障，适合正在做智能体应用、尤其被“能聊天但干不了活”卡住的开发者参考。

1. agent-skills 是什么：先搞清楚概念再动手

1.1 从智能体的“手”和“脑”说起

大语言模型的强项是理解意图、生成文本、拆解问题，但它本质上是没有“手”的。你说“帮我查一下订单到哪了”，模型能听懂，可它不知道订单存在哪个系统，也不知道怎么调接口，更不知道返回数据怎么解读。要让模型真正完成任务，就必须给它接上能操作外部世界的能力，这就是技能层。

agent-skills 要解决的核心问题，就是把这层“手”的工程化方案做出来。一个技能不是一段孤立的代码，而是一套可以被模型识别、选择、调用、返回结果的标准能力封装。它通常包含四个部分：技能名称和描述、输入参数定义、执行逻辑、返回值结构。模型在对话中看到用户的请求后，会根据技能描述判断“这件事该调哪个技能”，然后按技能协议传入参数，技能执行完把结果返回给模型，由模型组织语言回复用户。

我习惯用一个类比来解释：人脑知道“做西红柿炒蛋”的完整流程，但真正动手时，你不可能用一个笼统的“去做菜”命令完成全部操作。你得拆成“洗菜”“切西红柿”“打蛋”“热锅”“下锅翻炒”这些具体步骤，每一步都有清晰动作和预期结果。agent-skills 里的技能，就是这些被拆好的动作；如果只有“做菜”这一个万能技能，模型其实根本不知道该从哪里下手。

1.2 Skills、Tools、Plugins 到底有什么不同

在智能体相关的讨论里，经常能看到 Skills、Tools、Plugins 三个词混着用，很多项目文档也你中有我。但真到落地设计时，它们代表的层次和职责其实差异很大。

Tools 通常指偏底层的工具能力，比如一个封装好的 API 调用、一个数据库查询函数、一个文件读写模块。它强调的是“能做什么操作”，本身不关心智能体的语义决策。Plugins 更像是一个平台生态中的扩展包，往往由第三方提供，围绕某个产品形态做集成，用户装上就能用，但对内部逻辑的控制力弱。Skills 我更愿意理解为智能体侧的“会做什么”，它强调整体的可选择性、可编排性和语义描述。同一段 Tool，可以被包装成面向不同场景的 Skill，比如“查订单接口”是 Tool，但“按订单号查物流轨迹”和“查询用户最近订单列表”是不同 Skill，描述不同，适用场景也不同。

我用一张表帮助团队对齐概念：

这个区别不是纠结概念，而是直接影响代码怎么组织。如果只把技能当成普通函数写，很快会发现模型提示词里塞满了各种工具描述，选错率越来越高。如果按 Skills 的工程思路来设计，就能把“模型决策”和“能力执行”彻底分层，后续排查和扩展的体验会好非常多。

2. 技能拆解：设计一份高质量技能集的四个原则

2.1 原则一：技能粒度要“原子化”

我最早做智能体时犯过一个典型错误：为了让模型感觉“能力强”，把一大串操作塞进一个技能里。比如做一个“客户服务助手”技能，里面既查订单、又算优惠、还查库存，结果模型每次调用都成功，但返回结果要么过于笼统，要么中间某一步出错导致整体失败，根本定位不了问题。

后来我强制规定：一个技能只做一件事。以查订单为例，拆成“按订单号查询基本信息”“按手机号查询订单列表”“查询订单物流轨迹”三个独立技能。这样做的收益非常明显。第一，失败定位快，外部接口报错时能立刻知道是哪一段逻辑出问题。第二，组合性强，模型可以在一个任务里依次调用多个技能，而不是被迫选择那个“大杂烩”。第三，测试成本低，每个原子技能可以单独跑用例，覆盖率更容易做上去。

判断粒度是否合适的标准也很简单：如果一个技能描述里出现了“同时”或者“以及”这类词，大概率说明它还可以继续拆。技能可以拆到“每个技能只解决一个可独立验证的问题”为止，但也不要拆到参数层面过度零碎，否则模型选技能的压力会剧增。

2.2 原则二：描述越清晰，调用越准确

模型本质上是通过技能描述来决定“要不要用这个技能”的。同一套执行逻辑，写在描述里的文字不同，调用准确率能差出一大截。描述写得好比多加两个提示词还有效，因为它是直接喂给模型做决策的信息。

我给团队定的描述模板是这么写的：这个技能做什么；什么场景下应该调用；什么场景下禁止调用；必填参数和可选参数分别是什么；调用后会返回什么信息。正反例对比最直观。模糊描述是“处理订单相关操作”，模型面对“发货地址写错了要改一下”这种请求时，根本判断不了该不该调它。清晰描述会写成：“按订单号修改收货地址。订单状态为已发货时不可修改。需要提供 order_id 和 new_address。修改成功后返回新的收货地址信息。”

在真实项目里，我会把“什么场景下禁止调用”写得比“什么场景下调用”还要仔细。因为模型经常在相似场景上过度联想，比如用户说“我不想要这个订单了”，它可能去调用“删除订单”技能，但实际业务规则是只能“申请退款”。把禁用条件写清楚，能明显降低误调用率。

2.3 原则三：输入输出要有明确边界

技能本质上是一个函数，函数的输入输出必须有契约。很多团队用自然语言描述参数，模型传参时凭感觉写，执行层再做各种兼容，结果就是线上跑一段时间后，参数越来越不可控。

我建议每个技能都用结构化的参数定义，明确字段类型、是否必填、取值范围、默认值。举个例子，一个“生成月度报表”技能，参数应该定义为：

{ "start_date": {"type": "string", "format": "date", "required": true}, "end_date": {"type": "string", "format": "date", "required": true}, "department": {"type": "string", "enum": ["sales", "ops", "finance"], "required": false}, "format": {"type": "string", "enum": ["pdf", "excel"], "required": true} }

输出也是一样，尽量不要返回一段自由文本让模型去猜。统一结构化成这样：

{ "status": "success", "data": { "report_id": "RPT-2025-001", "download_url": "https://...", "generated_at": "2025-01-01T10:00:00Z" }, "error": null }

如果失败就把 error 字段填上结构化的错误码和可读信息。边界清晰最大的好处，是模型拿到返回值后不需要“脑补”含义，直接提取关键字段就能组织回复，后续做自动化断言也容易得多。

2.4 原则四：先写失败路径，再写成功路径

大多数人设计技能时习惯先想“正常流程怎么走”，但我踩过几次坑后把顺序反过来：先写失败路径，再写成功路径。因为智能体落地的稳定性，几乎全部取决于异常分支处理得够不够细。

一个技能至少要考虑这些失败场景：外部接口超时、参数格式不合法、接口返回业务错误（比如“无权限”“订单不存在”）、中间依赖服务不可用、权限校验失败。每种失败都要有对应的行为定义。比如超时不能默默失败，要返回“timeout_exceeded”这个错误码，并附带超时阈值；参数不合法时，返回“invalid_argument”并说明哪个字段有问题。

失败信息要“足够让模型理解并采取下一步”。比如用户要查订单，但订单号不存在，技能返回的 error 里应写明“订单号不存在，请引导用户核对订单号”，而不是简单一句“查询失败”。这样模型能基于错误信息继续引导用户，而不是卡死。我见过太多技能只在 try 里写了逻辑，except 里打一行日志就结束，智能体一遇到异常就只会回“抱歉我遇到问题”，体验极其糟糕。

3. 从零搭一套 agent-skills 的实操过程

3.1 第一步：梳理业务场景，列出需求清单

开始动手写代码之前，一定要先做需求梳理。我习惯从用户真实任务出发，而不是从现有接口出发。比如我在做一个面向客服场景的智能体时，先列了这样一份任务清单：查订单状态、修改收货地址、取消订单、申请退款、查优惠活动、生成售后工单、升级人工客服。

然后把这些任务拆成动作序列。查订单状态这个任务，拆出来的动作是：获取用户身份信息、调用订单查询接口、解析订单状态、组织回复。其中“获取用户身份信息”被多个任务复用，比如改地址、退款都要用，那它就应该单独变成一个技能。识别可复用的子动作是这一步的核心目标。

梳理时要注意和真实权限对齐。客服能查到订单不代表能改订单，操作类技能必须标注所需权限等级。我会在需求清单里增加一列“操作类型”，分成“只读”“普通操作”“敏感操作”，后续在技能注册时做权限匹配，这一步别省。

3.2 第二步：定义技能元数据与调用协议

需求清楚了，接下来就是给每个技能定义元数据。这里其实就是在写“给模型看的说明书”。我常用的技能元数据格式大致如下：

name: get_order_by_id version: 1.2.0 description: > 根据订单号查询订单基础信息，包括商品列表、金额、订单状态。 当用户提供订单号并询问订单详情时使用。 当用户仅询问物流轨迹时不要调用，请改用 get_tracking_info。 parameters: order_id: type: string required: true description: "用户提供的订单号，一般为字母和数字组合" returns: order_status: string total_amount: number items: array created_at: datetime timeout: 5s permission: order:read

每个技能我还会额外维护一份“调用协议”文档，说明技能内部远程调用的地址、认证方式、重试策略。它是给执行层工程师看的，不直接喂给模型，避免过多细节污染模型上下文。

技能命名的规范性容易被忽略。我建议统一用小写蛇形命名，命名里体现动作和对象，比如 send_message、create_ticket、update_address。命名一旦散乱，后面做技能注册和日志检索都会非常痛苦。

3.3 第三步：实现技能执行层

技能执行层是所有技能的公共底座，目标是把统一的公共逻辑抽出来，避免每个技能把参数校验、超时重试、日志上报都自己写一遍。一个标准执行层内部应该有这几件事：参数校验、权限校验、调用外部系统、结果标准化、日志上报。

参数校验最容易出问题。模型传参经常会出现字段缺失、类型错误、枚举值越界。我这边统一在入口处做严格校验，校验失败直接返回结构化错误，不让脏数据进入业务逻辑。错误信息要写得“模型能懂”，比如“date 字段格式应为 YYYY-MM-DD，当前收到 01/02/2025”。

外部系统调用要统一封装三次重试加指数退避。第一次失败后等 200 毫秒再试，第二次等 500 毫秒，第三次还失败就直接返回错误，避免无限重试拖死整个智能体。超时时间按技能单独配置，查询类技能我一般设 5 秒，写入类技能设 8 秒，兼顾体验和成功率。

我把这部分抽象成一个公共库，技能只写自己的业务校验和远程调用逻辑，其他事情全部交给执行层框架。这样新加一个技能时，只需要关注“这个技能到底要做什么”，而不是每次复制粘贴一堆重复代码。

3.4 第四步：注册到智能体运行时

注册是技能真正被模型“看见”的第一步。模型每一轮对话都需要一个技能清单，清单来自注册表。注册表里存放的是技能的元数据和当前状态，状态可以是 active、disabled、deprecated。不要把已废弃的技能从注册表里硬删，因为它可能还被历史会话引用，保留并标记 deprecated 更安全。

我在项目里维护一个简单的注册关系，类似这样：

skills_registry = { "get_order_by_id": { "name": "get_order_by_id", "version": "1.2.0", "enabled": True, "permission": "order:read", "executor": "OrderSkillExecutor", }, "update_address": { "name": "update_address", "version": "1.0.0", "enabled": True, "permission": "order:write", "executor": "AddressUpdateExecutor", }, }

实际运行时，智能体模型收到用户消息后，我取出所有 enabled 技能的描述，拼进上下文，让模型输出“要不要调技能、调哪个、参数是什么”。为了控制上下文长度，技能描述还要做压缩处理，比如只保留描述里最关键的字段，或者按场景分组建技能集。

注册时我强烈建议做一次“权限预检”：技能注册时就绑定最低权限要求，运行时再做一次用户粒度的鉴权，双保险。只依赖模型不做权限控制，等于裸奔。

4. 技能编排与复用：让 agent 从“能用”到“好用”

4.1 串行编排的三种基本模式

单技能只能解决碎片场景，真实任务往往是多步骤的。技能编排就是把这些步骤串起来。我做过的项目里，最常用的三种模式是：简单顺序、条件分支、并行扇出。

简单顺序很好理解，比如“查询订单并生成摘要”就是先调 get_order_by_id，再调 generate_summary。条件分支则是根据前一步结果决定下一步调用哪个技能，比如订单状态是“已发货”就走查物流技能，是“待付款”就走支付引导技能。并行扇出适合可同时执行的能力，比如用户问“我昨天买了什么以及物流到哪了”，可以同时查订单列表和物流轨迹，最后汇总结果。

我举一个完整的编排例子：用户请求“帮我看看这个订单值多少钱，如果超过 500 就帮我申请退款”。这个任务拆成三步：先 get_order_by_id 拿到金额；然后 judge_amount 判断是否超过 500；条件成立时再调用 apply_refund。每一步之间要把上一步的结构化输出传给下一步的参数，所以我在编排层维护一个临时状态对象，记录每步结果，避免重复调用同一技能。

4.2 技能冲突与优先级处理

技能多了以后，一定会出现“同一个用户请求，多个技能看起来都能响应”的情况。比如用户说“给张三发个消息”，既可以调 send_sms，也可以调 send_app_notification。模型如果自由发挥，大概率会随机选一个，结果可能和业务预期不符。

我解决冲突的方法是建一张优先级表。比如“发送渠道”冲突，按照业务规则定优先级：应用内通知 > 短信 > 邮件。同时把优先级写进技能描述的“禁止调用”字段里，比如 send_email 里明确写“当用户没有指定邮件发送时，且系统内已有更优发送渠道，请勿调用”。

如果两个技能语义高度重叠，最省事的办法是合并成一个技能，用参数决定行为。比如 send_message 可以接收 channel 参数，值为 sms 或 app，而不是维护两个独立技能。这能显著减少模型的选择压力。

触发敏感操作前，我会在编排层加一道“用户确认”节点。比如退款技能实际执行前，先让模型输出确认话术：“您确认要申请这笔退款吗？退款金额为 123.45 元，确认后预计 1 到 3 个工作日到账。”用户确认后才真正调用。这一步能把误操作率降到很低，值得多花一点交互成本。

4.3 复用视角：技能库的管理与版本

技能一旦开始服务真实业务，就必须当作独立产品来管理。我在代码仓库里给每个技能单独建目录，包含元数据、执行代码、测试用例、变更记录。技能版本号采用三段式，主版本不兼容变更、次版本新增能力、修订版修 bug。

版本变更最怕的是“默默改了描述但没告诉模型”。技能描述变了，模型决策逻辑就会变，所以我把描述变更视为高优先级的发布项，每次改动都要走一次回归测试，确认模型选技能的准确率没有下降。

灰度上线是另一个关键动作。没有条件做 A/B 测试的项目，至少要支持“按会话比例灰度”。比如把某个新版本技能的调用流量控制在 10%，观察调用成功率和平均耗时，稳定后再逐步放开。我会在注册表里动态调整 enabled 状态，不用重启服务。

我自己还维护一份技能健康度报表，记录每个技能的调用量、成功率、平均耗时、失败错误码分布。每个月过一遍，把调用量极低或失败率过高的技能挑出来，要么优化，要么下线。技能库不能只增不减，否则过段时间模型会被一堆低质量技能描述干扰。

5. 实测中踩过的坑和排查技巧

5.1 最典型的五个失败场景

技能跑起来以后，真正让人头秃的不是“技能不会写”，而是“模型用不对”。我整理了实战里最常见的问题和排查方向：

出现故障时，先别急着改提示词，优先看是不是技能层的问题。技能层问题通常有规律可循，大改提示词反而会把原本稳定的场景搞乱。

5.2 排查日志从哪看起

技能层的日志设计，我建议至少记录四个维度的信息：模型决策记录、参数快照、执行结果、耗时分布。

模型决策记录指的是“模型选择调用哪个技能、传了什么参数”，这是排障第一入口。参数快照要完整记录入参和执行结果，方便复现。执行结果要写清楚状态码和错误信息。耗时则按技能拆开，记录 P50 和 P95。

我把每次请求的全链路串成一个 trace_id，从用户消息进入智能体开始，到最终回复结束，所有技能调用日志都带上同一个 trace_id。分布式排查时，只要用户给一个会话 ID，就能把整条调用链拉出来。

一个有效的技能日志大概长这样：

{ "trace_id": "trc_8f3a2b", "event": "skill.invoked", "skill_name": "get_order_by_id", "input_snapshot": {"order_id": "A12345"}, "result_status": "success", "duration_ms": 342, "model_decision": { "selected_skill": "get_order_by_id", "confidence": 0.87 } }

排查时我习惯先看“模型选了什么技能”，再对比“应该选什么技能”。如果选错了，问题多半在描述冲突；如果选对了但执行失败，问题就在执行层或外部依赖。

5.3 一套可复用的测试清单

技能上线前，我有一套固定测试流程，确保不是“写出来能跑”就完了。

先测技能本身：参数合法时是否返回预期结构；参数缺失或类型错误时是否返回清晰错误；外部接口超时时是否走重试并最终返回错误码；权限不足时是否拒绝调用。

再测模型选技能的能力：给一组标准用户问题，逐个验证模型是否选到正确技能。例如“我订单到哪了”必须选物流查询，而不是订单详情。这组问题集要覆盖普通说法、口语化说法、间接说法，充分暴露描述问题。

接着测编排链路：把多步任务完整跑一遍，确认每一步的状态传递正确、分支逻辑符合预期、敏感操作确认节点生效。最后测异常恢复：在服务运行中手动让某个外部接口返回错误，观察智能体能否基于错误码继续引导用户，而不是卡住或报错。

这套清单跑完，基本能把上线的风险控制在一个可控范围内。测试集本身也要版本化，技能描述一变，先用老测试集回归，再补新样例。

最后再分享一个我在实操中的体会：agent-skills 这套东西，最难的从来不是写代码，而是让模型在无数个可能性里选到正确的那一个。把技能描述写细、把失败路径想全、把日志埋好，稳定性的提升是肉眼可见的。我早期做技能库时，总想塞更多功能进去，后来发现克制才是关键。少而精的技能集，配上清晰边界和完整异常处理，比堆几十个描述含糊的技能靠谱得多。如果你正准备重构智能体的技能层，建议从最小的三五个技能开始跑通全链路，再慢慢扩展，这个节奏最不容易翻车。