企业官网建设流程全解析

1. 从"提示词"到"技能"：agent-skills到底在解决什么问题

做AI Agent时间长了，你会发现一个很微妙的分水岭。早期大家玩Agent，更多是在琢磨怎么把Prompt写得足够精细，让模型表现得聪明一点。但项目一旦跑起来，Agent要处理真实业务的时候，光靠提示词就不够了——你可能面对的是一个需要调用十几个工具、跨多个系统、还要保持输出格式稳定的任务流。这时候，"这个Agent会什么"就变成了一个工程问题。

"agent-skills"这个概念，本质上就是在回答这个工程问题。它不是让模型"想"得更聪明，而是让Agent"会做"更多事。你可以把一个技能理解成Agent能力的基本单元：一个技能封装了模型完成某类特定任务时所需的全部要素——包括触发条件、执行流程、工具调用方式、参数定义、输出格式，甚至包括异常处理和边界约束。换句话说，技能是把模型的能力"固化成流程"的手段。

这篇文章我想聊的，就是围绕agent-skills展开的一套完整实践心得：技能体系应该怎么设计、每个技能内部怎么拆解、多个技能如何编排协作，以及我在实际项目中踩过的那些坑。适合正在做Agent应用开发、或者准备把Agent从Demo推向生产的团队参考。里面的经验不一定适用于所有场景，但方法论是通用的。

我始终觉得，Agent应用做得好不好，跟底层模型关系没想象中那么大，反而跟"技能"这层中间件设计得合理不合理关系很大。接下来我用自己的项目经历，把这条链路从头到尾拆一遍。

2. Agent技能体系的设计思路

2.1 一次任务驱动的技能重构：从零散工具到结构化能力

我先交代一下项目背景。当时我们团队接了一个企业内部的知识管理Agent需求，核心任务是让Agent能自动从各个业务系统里收集数据、整理成结构化信息、生成分析报告，最后推送到协作工具。最开始我们按"工具调用"的思路来设计——定义了一堆函数，比如query_database、fetch_api、send_message，让模型根据用户意图自己组合调用。

实话说，第一步跑通的时候效果还行。但越往后越不对劲，用户的需求稍微复杂一点，比如"总结上周各地区的销售数据，和上个月做对比，然后给每条产品线写一份简短的走势分析"，模型就会开始"自由发挥"——有时候它先查了全年数据，有时候它忘记做对比，有时候它生成的报告格式长得完全不一样。你会发现模型不是不会调用工具，而是它根本不知道该按什么顺序、什么标准来执行一整个流程。

这就是"工具思维"和"技能思维"最核心的区别。工具解决的是"能做什么"，技能解决的是"该怎么做"。我们在设计agent-skills的时候，把原来那些散的函数调用，重新组织成了一个个有明确目标、有步骤约束、有输出标准的技能模块。比如数据分析这个能力，不再是模型随时可以调用的一个API，而是一个完整的"数据分析技能"——它规定了输入数据源、分析维度、对比方法、报告模板，甚至规定了中间每一步的校验规则。

这个重构带来的第一个明显变化是稳定性的提升。模型不再是"临场发挥"，而是在一个设计好的框架内执行，自由度被限制在合理范围内。第二个变化是可维护性上来了，业务要加新的分析维度，不需要重新调Prompt，只需要改技能内部的配置。

2.2 技能粒度怎么定：拆得太细和拆得太粗都是坑

设计技能体系时，最容易被忽视却也最关键的问题，是技能的"粒度"应该怎么把握。我见过不少团队，把技能拆得极其精细，每个技能只做一件小事，比如"格式化日期""去重列表"这种级别。结果就是Agent要完成一个稍微复杂点的任务，需要串起十几个技能，中间的参数传递、上下文衔接变得异常复杂，模型出错率反而更高了。

