企业官网建设流程全解析

最近在技术社区里，“一句话画出系统架构图”成了挺热门的演示场景：输入“画一下外卖订单从创建到支付完成的核心链路”，几秒后就能得到一张带服务边界、调用关系和存储设计的架构图。这个功能看起来像“AI 自己会画图”，但真正让结果稳定可用的，并不是模型临时发挥，而是 AI Agent 引入了一种叫Skill（技能）的机制。Skill 把画图所需的知识、输出模板、校验规则提前固化下来，让模型在收到一句话时知道该按什么流程工作、该输出什么格式、该避免哪些错误。

本文会围绕“一句话画出系统架构图”这个现象，拆解 Skill 的工作方式，并带读者从零实现一个可复用的架构图生成 Skill。文章会覆盖 Skill 与提示词、Agent、Tool 的区别，文件结构如何设计，SKILL.md 中的规则怎么写，以及如何用 Mermaid 或 Draw.io 完成渲染验证。最后还会给出常见失败场景的排查路径，以及把 Skill 作为团队资产落地时要注意的事项。读者可以在 Claude Code、Codex、Trae 或任何支持 Skill 目录的 Agent 工具中复现这套流程。

1. 一句话生成架构图：先拆开它背后的调用链路

1.1 从用户输入到成品图的四个阶段

“一句话画图”看起来只有一个输入框和一个结果图，但它内部至少经历了四个阶段。

第一个阶段是意图识别。用户输入的“画一张电商订单系统的架构图”，模型需要先判断这是一个架构图生成任务，而不是代码编写或文本总结任务。这个判断除了依赖模型本身的理解能力，也依赖 Skill 的触发条件。如果 Skill 的描述写得足够精确，Agent 会优先加载对应技能。

第二个阶段是结构化展开。模型把“电商订单系统”这种模糊概念拆成边界、节点、依赖关系，例如前端、网关、订单服务、库存服务、支付服务、数据库，以及它们之间的调用方向。这个阶段最容易失控的地方是节点数量膨胀、命名不统一、关系方向混乱。

第三个阶段是图语言转换。模型把内部结构转成 Mermaid、PlantUML 或 Draw.io XML 等文本形式。Mermaid 是当前最常见的选择，因为它语法简洁、渲染工具多、容易被模型生成。

第四个阶段是渲染验证。文本形式的图语言被送入渲染器，生成可视化的架构图。这个阶段负责暴露语法错误和结构问题，例如节点未定义、连线指向不存在的节点、标签中包含非法字符等。

这四个阶段如果全部靠模型的临时推理完成，结果会非常不稳定。Skill 的作用就是在第二阶段和第三阶段之间插入一套固定规则，把“自由发挥”变成“按模板填内容”。

1.2 为什么 Skill 比“直接写一段画图提示词”更稳定

很多开发者最初会尝试把画图要求直接写在系统提示词里，例如在上下文中写“请用 Mermaid 画架构图，注意分层清晰”。这种方式在小规模、短会话中有效，但存在明显问题。

一是提示词会随上下文变长而被稀释。Agent 处理长会话时，如果没有 Skill 的自动加载机制，模型可能会遗忘画图规范，尤其在多轮交互之后。

二是规则不可复用。换个项目、换个场景，又要把同样的画图规则复制一遍。写错一个字、漏掉一段，输出质量就出现波动。

三是缺少示例支撑。架构图涉及多种风格：分层架构、微服务调用链、部署拓扑、业务链路。直接写提示词很难把每种风格都讲清楚，而 Skill 可以附带多个 example 文件作为少样本示例。

四是不可版本化。提示词无法像文件一样进入 Git 仓库，无法记录“这个模板为什么改、谁改的、改了之后对哪些图有影响”。

Skill 的本质是把“画架构图应该怎么做”这套知识从对话上下文中抽离出来，变成一个独立、可加载、可版本化的能力包。当 Agent 识别到用户请求符合 Skill 的触发条件时，才把这个能力包注入当前上下文。平时它不占用任何 token，也不会干扰其他任务。

