企业官网建设流程全解析

如果你最近在做智能体相关的开发，或者只是被 AI 自动化的各种 Demo 刷屏，那大概率绕不开一个词：agent-skills。它不是某个特定产品，而是一种把智能体能力拆成一项项独立技能的思路——你可以理解为给 Agent 准备一本“操作手册”，让它知道什么时候调用什么工具、按照什么步骤完成任务。我和团队在某个跨平台系统里用这套思路重构了原有的单一 Prompt 结构之后，调试效率和任务成功率都有了肉眼可见的提升。这篇文章就从设计、定义、上下文管理到调试排障，完整讲一遍我们踩过的坑和沉淀下来的做法，适合正在搭建技能库的开发者，也适合想让产品同学理解 Agent 上限的项目负责人。

1. 技能库的整体设计思路

1.1 为什么智能体需要一套“技能集合”

先讲一个背景。早期做智能体应用的时候，很多人习惯把所有指令塞进一个超大 Prompt，里面写清楚角色、目标、步骤、工具清单、输入输出格式。这种做法在小规模 demo 里完全能跑通，但一旦任务种类超过十种，Prompt 就会变得像一个塞满东西的行李箱——找什么都费劲，稍微修改一处，另一个功能就莫名失效。

agent-skills 的核心思路，是把“大而全的指令”拆成“小而专的技能文件”。每个技能只负责一种能力，比如“从URL提取正文”、“查询订单状态”、“生成日报总结”。Agent 在运行时会根据用户请求动态选择需要的技能，而不是每次把所有规则都加载一遍。这么做有两个直接好处：

• 上下文更省：每次对话只加载相关技能描述，token 消耗明显下降。
• 调试更快：某个技能出问题时，单独改那个文件就行，不影响其他功能。

当时我们重构的某个模拟项目，原来一个 Prompt 有三万多字符，改动一次要跑半小时回归；拆成三十多个技能文件后，单个技能的平均响应速度和稳定性都好了很多。

1.2 设计技能库的顶层原则

技能库不是简单把 Prompt 拆碎，而是要有清晰的边界和规范。我总结下来有四条原则，几乎适用于所有场景。

第一条是“单一职责”。一个技能只做一件事。判断标准很简单：如果这个技能描述里出现了“然后”“同时”这类词，大概率还能拆。比如“提取订单并发送邮件”应该拆成两个技能，因为“提取订单”可以被多个场景复用，而“发送邮件”也要单独测试。我们曾经犯过的错误是把“总结会议纪要并同步到日历”写成一个技能，结果用户只想取纪要文本时，Agent 也会强行触发日历写入操作，产生了大量误调用。

第二条是“描述即触发条件”。技能描述要写清楚“什么时候该用”“什么时候千万别用”。这里的关键不只是给模型看，更是给未来维护者的文档。比如某个技能叫“数据清洗”，描述里如果只写“处理脏数据”，Agent 在用户闲聊时也可能误触发。更好的写法是：“当用户提供表格或结构化数据，且数据中存在缺失值、重复行或格式错误时使用；仅用于处理已加载的数据，不用于生成新数据。”

第三条是“工具绑定要显式”。技能里涉及的工具调用，不能只靠模型猜参数。每个工具的参数名、类型、必填项、示例值都要在技能文件里写清楚。模型调用外部接口出错，八成原因是参数示例没给够，而不是模型本身笨。我们后续会在第二章细讲怎么定义工具 schema。

第四条是“可单独测试”。每个技能最好能独立运行，比如通过命令行传入一个测试输入，看看返回结果是否符合预期。如果技能之间存在强依赖，至少也要能 mock 掉外部依赖后测试。这条原则决定了后面整个调试体系的效率。

2. 技能的定义与拆解实操

2.1 一个技能应该包含哪些核心要素

在实践中，我们把一个技能文件固定成几个字段：技能名称、描述、适用场景、触发条件、禁用场景、输入参数、输出格式、依赖工具、执行步骤、失败处理、使用示例。这里最容易被忽略的是“禁用场景”和“失败处理”。

禁用场景是防止 Agent 在高风险场景下硬套技能的有效手段。比如某个“信息提取”技能，我们会明确写“仅处理用户主动提供的内容，不得通过搜索获取额外信息”；某个“代码生成”技能，会写“不得修改配置文件中的连接字符串”。这些负向规则在模型评估时很容易被验证，也方便审计人员检查。

失败处理要定义“当调用链某一步失败时怎么办”。很多技能只写了主流程，没写异常分支，结果 Agent 遇到错误只会卡住或不停重试。我们的做法是把失败处理也作为一种技能内指令，比如“如果接口返回401，不要重试，直接返回需要用户重新授权的提示”。这样模型就能在异常情况下仍然给用户一个明确反馈，而不是一脸茫然。