反过来也有走极端的，把所有东西都塞进一个"超级技能"，内部用一大堆条件分支来处理不同场景。这种做法的缺点是技能内部逻辑变成了黑盒，一旦某个环节出错，排查成本非常高，而且技能很难复用——你会发现"生成周报"和"生成月报"明明大量逻辑重叠，却因为被写死在两个大技能里，只能各维护一套。

我现在的实践经验是：技能粒度应该以"一个可独立验证的业务动作"为单位。什么叫可独立验证？就是这个技能做完之后，产出的结果可以被明确地判断"对不对"。比如"从数据库查询原始数据"是一个技能，"生成对比分析报告"是一个技能，"将报告格式化推送到企微群"又是一个技能。每个技能内部可以有多个步骤，但这些步骤服务于同一个业务目标，对外暴露的输入输出是清晰的。

判断粒度合不合适，我还有一个很笨但很有效的办法：给每个技能写文档，如果写文档的时候发现有超过20%的篇幅在描述"什么情况下不该用这个技能"，那大概率是粒度拆错了。真正好用的技能，场景应该是收敛的。

2.3 技能的输入输出契约：一切稳定性的根基

工程师都知道"约定优于配置"这句话，在Agent技能设计里，输入输出契约就是那个"约定"，而且它的重要性远高于传统软件开发。原因是传统接口的调用方是代码，行为是确定的；但技能的调用方是模型，模型的"理解"天然存在波动。如果技能定义里参数含义模糊、输出格式不严格，模型就会在边缘情况下产生各种意想不到的理解偏差。

我在项目里定义的技能契约，一般包含这么几块：技能名称、适用场景描述、输入参数表（包含参数名、类型、取值范围、默认值、必填与否）、输出格式定义、执行步骤说明、错误处理策略，以及几条"使用注意"。其中最容易被忽视的是"适用场景描述"——这段文字不参与技能内部的执行，但它写得清不清楚，直接决定模型会不会在错误的时候调用这个技能。

输出格式方面我也吃过亏。早期我们让技能自由输出文本，结果模型写报告的风格每天都在"微调"，今天用表格明天用列表，今天先总结后明细明天先明细后总结。后来我们把输出格式全部改成严格的schema约束，跟工具调用的function calling类似，必须输出结构化字段，再由渲染层负责展示。这一步实施之后，输出的稳定性有了质的提升。

2.4 技能注册表：让Agent知道"自己会什么"

有了技能模块，下一步就是解决"Agent怎么知道自己有哪些技能可以用"的问题。这就是技能注册表的作用。从实现上讲，它就是一个结构化的清单，每次模型做规划之前，系统会把注册表里的技能描述注入到上下文中，让模型根据用户需求挑选合适的技能组合。

这个环节有一个性能陷阱。当技能数量从几个增长到几十个的时候，把所有技能描述全量塞给模型，会占用大量上下文窗口，不仅变慢，还可能干扰模型对核心信息的注意力。我在项目里做了一级粗筛：先根据用户请求的语义做一个技能召回，只把相关性高的几条技能描述注入上下文。这一步用的是轻量级的向量检索，命中率实测下来95%以上，而且大幅节省了Token消耗。

注册表里除了技能本身的描述，我还会维护一个"技能间关系"的字段——标注哪些技能经常搭配使用、哪些技能存在前置依赖。这个信息对模型做任务规划很有帮助，相当于给模型一张"地图"，让它知道流程可以怎么走，而不是每次都靠模型自己摸索。

3. 技能模块的完整拆解：以"数据指标对比分析"为例

3.1 技能内部的五个层次

纸上谈兵没什么意思，我拿一个真实的技能模块出来拆开看。这个技能叫"数据指标对比分析"，它解决的问题是：给定一个业务指标和两个时间周期，自动从数据库取数、计算变化率、识别异常波动、并输出一份带自然语言解读的分析结果。