1.3 架构图背后的三种常见图语言

Skill 不直接画图，它生成的是图语言的文本。理解这一点很重要，因为它决定了输出能否被渲染。

实际项目中，Mermaid 是最适合“AI 生成”的格式，因为它的语法容错性相对好、生态工具多。PlantUML 则适合需要严谨 UML 语义的场景。Draw.io XML 适合最终需要人工持续维护的大型图。

注意：无论选择哪种语言，Skill 的职责都是生成“可渲染的文本”，而不是直接输出图片。图片应由渲染器完成，这样既方便调试，也方便把图文件纳入版本管理。

2. Skill 机制速览：它和提示词、Agent、工具的区别

2.1 Skill 是什么：一个目录和一个 SKILL.md

在常见实现里，一个 Skill 就是一个目录，目录里至少包含一个SKILL.md文件。这个文件带有 YAML frontmatter，描述技能的元信息，正文则描述技能的完整工作方式。

architecture-skill/ ├── SKILL.md ├── examples/ │ ├── ecommerce-order-system.md │ └── payment-flow.md └── references/ ├── mermaid-style-guide.md └── architecture-layers.md

SKILL.md的典型开头：

--- name: architecture-diagram-generator description: 当用户需要生成系统架构图、应用架构图、调用链路图、部署架构图时使用。 输入可以是一句话、一段需求描述或一段代码说明。输出 Mermaid 格式，并解释图的层次关系。 --- # Architecture Diagram Generator 你是一个系统架构图助手。你的任务是把用户的模糊描述转成结构清晰、层次合理的架构图。

这个文件解决的核心问题是“Agent 在什么情况下加载这个技能、加载后按什么标准完成任务”。目录中的examples用来提供示例输出，references用来提供风格规范。这些附加内容只有在 Skill 被加载时才进入上下文，平时不会占用空间。

2.2 Skill、Prompt、Agent、Tool 四者到底什么关系

这个概念容易混淆，尤其是刚接触 Skill 的开发者。

Prompt 是一次性输入。它是用户和模型之间的指令，说话就生效，会话结束就消失。

Tool 是可执行能力。它指向一个真实函数或外部系统，例如“搜索网页”“执行 Shell 命令”“调用数据库”。Tool 强调“能做动作”。

Agent 是执行主体。它利用模型做决策，调用 Tool 完成动作，管理多步任务流程。

Skill 是知识包。它既不像 Prompt 那样是一次性上下文，也不像 Tool 那样直接执行动作，而是一个“按需加载的说明书”。Skill 内部可以描述“你可以使用某个 Tool 去获取信息”，也可以要求“你必须按某种格式输出”。

它们的关系可以这样概括：Agent 是大脑，Tool 是手脚，Skill 是大脑里可按需调取的教材。教材在平时不翻开，当遇到对应题目时才自动打开。

2.3 主流 Agent 工具里 Skill 的常见写法

不同工具对 Skill 的实现细节有差异，但设计思路基本一致：某个目录下放一个技能描述文件，Agent 启动时扫描这些目录，根据用户请求决定是否加载。Codex、Claude Code、Trae 等工具都有各自的 Skill 路径和加载规则，落地前要先确认你使用的工具版本和文档。

在常见实现中，Skill 可能放在项目目录下的.agent/skills或.claude/skills，也可能放在用户全局目录下。放在项目目录里的 Skill 会随代码库提交，适合团队共享；放在全局目录里的 Skill 只对当前机器生效，适合个人工具集。

编写 Skill 时，最关键的不是文件放哪里，而是description写得够不够精准。它直接影响 Agent 的触发判断。描述里应包含触发场景、典型输入、输出格式和不适用场景。例如“当用户需要生成系统架构图、应用架构图、部署架构图时使用。如果用户只是在问概念，不需要生成图片，则不要使用本技能。”

3. 从零编写一个架构图生成 Skill：目录、指令、模板

3.1 目录结构与落盘位置