2.2 从业务需求到技能文件的落地步骤

下面用一个真实场景演示拆解过程：“根据用户提供的行业关键词，生成一份包含市场概述、竞品清单、建议策略的调研简报。”如果这是项目里的一个需求，按 agent-skills 的思路应该拆成如下步骤。

首先是任务拆解。把需求拆成独立动作：生成搜索关键词、获取相关资讯、整理竞品清单、撰写报告段落。这四个动作里，“获取相关资讯”依赖一个搜索工具，其它三个可以只靠模型完成。

其次是定义技能边界。我建议每个技能文件里都给出一个 JSON 格式的输入输出示例，因为 JSON 比自然语言更容易被模型理解。比如“整理竞品清单”技能，输入字段是company_list和source_urls，输出字段是competitors数组，每个元素包含名称、简介、主要产品。你不需要写一大段解释，一个例子顶千言。

然后是绑定工具与参数。给“获取相关资讯”技能绑定搜索工具时，要明确参数query的长度限制、max_results的可选值范围，并且给一个示例查询词。很多工具调用的失败案例，就是因为技能文件里只写了参数含义，没写示例值，导致模型生成了一串带有特殊符号的关键词，触发了工具的输入校验错误。

最后是写使用示例。我们会在技能文件底部放 2-3 个“用户说法 -> 技能选择”的例子，比如：

{ "用户说法": "帮我看看新能源行业最近有什么动静", "选择技能": ["generate_keywords", "fetch_news", "organize_competitors", "write_brief"] }

这套拆解步骤看起来简单，但真正执行时很容易掉进“过度拆解”的坑。比如把“生成搜索关键词”和“生成报告章节标题”拆成两个技能，其实都是同一个“文本生成”能力，完全没有必要。判断拆分粒度是否合适的标准是：技能是否会被两个以上的场景复用。能复用才拆，否则就先留着。

3. 上下文管理与调用链路的实现

3.1 技能触发与上下文传递

拆好技能之后，下一个问题是：Agent 怎么知道该用哪个技能？目前常见的做法是在主对话流程中做一次“路由选择”——把用户当前请求和候选技能描述交给模型，让它输出一个技能列表。这个路由过程本身可以是一个内置技能，我们叫它router。

路由的关键是控制候选技能的数量。如果把几十个技能描述全部塞给模型，模型容易忽略最合适的那个，生成一个四不像的技能序列。我们的做法是先让路由模型根据用户请求做一级粗筛，把候选压缩到五个以内，再让执行模型细选并生成参数。一级粗筛可以用规则加关键词，也可以用一个小模型做分类，成本很低。

技能触发后，上下文传递要注意“最小化”原则。只把当前技能需要的输入传过去，不要把整个对话历史都塞给执行模型。我们遇到过一个典型问题：Agent 在执行“信息提取”技能时，把用户三天前的闲聊内容也带进了工具参数里，导致关键词混乱。后来在技能文件里明确声明“仅使用当前消息及最近一轮系统消息作为输入”，问题就消失了。

3.2 多技能协作时的编排顺序

有些任务需要多个技能按顺序执行。比如文章开头那个调研简报，需要先搜索、再整理、最后写报告。这时就涉及技能编排。

编排方式有两种：一种是在路由阶段就生成一个完整计划，另一种是让 Agent 每执行完一个技能，根据中间结果再决定下一步。前者适合流程固定的场景，效率高但灵活性低；后者适合探索型任务，效果更稳但会产生更多轮调用。我们在实际项目里采用混合策略：固定流程用预定义模板，分支流程用动态决策。

在技能编排里，最容易被忽视的是“中间结果的持久化”。如果技能 A 输出了一组文章链接，技能 B 需要用到这组链接，那么这组数据应该被存储在一个结构化变量里，而不是留在模型生成的历史消息中。很多 Agent 失败的原因是：前一个技能已经输出了结果，但后续技能在上下文里找不到这个结果，被迫重新生成了一次。给自己定一个规范：任何技能的输出，只要后续可能被用到，都显式写入一个workspace字段，后续技能通过读取该字段取值。

此外，编排顺序还要考虑“失败后的回退路径”。比如技能 A 失败后，是否尝试技能 A 的简化版本，还是直接跳转到技能 C？我们通常在编排模板里写一个fallback数组：

{ "steps": ["fetch_news", "deduplicate", "write_brief"], "fallback": { "fetch_news": ["search_local_cache", "ask_user_for_links"] } }

这样模型在某一技能失败时就知道还有哪些备选动作，而不是硬着头皮重试同一个工具。

4. 调试、评估与迭代避坑实录

4.1 常见技能失效场景与排查思路

技能拆好之后，真正的工作才刚开始。调试是最耗时间的部分。我把常见的技能失效场景分成四类，每类都有对应的排查方法。