整个技能内部我分成了五层。最底层是数据访问层，负责连接不同的数据源——可能是MySQL、ClickHouse，也可能是内部API，这一层对上层屏蔽了数据来源的差异。再往上是计算层，负责指标口径的核对、同环比的计算、异常检测算法（我们用的是简单但有效的3σ原则加趋势判断）。第三层是语义层，把计算结果转成自然语言结论，比如"华东区销售额环比下降12.3%，超过阈值，需要关注"——这一层我通常会写清楚语言模板，防止模型自由发挥出奇怪的说法。

第四层是组装层，把数据结果、结论文本、图表参数按标准格式聚合成结构化输出。最上面一层是校验层，检查输出结果是否满足技能定义里的schema要求，不满足就触发重试或报错。分层的核心理念是，每一层只干一件事，模型只在"语义层"和"组装层"参与文本生成，计算和数据操作全部由代码控制。

3.2 技能定义文件里到底写了什么

下面是一个简化后的技能定义文件示例，真实项目里会复杂一些，但核心结构可以参考：

skill: name: data_metric_compare description: 对比分析指定业务指标在两个时间周期内的变化情况，输出结构化报告。 适用场景: - 用户要求分析同比/环比变化 - 用户要求对比两个时间段的表现 - 用户需要指标波动的解释说明 输入参数: metric: type: string required: true description: 业务指标名称，必须在系统指标字典中存在 current_period: type: string required: true description: 当前分析周期，格式为 YYYY-MM-DD ~ YYYY-MM-DD baseline_period: type: string required: true description: 对比基准周期，格式同 current_period 输出格式: type: object properties: metric_name: string current_value: number baseline_value: number change_ratio: number is_abnormal: boolean abnormal_reason: string summary_text: string 执行步骤: - 校验指标名称是否在指标字典中 - 从数据源读取当前周期和基准周期的聚合值 - 计算变化率和差异绝对值 - 根据阈值规则判断是否存在异常波动 - 调用语义生成层撰写解读文本 错误处理: - 指标不存在: 返回明确错误信息，不尝试猜测指标含义 - 数据为空: 返回空数据提示，不生成虚假结论

这个文件看起来简单，但每一行都有讲究。拿"适用场景"来说，当初我们没有认真写这段，结果模型经常拿这个技能去回答"今天周几"这种问题，不是模型蠢，而是描述不够精确。后来我把"适用场景"写成三四条具体的句子，误用率立刻降下来了。"输入参数"的类型和格式标注也很关键，如果不写清楚格式，模型可能给你传一个"上周"这样的自然语言值，导致解析层崩溃。

3.3 为什么技能必须包含"错误处理"而不是让模型自由发挥

很多团队在写技能定义时，完全没有错误处理的部分。他们的逻辑是：反正模型很聪明，遇到问题它会自己想办法。这句话在某些场景下成立，但在生产环境里非常危险。模型"自由发挥"处理错误，最常见的结果是编造一个看似合理的结果，或者反复尝试同一个错误操作浪费时间。

我举个例子。有一次我们的分析技能在半夜执行任务时，发现目标数据库连接超时，模型没有报告错误，而是基于上一次的缓存数据继续生成了一份报告，而且完全没有标注数据时效性问题。第二天早上业务团队看到报告后，差点基于过期数据做了决策。从那之后，我把所有技能的错误处理策略统一成三条原则：第一，拿不到数据就明确说拿不到，绝不编造；第二，执行失败就按定义的兜底流程走（比如发一条需要人工关注的提醒），绝不静默吞掉异常；第三，重试不做无脑循环，最多试两次，第二次失败必须触发告警。

这条经验也改变了我们对模型能力边界的认知。模型擅长的是理解和生成，但"严谨性"这件事不能依赖模型自觉，必须通过工程手段来兜底。技能里的错误处理，就是第一道兜底防线。

4. 多技能协作与编排：从"单个技能"到"工作流"

4.1 模型规划与技能编排的边界在哪里

单个技能设计得再完善，也只是一个零件。真实业务场景里，Agent通常需要串起多个技能来完成一个完整的任务流。比如"生成一份竞品周报"，至少要经历：收集数据（网页抓取技能）、清洗去重（数据清洗技能）、指标分析（对比分析技能）、文本生成（报告撰写技能）、推送分发（消息通知技能）。这个编排过程应该由谁来主导？模型还是预定义的流程？这是每个Agent开发者都要回答的问题。