先建立一个干净的 Skill 目录，命名用短横线连接，避免空格和中文。

mkdir -p architecture-skill/examples architecture-skill/references

目录结构：

architecture-skill/ ├── SKILL.md ├── examples/ │ └── order-system.md └── references/ └── layers.md

在将目录放入 Agent 能识别的路径前，先确认工具支持的 Skill 目录形态。如果当前使用的工具要求每个 Skill 直接放在 skills 根目录，就放 SKILL.md；如果要求按项目名区分，就再套一层外层目录。这个细节不对，Skill 就不会被加载。

3.2 SKILL.md 的核心内容：元信息与工作流程

SKILL.md是技能的主文件。内容分为两大部分：frontmatter 里的元信息，和正文里的工作流程。

--- name: architecture-diagram-generator description: 生成系统架构图、应用架构图、调用链路图、部署图。 适用于用户给出系统名称、需求描述或文本片段并要求可视化时。 输出格式为 Mermaid 架构图，同时给出节点层次说明。 如果不涉及画图，不要使用本技能。 --- # Architecture Diagram Generator ## 目标 将用户的一句话或一段需求描述，转换成一幅结构清晰、可渲染的架构图。 ## 工作流程 1. 从用户输入中提取系统边界、关键模块、外部依赖和数据存储。 2. 将模块按照常见分层组织，例如接入层、应用服务层、领域层、基础设施层。 3. 确定模块之间的依赖方向，用带箭头的连线表达。 4. 为每个节点命名，确保命名统一、无歧义、不含特殊字符。 5. 输出 Mermaid 代码块，并在代码块后补充架构说明。 ## 输出格式 必须使用如下 Mermaid 结构： ```mermaid flowchart LR 用户 --> 前端 前端 --> 网关 网关 --> 服务A 服务A --> 数据库A

校验规则

• 每个节点至少被一个箭头连接，不能出现孤立节点。
• 节点命名不超过 6 个汉字或 12 个英文字符。
• 不使用 Emoji。
• 连线必须标注方向。
• 如果节点数量超过 12 个，先抽象公共模块，再绘制细节。

示例

参考 examples/order-system.md

这段内容是 Skill 的核心。最关键的是“工作流程”和“输出格式”两部分。工作流程把画图任务拆成可执行的步骤，避免模型一步到位却漏掉关键信息；输出格式则强制模型按固定模板输出，避免每次生成的图结构都不一致。 ### 3.3 输出模板：让模型始终按固定结构输出 架构图生成最容易出现的问题是“模型自由发挥，每张图风格都不同”。解决方式是提供一个固定的输出模板，并告诉模型必须先填充模板，再考虑扩展。 在 SKILL.md 中可以加入一个强约束段落： ```markdown ## 输出模板约束 在输出 Mermaid 代码块之前，先输出如下结构： - 系统边界：列出该系统包含哪些模块，哪些属于外部依赖。 - 分层结构：把模块归入接入、应用、领域、基础设施等层次。 - 依赖关系：用“A 调用 B”的句式写出关键依赖。 确认上述结构完整后，再将其转换为 Mermaid 代码。

这种做法利用了模型在纯文本结构描述上更稳定的特点。先出文本结构，再转图语言，错误率会比直接生成 Mermaid 低很多。

3.4 用校验规则约束生成质量

校验规则不是摆设，它是 Skill 区别于普通提示词的重要环节。每一行约束都应能回答“防止什么错误”。

例如“节点命名不超过 6 个汉字”防止的是中文长名词在 Mermaid 渲染时出现换行错乱和辨识困难；“不使用 Emoji”防止渲染器兼容性问题；“节点数量超过 12 个先抽象公共模块”防止大图变成一团乱麻。每个约束背后都有实际失败样本作为依据。

可以在 SKILL.md 中加入一段“输出前自检”：

