企业官网建设流程全解析

最近在梳理智能体项目时，我发现一个很有意思的现象：很多团队在搭建 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 技能测试与回填验证：跑通只是起点，回头验才算完成

技能写完之后，我没有直接拿去用，而是做了一轮"回填验证"：拿历史人工处理的工单数据作为测试集，模拟一次次任务流程，把技能系统给出的结果和人工结果做比对。比对的重点有三个：

1. 正确性：提取的信息是否准确，分类是否符合人工标准。
2. 流程完整性：编排过程中是否出现技能未触发、重复触发或卡死的情况。
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 更可靠地干活，而可靠性这个东西，是试出来的，不是设计出来的。