我的观点是：能用流程固定的，不要依赖模型临场规划。道理很简单，模型规划的不确定性，是生产系统最大的不稳定因素。同一个任务，模型今天可能规划三步完成，明天可能规划五步，每一步之间的数据交接还可能出岔子。对于业务固定、链路清晰的任务，直接用工作流编排引擎把技能的调用顺序定义死，只有遇到真正的意外情况时，才把控制权交还给模型。

那模型规划还有用吗？用，但用在那些真正需要动态决策的任务上。比如用户提出一个开放式需求，系统需要从技能库里挑选合适的技能组合，这种时候模型的规划能力就很重要。我们内部的做法是双轨制：跑批任务全部走预设工作流，交互式任务允许模型动态规划，但规划结果必须经过一个合法性校验器，检查技能是否存在、参数是否齐全、依赖是否满足。

4.2 技能编排中的上下文传递技巧

多技能协作最常见的工程难点，是上下文在不同技能之间怎么传递。我见过很多实现，把前一个技能的所有输出一股脑塞给下一个技能，结果上下文窗口迅速膨胀，而且里面大量无关内容干扰了模型对关键信息的提取。

我的做法是设计一个"共享上下文"结构，整个工作流内所有技能共享这个结构，但每个技能只能写入自己负责的字段，读取时也只读取跟自己相关的部分。比如分析技能负责写analysis_result字段，报告技能读这个字段生成文本，同时报告技能还需要原始数据的概要信息，那它直接引用raw_data_summary字段，而不是去读完整的原始数据集。这样做的好处是：上下文可控、信息不会因为传递而丢失、每个技能的执行结果都有明确的落点，便于审计和排查。

另外还有一个小技巧，就是每个技能执行完，在当前上下文中追加一段"执行摘要"——一两句话说明这个技能做了什么、产出了什么、有没有异常。这段摘要对模型后续的决策非常关键，它相当于一个"记忆锚点"。我们在实践中发现，加了执行摘要之后，模型在长链路任务中"忘记前面做了什么"的错误率下降了一半以上。

4.3 工作流编排的失败模式与降级策略

流程编排看上去是"按顺序调用技能"那么简单，但真实跑起来，你会遇到各种各样的失败模式。我给你盘点一下最常见的几种：技能A成功但技能B失败，整个流程要不要回滚？技能A输出的数据格式跟技能B期望的不一致，谁来负责转换？某个技能长时间无响应，是继续等待还是超时跳过？技能链路中出现循环依赖，怎么检测？

我们的处理策略有几条硬性规则：第一，所有技能调用必须有超时设置，超时后默认走失败分支；第二，关键技能（比如数据写入类）失败时，整个流程中断并告警，不允许继续往下走；第三，非关键技能（比如美化格式）失败时，允许跳过并使用默认值，但要在最终结果里标注"部分内容未生成"；第四，流程状态全量落盘，每一步的输入输出都记录在案，这样排查问题的时候能找到准确的现场。

降级策略这块，我的核心原则是"宁可让用户看到部分结果，也不要让用户看到错误结果"。比如报告生成流程里，如果图片渲染技能挂了，我们不会让整个报告失败，而是生成一份纯文本报告并标注"图表生成失败，已转为文本模式"。用户拿到的是一份可用的结果，同时系统自动发起告警通知维护人员处理。这种体验比"流程执行失败请稍后重试"好太多了。

5. 实战案例：用技能体系搭一个"竞品情报分析Agent"

5.1 需求拆解与技能选型

光讲理论没有说服力，我拿一个完整案例收尾。我们当时要做的是一个"竞品情报分析Agent"，目标用户是市场部的同事。他们的日常工作之一是每周收集竞品动态，包括竞品官网更新、招聘信息变化、社交媒体动态、第三方平台的版本发布记录，然后整理成一份周报。