## 输出前自检 输出 Mermaid 之前，检查以下问题： 1. 是否存在没有连线的孤立节点？如果有，删除或补充连线。 2. 每个节点名称在整张图中是否只出现一次？ 3. 箭头方向是否代表真实的依赖或调用方向？ 4. 节点数量是否超过 12 个？如果超过，是否需要拆成多张图？ 5. 代码块是否正确标记为 mermaid？

这样模型在生成时会先做一轮内部检查，减少明显的结构性错误。

4. 完整案例：用一句话触发并验证一张电商系统架构图

4.1 场景设定与运行环境

下面用一个最小案例验证 Skill 的效果。假设读者已经有一个支持 Skill 机制的工具，并且 Skill 目录已经放在正确位置。如果暂时没有可用工具，也可以在 Claude 或类似对话型产品中把SKILL.md内容直接粘贴为上下文，同样可以验证规则设计的合理性。

创建一个示例文件examples/order-system.md，内容是一份参考输出，给模型提供少样本示例：

## 输入示例 画一张电商下单系统的系统架构图，包含前端、网关、订单服务、库存服务、支付服务和数据库。 ## 预期结构 系统边界：电商下单系统。 分层结构： - 接入层：前端、网关 - 应用层：订单服务、库存服务、支付服务 - 基础设施：订单数据库、库存数据库、支付数据库 依赖关系： - 前端调用网关 - 网关调用订单服务 - 订单服务调用库存服务 - 订单服务调用支付服务 - 订单服务访问订单数据库 - 库存服务访问库存数据库 - 支付服务访问支付数据库 ## Mermaid 输出 ```mermaid flowchart LR 用户 --> 前端 前端 --> 网关 网关 --> 订单服务 订单服务 --> 库存服务 订单服务 --> 支付服务 订单服务 --> 订单数据库 库存服务 --> 库存数据库 支付服务 --> 支付数据库

### 4.2 触发与生成过程 准备好之后，在 Agent 中输入： ```text 画一张电商下单系统的系统架构图，包含前端、网关、订单服务、库存服务、支付服务和数据库。

正常情况下，Agent 会命中 Skill 的触发条件，加载SKILL.md，参考示例文件，然后经过以下步骤：

1. 识别用户提到的六个核心元素。
2. 判断这些元素应该归入接入层、应用层还是基础设施层。
3. 补充示例中没有明确说出的“用户”边界，用于表达外部入口。
4. 构建依赖关系，例如“订单服务访问订单数据库”“支付服务访问支付数据库”。
5. 按模板输出 Mermaid 代码块，并附带架构说明。

最终输出应接近上一节的 Mermaid 代码。如果 Agent 没有输出代码块，或者输出的图结构混乱，说明 Skill 没有成功加载，或者 description 触发条件写得不够准确。

4.3 渲染验证：确认图真的能被画出来

Mermaid 文本生成之后，还需要验证它能否被渲染。将代码块复制到 Mermaid Live Editor 或支持 Mermaid 的 Markdown 编辑器，渲染成功后应该能看到一张从左到右的架构图。

验证标准可以按下面几条检查：

• 图中是否有孤立节点。任何节点如果没有任何连线，说明结构描述不完整。
• 连线方向是否符合预期。例如“前端调用网关”应该是前端 --> 网关，而不是反向。
• 节点命名是否清晰。过长、重复、含特殊字符的节点名在渲染时容易出现换行或报错。
• 图是否表达了系统边界。“用户”作为外部角色，不能混入内部模块。

使用 Draw.io 时思路相同，只是把 Mermaid 换成 XML 或通过导入功能转换。对日常博文和团队沟通文档来说，Mermaid 是性价比最高的方案，因为它可以直接嵌入 Markdown，提交到 GitLab、GitHub 或内部 Wiki 后自动渲染。

5. 为什么“一句话”能稳定产出：Skill 规则设计的关键点

5.1 明确架构图的类型、视角和抽象层级

架构图不是一个单一概念。模型如果不知道用户要哪种图，就会按自己默认理解生成。Skill 在生成前应先判断图类型。

在 SKILL.md 中，可以加一句强制规则：