第一类是“技能没触发”。用户需求明明匹配技能描述，但模型选了别的技能或什么都没调用。这种问题大概率是技能描述里的触发关键词和用户语言不一致。排查方法是把历史对话中用户真实说法收集起来，重新写描述。比如“提取文章标题”技能，描述里用的是“抓取标题”，但用户说“这个页面的主题是啥”，模型当然认不出来。要写“从页面中提取核心主题、标题或关键词”这样的泛化描述。

第二类是“技能触发了但参数错”。典型表现是工具调用报了类型错误或字段缺失。我们会启用一个“参数校验层”，在把工具调用真正发出去之前，用轻量规则检查必填字段是否都有值、枚举值是否合法。校验失败时，把错误信息返回给模型让它重新生成参数，最多重试两次。这个机制能在源头拦截大部分问题，比直接修改工具 schema 管用多了。

第三类是“技能执行过程幻觉”。比如信息提取技能输出了原文里不存在的内容。这种情况很难完全避免，但可以在技能文件里加一句“所有输出内容必须能从输入文本中找到对应证据，否则标注‘推断’”。另外，在代码侧对输出做一点事后校验，比如提取任务要求返回摘要时，检查返回文本与原文的重叠率是否过低。

第四类是“技能之间互相污染”。前面提到过上下文最小化，但还有一个常见问题：Agent 执行完一个技能后，把技能内部的思考过程遗留到了系统消息里，影响后续路由判断。我们在每次调用结束时都会清理系统消息里的技能内部记录，只保留输出结果。这一步看起来不起眼，但亲测能减少很多无规律的崩溃。

4.2 技能效果的评估指标与回归方法

没有评估就无法迭代。很多团队停留在“看一两个例子跑通了就上线”的阶段，后面每次改动都不知道是好是坏。我们后来搭了一套相对轻量的评估流程。

核心指标有三个：技能调用成功率、单任务平均交互轮次、人工修正率。成功率指的是“技能按要求完成了输入到输出的转换”，不是工具请求成功这一层；交互轮次衡量编排是否高效；人工修正率则反映用户体验——如果每个任务都需要用户补充信息，说明技能描述里的输入字段设定有问题。

回归测试集是另一件值得做的事。我们会为每个技能准备 20-50 条“用户说法 + 期望调用的技能/参数”样本，每次技能改动后跑一遍全量回归。内容不能太死板，要覆盖正常的说法、带方言的说法、带错别字的说法。这些样本不需要一开始就完美，可以边做边积累，重点是把典型坑给固化下来。

这里分享一个让我印象深刻的案例。某次我把某个技能描述里的“当用户提供链接时执行”改成了“当用户提到链接时执行”，结果测试集里凡是说“帮我找一个能用的链接，我先看看”的样本全部误触发。从这个案例我们知道，描述里的关键字要尽量用“主动提供”而不是“提到”，否则模型会把用户对链接的期待当成已有输入。这类细节只有通过大量回归样本才能发现。

5. 经验总结：几个值得长期坚持的习惯

围绕 agent-skills 这套体系，我们做了一年多，沉淀下来几个习惯，这里送给打算入坑的开发者。

第一个习惯是“版本化技能文件”。技能文件不是写一次就完，而是会随业务变化持续修改。我们一直用类似语义化版本的方式管理每个技能文件，字段增删、描述修改都留痕。这样出了问题能快速知道是哪次改动引入的。没有版本管理前，我们曾有三次上线后才发现是回溯了旧技能文件。

第二个习惯是“给每个技能写反面清单”。在技能文件里专门放一块“绝对不要做什么”。比如某个“周报生成”技能的负面清单会写“不要编造用户未提供的项目进度”“不要把上个月数据当作本月数据”。这些负面规则在模型判断边界时非常有用，也是我们评估模型对齐程度的最简单依据。

第三个习惯是“控制技能的总量”。我们早期拆技能拆得特别细，拆到每个动作一个文件，结果路由模型经常在几十个候选里犹豫。后来设定一个阈值：如果技能总数超过五十个，就先合并同类项。合并的标准不是文件数量，而是用户意图的区分度。不同意图才需要不同技能，相同意图只是参数不同就用一个技能加参数区分。

第四个习惯是“让产品同学一起写描述”。一开始技能描述由开发写，写出来特别像接口文档，模型经常触发不了。后来让产品同学参与编写场景化描述，开发只负责校准参数和边界，效果好了很多。一个技能描述如果能让不懂技术的人也觉得合理，那这个描述离一个好触发机制就不远了。

我个人在这些实践里最深的感觉是：agent-skills 解决问题的本质不是把 Prompt 变短，而是把混乱变成有边界的结构。只要边界清晰、回归到位，这个思路能很好地支撑起一套纯靠语言模型驱动的工作流。希望这篇经验整理的实操细节能帮你少走一点弯路。