需求拆解下来，核心能力包括四块：多渠道信息采集、去重归类、趋势对比、报告生成。对应到技能体系，我们设计了五个技能：网页信息采集技能、信息清洗去重技能、变更识别技能（判断某个竞品这周跟上周相比有什么变化）、趋势分析技能、周报生成技能。前四个是处理型技能，最后一个是把前面所有处理结果结构化输出的报告技能。

这个案例我觉得很有代表性，因为它覆盖了技能体系的多种典型场景：有外部依赖（网页抓取）、有数据加工（清洗去重）、有对比推理（变更识别）、有分析判断（趋势分析）、有内容生成（周报生成）。而且每个技能的成败边界都很清晰，非常适合用来验证技能设计的好坏。

5.2 关键实现：变更识别技能的设计细节

这个案例里最有意思、也最需要细致设计的，是"变更识别技能"。它做的事情是：拿到同一个竞品网站这周和上周的抓取快照，识别出哪些内容发生了变化，并判断变化的重要性。听起来简单，做起来有好几个坑。

第一个坑是不同页面的噪音太多，导航栏、版权信息、Cookie提示几乎每周都一样，如果不做内容归一化处理，这些噪音会被识别成"变更"，导致报告里全是无效信息。我们的做法是给页面做区块切割，只保留主体内容区域再做diff。第二个坑是"变更"的语义理解——同样是"新增了一个职位"，在"关于我们"页面出现可能只是普通的团队扩张，在"招聘"页面出现则可能意味着业务方向调整。为了处理这个语义差异，我们给变更识别技能增加了一组注意力规则：优先关注招聘页、产品页、定价页的变更，并按变更内容做多级分类。

第三个坑是模型的输出置信度不可靠，它可能把一次普通的文案措辞调整，判断成"产品战略变化"。我们用的妥协方案是：所有判断结果必须同时输出"原文摘要"和"判断理由"，如果判断为高风险变更，必须附上原文截图作为证据。这样一来，即使模型判断有偏差，人工审核时也能快速还原现场，不至于被误导。

5.3 实操效果复盘：哪些技能真正提升了效率

这个Agent上线跑了两个月之后，退役了原有的人工周报流程，这里有几组数据值得一提。在技能体系还未充分打磨的第一周，周报生成的成功率只有60%左右，大部分失败集中在采集环节的网页反爬，以及信息清洗阶段的误删。随着技能定义逐渐完善，特别是加入了错误处理策略和重试机制后，成功率稳定在了95%以上，剩余失败场景全部会自动告警，由人工兜底修复。

有两类技能升级带来的收益最明显。一类是"信息清洗去重技能"，过去模型经常把同一新闻的不同转载源当作不同信息，导致周报里出现重复内容；后来我们在技能内部加了URL归一化和正文相似度计算，重复率从30%降到了5%以下。另一类是"周报生成技能"，过去生成格式经常漂移，业务方每周都要手动调整排版；后来数据完全结构化之后，渲染层面彻底解耦，格式问题基本绝迹。

这个案例也验证了我开头那个判断：Agent的上限由模型决定，但下限由技能体系决定。没有一套设计良好的技能体系，再强的模型也只能是一个聪明的玩具，成不了可靠的生产工具。而技能体系的构建，本质上是一个把"不确定性"不断转化为"确定性"的过程——每定义一个技能，就等于把一类模糊的能力诉求，变成了一个边界清晰、可执行、可验证的工程模块。

最后分享一个我在整个项目里体会最深的小技巧：给Agent加技能这件事，一定要跟着真实业务线索走，哪怕只是顺手的一小步，也别急着做"通用大而全"的技能库。我在实践中发现，最好的技能沉淀路径，是先从具体任务里拆出雏形，跑一段时间，等模式稳定了再抽象、再泛化。技能不是设计出来的，是长出来的。这就是agent-skills带给我最大的认知转变。