## 类型判断 开始生成前，先判断用户需要的是应用架构、系统架构、部署架构还是业务流程链路。 如果用户没有明确说明，默认生成应用架构图，并用文字说明当前视角。

这一条的作用是减少模型的默认偏好。很多模型默认倾向输出类似 UML 的组件图，但在实际架构文档中，分层表达通常比组件关系更直观。

5.2 输出约束要具体到可执行

“画得清晰一点”这种约束对模型没有意义。好的约束必须能转换成具体判断标准。

推荐在 SKILL.md 中写这类约束：

• 节点数量默认不超过 12 个，超过时先抽象公共层。
• 节点命名默认用“模块名”，不用“xxx模块的详细实现”这种长句。
• 箭头数量控制在节点数量的 1.5 倍以内，避免出现任意两点都连线的混乱情况。
• 每个箭头必须有业务含义，例如“调用”“访问”“回调”，不允许只有方向没有语义。

其中“箭头数量控制”这个约束经常被忽略。如果所有节点之间都画箭头，架构图就失去了信息过滤功能。架构图的价值在于突出关键依赖，而不是把所有关联全部铺满。

5.3 先输出文本结构，再转 Mermaid，能显著降低错误率

直接让模型生成 Mermaid 不是不行，但一旦系统复杂，语法错误和结构错误会同时出现，排查非常痛苦。更好的做法是在 Skill 中强制两段式输出：

第一段输出文本结构，包括系统边界、分层、依赖关系。第二段再把这些结构转成 Mermaid。

原因是模型在处理逐步展开的文本结构时，更不容易丢失信息。文本结构相当于“草稿”，Mermaid 相当于“成稿”。草稿阶段的纠错成本低，成稿阶段的渲染报错更直观。两段式输出还能让调用者先检查内容是否正确，再花时间去渲染，避免“辛辛苦苦渲染完发现业务语义不对”。

5.4 触发条件写得越精确，误用率越低

一个 Skill 如果 description 过于宽泛，Agent 会在不合适的场景加载它，比如用户只想了解架构概念却被强制输出图。过于狭窄又会让 Agent 在该用的场景不加载。

推荐写法：

description: 生成系统架构图、应用架构图、调用链路图、部署架构图。 当用户输入描述一个系统或服务并要求可视化时使用。 当用户只是询问概念、不需要输出图片时不要使用。

这里的“不要使用”不是可有可无的补充，它有实际作用。很多 Agent 在判断技能是否匹配时，会优先选择 description 最完整的那个。加入负向描述能帮助模型排除无关场景。

6. Skill 画图失败的常见问题与排查路径

6.1 高频问题对照表

6.2 推荐排查顺序

遇到“一句话画图失败”时，不要一开始就怀疑模型能力。建议按以下顺序排查：

1. 先看输入是否清晰。系统边界、关键组件、依赖关系是否都能从一句话中提取。输入太模糊时，任何模板都救不了。
2. 再看 Skill 是否被加载。很多工具会在日志或调试面板中显示加载了哪些 Skill。如果没有加载，优先改 description。
3. 再看 SKILL.md 本身。有没有输出模板、有没有校验规则、示例文件在不在正确路径。注意：SKILL.md 中引用的examples/xxx.md如果路径写错，模型即使在加载 Skill 后也拿不到示例。
4. 再看 Mermaid 语法。把输出代码复制到 Mermaid Live Editor，如果渲染失败，通常有错误行提示。
5. 最后才考虑是否要调模型或调参数。多数情况下问题出在前四步。

注意：验证时不要只看“模型生成了几张图”，还要验证“生成了几次完全相同的结构”。稳定性是架构图 Skill 最有价值的输出指标。

6.3 常见坑与预防写法

第一个坑：在 SKILL.md 里写“画得漂亮一点”这种不可执行的要求。应改为“节点命名统一为模块名，连线统一标注调用或访问关系”。

第二个坑：在 description 里堆了大量关键词，导致模型在无关任务中也加载 Skill。应改为“当用户需要生成架构图时才使用，如果只是讨论概念则不使用”。

第三个坑：示例文件过长。示例是为了少样本学习，但太长会占用上下文，反而干扰生成。示例保持在 30 行以内，只覆盖一种典型场景即可。

第四个坑：为了追求美观在 Mermaid 中使用 Subgraph 嵌套多层。Subgraph 在复杂图中经常出现关系交叉，渲染时非常容易乱。生产环境建议默认不用 Subgraph，改用“模块名前缀”表达分组，例如订单服务、库存服务本身就通过前缀区分了服务归属。

7. 从个人实验到团队资产：Skill 的落地与扩展

7.1 学习环境：先复现，再改规则

如果你只是想验证“一句话画图”的效果，不建议一上来就写复杂规则。先创建一个最小 SKILL.md，只包含触发条件、输出格式和工作流程三步，跑通一次渲染，确认这个链路没有问题。

之后每遇到一次失败，再往 SKILL.md 里加一条规则。这种“失败驱动”的规则积累方式，比一次写完所有规则更可靠。因为你能准确知道每条规则对应哪个失败场景，而不是写了大量用不到的约束。

个人学习时可以准备一个iteration-log.md，记录每次修改 Skill 后的失败样例和修改内容。后续优化时只需要看这个日志，不用从零回忆。

7.2 团队实践：把 Skill 当作架构资产管理

当 Skill 在个人环境中稳定后，可以考虑把它放进团队仓库。这里的要点不只是“把文件传上去”，而是按工程规范管理。

SKILL.md 要有版本记录。即使工具不强制，也应在自己的项目里记录变更。架构风格会演进，依赖关系会变化，Skill 里的模板和示例必须同步更新。长时间不维护的架构 Skill，会让模型继续输出已经废弃的服务名，误导读者。

示例文件要保持最小化。examples目录用于少样本示例，不是历史案例存档。建议只保留一到两个能代表当前架构风格的示例，其他历史案例移到文档区，避免每次加载 Skill 时把不相关示例带入上下文。

团队评审时，重点关注 SKILL.md 里的四点：触发条件是否准确、输出格式是否与团队文档规范一致、校验规则是否能防止已知错误、示例是否反映当前系统结构。

7.3 三个可复用清单

Skill 发布前检查清单：

• description 是否同时包含正向触发场景和负向排除场景
• SKILL.md 是否有工作流程、输出格式、校验规则三个核心段落
• 是否有一个 30 行以内的示例文件
• 是否显式声明不使用 Emoji
• 是否设置了节点数量和箭头数量上限
• 是否能在空环境中按文档步骤成功运行

架构图输出质量检查清单：

• 所有节点是否都已定义
• 是否存在孤立节点
• 箭头方向是否表示真实的调用或依赖关系
• 节点命名是否统一、简洁、无重复
• 是否已经按“接入层、应用层、基础设施层”完成分层抽象
• 渲染后是否可以放入文档或代码仓库

团队落地检查清单：

• Skill 目录是否已纳入 Git 管理
• 是否有人负责维护 SKILL.md 和示例
• 是否在架构评审中使用同一套图语言和模板
• 新成员是否能通过示例快速理解架构风格
• SKILL.md 是否包含变更记录
• 是否在试运行阶段定期统计生成失败的类型和频率

7.4 可以继续扩展的方向

架构图生成只是 Skill 的一个入门场景。理解这套机制后，可以继续把下述能力做成新的 Skill：基于代码生成时序图、将旧系统文档转换为新版架构图、把需求文档转成部署架构基线、统一团队架构图命名规范。

真正让 Skill 产生价值的不是“AI 能画图”这个现象，而是把团队对架构的表达标准固化下来。当每个层级都遵循同一套模板和校验规则时，架构图才不只是“一张图”，而是可沟通、可审查、可演化的设计文档。对新手来说，最好的练习是从本文的电商系统案例开始，先跑通一次渲染，再把失败案例逐条转成规则，最后把规则分享给团队。这条路比到处收藏“画图提示词”要扎实得多。