企业官网建设流程全解析

之前团队画系统架构图，通常要走一套固定流程：先开会讨论模块边界，再打开 draw.io 或者 ProcessOn 拖半天方框箭头，等架构图终于能看了，项目已经迭代了两轮，图又过时了。最近圈子里开始流行一种新玩法：给 AI 编程助手配一个 Skill，让它根据一句需求描述，自动输出一张结构清晰、可以直接贴进技术文档的系统架构图。本文就围绕这个思路，把 Skill 的原理、文件结构、完整代码和接入步骤拆开讲一遍，方便你在自己的项目里直接复用。

先说明本文适合哪些读者：正在使用 Claude Code、Codex、Trae 等 AI 编程工具，想进一步定制工具能力的开发者；需要频繁输出架构图、时序图的技术文档写作者；以及想理解“Agent Skill”到底是什么、和普通 Prompt 有什么差别的初学者。读完你会掌握 Skill 的标准目录结构、SKILL.md 的编写规则，以及一个可运行的“架构图生成 Skill”完整示例。

1. 为什么“一句话画架构图”会火

1.1 画架构图这件事，远比想象中费时间

很多开发者在接到“把系统架构整理成图”这个任务时，第一反应是打开绘图工具一格格拖拽。小系统还好，一旦模块超过 10 个，方框、箭头、分层、跨服务调用关系会迅速把图撑成一团乱麻。

更麻烦的是维护成本。代码里新增了一个服务，架构图就得跟着改；某个模块从 MySQL 迁到了 PostgreSQL，图里的数据存储节点也要改。人工维护的架构图，本质上很难跟得上代码演进。这也是为什么很多团队的项目文档里，架构图往往停留在“第一版”，后面的系统早就和图纸对不上了。

1.2 Skill 让 AI 从“聊天”变成“干活”

普通情况下，你让大模型画架构图，它可能会给你一段建议，或者一段描述性的文字，很少能直接变成可发布的文件。即便能输出，也缺乏稳定的流程，每次生成的结果风格不一。

Skill 解决的问题是：把“画架构图”这件事，从一次性的对话请求，变成一套可复用的、带脚本和约束的专业流程。AI 工具加载 Skill 后，会按照 SKILL.md 里的规定步骤处理输入，必要时调用 Python 脚本完成结构化转换和文件输出。用户要做的只是描述系统，剩下的组件拆解、关系梳理、图表生成，都由 Skill 自动完成。

1.3 热点背后的技术本质

最近 Skill 相关讨论在开发者社区非常热，搜索热词里大量出现 Codex Skill、Claude Code Skill、Trae Skill、Agent Skill 等词条，本质上反映的是同一个趋势：AI 编程工具的竞争，已经从“谁能生成更多代码”转向“谁能被开发者定制成更顺手的工程工具”。Skill 就是这种定制能力的载体。架构图生成只是其中一个典型场景，同样的机制还可以用来写测试、做代码评审、生成数据库设计文档等。

2. 理解 Agent Skill：从概念到运行机制

2.1 Skill 是什么

Skill 可以理解为一个“自包含的指令包”。它通常由一个目录组成，里面包含一份 SKILL.md 说明文件，可能还包含脚本、模板、示例数据。当 AI Agent 被触发并加载这个 Skill 时，它会按照说明文件中的步骤，完成一类特定任务。

以画架构图为例，普通情况下你可以直接对大模型说“帮我画一个订单系统架构图”，模型会基于训练知识给出一个随机风格的回答。但如果你已经把“架构图生成 Skill”配置好，模型会严格按照你定义的组件类型、关系格式、输出规范来工作，质量稳定且可验证。

2.2 Skill 和普通 Prompt 的区别

很多人觉得 Skill 不就是一段写得比较长的 Prompt 吗？这个理解不算错，但不完整。

普通 Prompt 是临时写给模型看的指令，关键词就是“临时”。它不具备文件结构，不能携带脚本，也很难被版本管理。今天你写了一段很顺手的画图 Prompt，明天想复用，可能已经找不到了。

Skill 则是有结构的工程产物。它放在固定目录下，有元信息描述触发条件，有处理流程，必要时还附带可执行的脚本。同一份 Skill 可以分发给团队中的其他人，也可以放进 Git 仓库做版本管理。简单说，Prompt 是对话，Skill 是工具。

2.3 Skill 和 Agent 的区别

这里有一个容易混淆的概念。Agent 是能自主规划、调用工具、执行多步骤任务的 AI 系统，Skill 是 Agent 的能力扩展包。一个 Agent 可以拥有多个 Skill；Skill 则服务于 Agent，让它在特定领域表现更专业。

可以这样类比：Agent 是“员工”，Skill 是“岗位培训手册 + 工具箱”。员工本身具备学习能力，但只有拿到对应岗位的培训手册和工具，处理专业任务时才会又快又准。

2.4 哪些工具支持 Skill

目前主流 AI 编码工具都在布局 Skill 能力：

• Claude Code 将 Skill 放在.claude/skills/目录下，支持项目级和全局级加载。
• Codex 也在快速迭代，社区中已经出现大量自定义 Skill 的实践。
• Trae 这类 AI IDE 同样提供了类似能力，可以在面板中管理 Skill。

由于各工具的目录约定仍处于快速变化阶段，本文后续示例会以通用的 Skill 结构为主，并在接入环节给出不同工具的路径参考。你实际使用时，最好以对应工具的官方文档为准。

3. 环境准备与通用 Skill 文件结构

3.1 环境要求

为了运行本文的完整示例，环境准备如下：

• 操作系统：Windows / macOS / Linux 均可。
• Python：3.8 及以上版本，用于运行架构图生成脚本。
• AI 编程工具：任意支持 Skill 机制的 Agent 工具，本文以 Claude Code 和 Codex 的目录习惯为例。
• 图表查看工具：VS Code 安装 Markdown Preview Mermaid Support 插件，或者使用 draw.io、Typora 等支持 Mermaid 语法的工具。

版本说明：不同工具的 Skill 加载方式可能不同，示例脚本本身是跨平台的，不需要额外安装第三方 Python 库，只依赖标准库。

3.2 Skill 的通用目录结构

一个标准的 Skill 目录通常长这样：

architecture-diagram/ ├── SKILL.md ├── scripts/ │ └── generate_architecture.py └── examples/ ├── order-system.json └── order-system.mmd

目录中各个文件的职责如下：

3.3 SKILL.md 是 Skill 的灵魂

SKILL.md 通常采用 Markdown 格式，顶部是 YAML frontmatter，包含 name 和 description 两个关键字段。

--- name: architecture-diagram description: 将用户的自然语言系统描述转换为 JSON 架构模型，并生成 Mermaid 架构图文本。 ---

name 是 Skill 的唯一标识；description 非常重要，Agent 会根据描述来决定什么时候加载这个 Skill。写描述时要尽量明确触发场景，例如“当用户提到画架构图、系统架构、architecture、diagram 时使用”，比简单写“生成架构图”更容易被 Agent 准确识别。

4. 核心原理解析：一句话到架构图的调用链路

4.1 第一步：理解自然语言

整个过程的第一步，是 Agent 读取用户的话，例如“请画一个订单中台的架构图，包含前端客户端、API 网关、订单服务、用户服务、MySQL、Redis 和消息队列”。模型需要识别出：哪些是组件，组件之间是什么关系，调用方向如何。

这一步依赖大模型的自然语言理解能力。为了让输出稳定，Skill 必须在 SKILL.md 中明确规定组件类型和关系描述方式，避免模型自由发挥。

4.2 第二步：结构化中间数据

模型把自然语言整理成 JSON 格式的中间数据。这个设计很关键。JSON 是一个独立于生成脚本和渲染工具的中间层，具备以下优势：

• 可校验：可以检查组件 id 是否重复、关系是否引用了不存在的组件。
• 可缓存：同一份架构描述可以反复生成不同风格的图表。
• 可人工审查：在生成图表前，可以先让团队成员确认 JSON 里描述的组件和关系是否正确。

中间数据大概长这样：

{ "title": "订单中台系统架构", "direction": "LR", "components": [ {"id": "web", "name": "Web 前端", "type": "client"}, {"id": "app", "name": "App 端", "type": "client"}, {"id": "gateway", "name": "API 网关", "type": "service"}, {"id": "order", "name": "订单服务", "type": "service"}, {"id": "user", "name": "用户服务", "type": "service"}, {"id": "mysql", "name": "MySQL 主库", "type": "database"}, {"id": "redis", "name": "Redis 缓存", "type": "database"}, {"id": "mq", "name": "消息队列", "type": "middleware"} ], "relationships": [ {"from": "web", "to": "gateway", "label": "HTTPS"}, {"from": "app", "to": "gateway", "label": "HTTPS"}, {"from": "gateway", "to": "order", "label": "RPC"}, {"from": "gateway", "to": "user", "label": "RPC"}, {"from": "order", "to": "mysql", "label": "JDBC"}, {"from": "user", "to": "mysql", "label": "JDBC"}, {"from": "order", "to": "redis", "label": "Redis 协议"}, {"from": "order", "to": "mq", "label": "消息投递"} ] }

4.3 第三步：脚本引擎生成图表

结构化数据确定后，Python 脚本负责把 JSON 渲染成 Mermaid 文本。脚本的任务包括：

• 按 type 把组件划分到不同子图（subgraph）。
• 为每个组件选择合适的节点形状，例如数据库节点使用双圆括号。
• 将 relationships 中的调用关系转化为箭头表达式。
• 最终输出 .mmd 文件，供 Mermaid 兼容工具渲染。

4.4 为什么选择 Mermaid 作为图表 DSL

Mermaid 是一种用文本描述图表的 DSL（领域特定语言）。相比直接让 AI 生成图片文件，文本 DSL 更适合 Agent 场景，原因有三点：

• 文本可靠：AI 生成文本远比生成图片文件稳定。
• 跨工具兼容：同一个 .mmd 文件可以在 Typora、draw.io、VS Code、GitLab 中渲染。
• 可版本管理：架构图进入 Git 仓库后，diff 也能看清楚改动。

5. 完整实战：编写一个架构图生成 Skill

5.1 创建目录结构

在任意工作目录下创建架构图 Skill 的目录结构。这里以项目根目录为例：

mkdir -p architecture-diagram/scripts mkdir -p architecture-diagram/examples cd architecture-diagram

5.2 编写 SKILL.md

在 architecture-diagram 目录下创建 SKILL.md。注意，展示 SKILL.md 内容时使用 markdown 代码块，实际文件路径为architecture-diagram/SKILL.md。

--- name: architecture-diagram description: 将用户的自然语言系统描述转换为 JSON 架构模型，并生成 Mermaid 架构图文本。当用户提到画架构图、系统架构、架构设计图、architecture、diagram 时使用。 --- # 架构图生成 Skill 你的任务是根据用户对系统的描述，生成一张清晰、规范、可直接发布的 Mermaid 系统架构图。 ## 处理步骤 1. 从用户描述中提取组件（components）和关系（relationships）。 2. 为每个组件分配 id、name、type，type 取值范围：client / service / database / middleware / external。 3. 将整理后的结构化数据写入临时 JSON 文件，例如 /tmp/arch_input.json。 4. 在 Skill 根目录下执行：python3 scripts/generate_architecture.py --input /tmp/arch_input.json --output /tmp/arch_output.mmd 5. 读取 /tmp/arch_output.mmd 的内容并返回给用户；如果脚本执行失败，则根据 JSON 规则手工构造 Mermaid 文本。 6. 返回文本时，用一句话解释图表结构和组件分层。 ## 输出规范 - 输出文件必须是 Mermaid 格式，以 flowchart 开头。 - 节点命名使用 {type}_{id}，避免不同子图节点名冲突。 - database 类型节点使用双圆括号形状。 - 调用关系从调用方指向被调用方。 - 如果用户没有指定方向，默认使用 LR（从左到右）。

5.3 编写 JSON 输入样例

在 examples 目录下创建order-system.json，这个文件一方面用于本地测试脚本，另一方面也作为 Agent 的参考样例，帮助它理解中间数据格式。

{ "title": "订单中台系统架构", "direction": "LR", "components": [ {"id": "web", "name": "Web 前端", "type": "client"}, {"id": "app", "name": "App 端", "type": "client"}, {"id": "gateway", "name": "API 网关", "type": "service"}, {"id": "order", "name": "订单服务", "type": "service"}, {"id": "user", "name": "用户服务", "type": "service"}, {"id": "mysql", "name": "MySQL 主库", "type": "database"}, {"id": "redis", "name": "Redis 缓存", "type": "database"}, {"id": "mq", "name": "消息队列", "type": "middleware"} ], "relationships": [ {"from": "web", "to": "gateway", "label": "HTTPS"}, {"from": "app", "to": "gateway", "label": "HTTPS"}, {"from": "gateway", "to": "order", "label": "RPC"}, {"from": "gateway", "to": "user", "label": "RPC"}, {"from": "order", "to": "mysql", "label": "JDBC"}, {"from": "user", "to": "mysql", "label": "JDBC"}, {"from": "order", "to": "redis", "label": "Redis 协议"}, {"from": "order", "to": "mq", "label": "消息投递"} ] }

5.4 编写 Python 生成脚本

在 scripts 目录下创建generate_architecture.py。脚本只使用 Python 标准库，不需要 pip 安装任何依赖。

#!/usr/bin/env python3 # -*- coding: utf-8 -*- """根据 JSON 架构描述生成 Mermaid 架构图文本。""" import argparse import json import sys from pathlib import Path # 组件类型 -> 子图名称 LAYER_MAP = { "client": "客户端层", "service": "服务层", "database": "数据层", "middleware": "中间件层", "external": "外部依赖", } # 组件类型 -> 节点形状模板 SHAPE_MAP = { "database": '{id}[("{name}")]', "default": '{id}["{name}"]', } def load_json(path: Path) -> dict: with open(path, "r", encoding="utf-8") as f: data = json.load(f) if not isinstance(data, dict): raise ValueError("JSON 根节点必须是对象") return data def validate(data: dict) -> None: components = data.get("components", []) relationships = data.get("relationships", []) ids = set() for comp in components: cid = comp.get("id") if not cid: raise ValueError("组件缺少 id 字段") if cid in ids: raise ValueError(f"组件 id 重复: {cid}") ids.add(cid) for rel in relationships: for key in ("from", "to"): ref = rel.get(key) if ref not in ids: raise ValueError(f"关系引用了不存在的组件: {key}={ref}") if not components: raise ValueError("components 不能为空") def render(data: dict) -> str: title = data.get("title", "System Architecture") direction = data.get("direction", "LR") components = data.get("components", []) relationships = data.get("relationships", []) lines = [] lines.append(f"flowchart {direction}") lines.append("") # 按类型分组 groups = {} for comp in components: ctype = comp.get("type", "service") groups.setdefault(ctype, []).append(comp) # 输出子图 for ctype, comps in groups.items(): group_name = LAYER_MAP.get(ctype, ctype) lines.append(f" subgraph {ctype}[\"{group_name}\"]") for comp in comps: cid = comp["id"] name = comp.get("name", cid) safe_id = f"{ctype}_{cid}" shape = SHAPE_MAP.get(ctype, SHAPE_MAP["default"]).format( id=safe_id, name=name ) lines.append(f" {shape}") lines.append(" end") lines.append("") # 输出关系 for rel in relationships: frm_comp = next(c for c in components if c["id"] == rel["from"]) to_comp = next(c for c in components if c["id"] == rel["to"]) frm_id = f"{frm_comp.get('type', 'service')}_{frm_comp['id']}" to_id = f"{to_comp.get('type', 'service')}_{to_comp['id']}" label = rel.get("label", "") if label: lines.append(f" {frm_id} -->|{label}| {to_id}") else: lines.append(f" {frm_id} --> {to_id}") return "\n".join(lines) + "\n" def main() -> int: parser = argparse.ArgumentParser( description="Generate Mermaid architecture diagram from JSON" ) parser.add_argument("--input", required=True, help="输入 JSON 文件路径") parser.add_argument("--output", required=True, help="输出 .mmd 文件路径") args = parser.parse_args() input_path = Path(args.input) output_path = Path(args.output) try: data = load_json(input_path) validate(data) result = render(data) except Exception as e: print(f"[ERROR] {e}", file=sys.stderr) return 1 output_path.parent.mkdir(parents=True, exist_ok=True) output_path.write_text(result, encoding="utf-8") print(f"[OK] 已生成架构图: {output_path}") print(result) return 0 if __name__ == "__main__": sys.exit(main())

这段脚本有几个设计细节值得说明。

validate 函数负责在生成前拦截错误。组件 id 重复或关系引用不存在组件时，脚本会直接报错，避免 Agent 把错误数据带入后续流程。

render 函数按 type 字段分组生成子图。这样输出天然就带分层效果。节点 id 统一加上类型前缀，例如 service_order、data_mysql，能有效避免不同子图节点重名导致的渲染冲突。

database 类型的节点走 SHAPE_MAP 中的 special 模板，渲染为[("MySQL 主库")]这种双圆括号形状，让数据库在架构图中一眼可辨。

5.5 本地验证脚本

在 architecture-diagram 目录下执行命令：

python3 scripts/generate_architecture.py \ --input examples/order-system.json \ --output output/order-system.mmd

预期输出：

[OK] 已生成架构图: output/order-system.mmd flowchart LR subgraph client["客户端层"] client_web["Web 前端"] client_app["App 端"] end subgraph service["服务层"] service_gateway["API 网关"] service_order["订单服务"] service_user["用户服务"] end subgraph data["数据层"] data_mysql[("MySQL 主库")] data_redis[("Redis 缓存")] end subgraph middleware["中间件层"] middleware_mq["消息队列"] end client_web -->|HTTPS| service_gateway client_app -->|HTTPS| service_gateway service_gateway -->|RPC| service_order service_gateway -->|RPC| service_user service_order -->|JDBC| data_mysql service_user -->|JDBC| data_mysql service_order -->|Redis 协议| data_redis service_order -->|消息投递| middleware_mq

生成的 output/order-system.mmd 可以直接用 VS Code 的 Markdown Preview Mermaid Support 预览，也可以粘贴到 draw.io 或 Typora 中渲染。

5.6 将 Skill 接入 Agent 并实测

本地脚本验证通过后，接下来把 Skill 接入 AI 工具。

不同的 AI 编码工具对 Skill 目录的约定不一样，常见的做法是：

• Claude Code：把 architecture-diagram 目录放到项目的.claude/skills/下，或者放在用户级目录~/.claude/skills/下。
• Codex：社区常见的做法是把 Skill 放到~/.codex/skills/下，具体路径以你使用的版本和官方文档为准。
• Trae 等 IDE：通常在设置面板中提供 Skills 管理入口，可以直接导入目录。

接入完成后，在聊天框中输入一句话：

请画一个订单中台架构图，包含 Web 前端、App 端、API 网关、订单服务、用户服务、MySQL、Redis 和消息队列，订单服务依赖数据库和缓存。

Agent 识别到“画架构图”后加载 Skill，会完成以下动作：

1. 从用户描述中提取组件和关系。
2. 将数据整理成 JSON 中间格式。
3. 调用generate_architecture.py生成 .mmd 文件。
4. 将 Mermaid 文本返回给你。

5.7 验证输出

如果 Agent 顺利执行，你会收到类似下面的 Mermaid 文本结果：

flowchart LR subgraph client["客户端层"] client_web["Web 前端"] client_app["App 端"] end subgraph service["服务层"] service_gateway["API 网关"] service_order["订单服务"] service_user["用户服务"] end subgraph data["数据层"] data_mysql[("MySQL 主库")] data_redis[("Redis 缓存")] end subgraph middleware["中间件层"] middleware_mq["消息队列"] end client_web -->|HTTPS| service_gateway client_app -->|HTTPS| service_gateway service_gateway -->|RPC| service_order service_gateway -->|RPC| service_user service_order -->|JDBC| data_mysql service_user -->|JDBC| data_mysql service_order -->|Redis 协议| data_redis service_order -->|消息投递| middleware_mq

把这个内容粘贴到支持 Mermaid 的编辑器中，即可看到分层清晰的系统架构图。到这里，一个“一句话画架构图”的 Skill 已经端到端跑通。

6. 常见问题与排查思路

在实际使用 Skill 的过程中，可能会遇到下面这些问题。

下面重点展开两个高频问题的排查流程。

6.1 Skill 未被识别

先确认 Skill 目录是否放在了工具规定的加载路径下。不同工具差异较大，一定要查当前版本官方文档。其次，检查 SKILL.md 顶部的 frontmatter 是否合法，name 和 description 是否都存在。最后，重启 AI 工具会话，很多工具只在会话启动时扫描 Skill 目录。

6.2 脚本执行失败

先在本地手动跑一遍脚本，排除脚本本身的问题。可以用 examples/order-system.json 作为输入，如果本地正常，说明问题出在 Agent 生成的中间 JSON 上。建议在 SKILL.md 中增加一条兜底规则：当脚本失败时，Agent 必须把临时 JSON 内容展示给用户，或者根据 JSON 规则手工生成 Mermaid 文本，而不是直接返回错误信息。

7. 最佳实践与工程建议

7.1 Skill 设计要“小而专”

一个 Skill 只解决一个问题。架构图生成 Skill 不必再顺带生成时序图或数据库设计文档。Skill 越聚焦，description 越精确，Agent 就越容易在合适场景下触发它。

7.2 数据先行，脚本兜底

设计中间 JSON 格式是整个 Skill 最值得花时间的部分。先把数据结构定好，后面无论是换渲染引擎、接可视化平台，还是做数据校验，都容易很多。脚本本身要做好校验和错误返回，不要把“坏数据”带进渲染阶段。

7.3 架构图的规范与可读性

生成架构图不只是“画出来”，还要保证可读性。建议在 SKILL.md 中明确以下约束：

• 组件数量控制在 15 个以内，超出时应自动分组，避免单图信息过载。
• 子图命名统一，客户端层、服务层、数据层、中间件层一目了然。
• 关系必须标注协议或调用方式，例如 HTTPS、RPC、JDBC、消息投递。
• 调用方向统一从调用方指向被调用方，不因为布局美观而倒置箭头。

7.4 安全与数据边界

使用 Skill 时要注意数据安全。不要让脚本读取任意路径下的文件，也不要在 Skil 中内置高权限命令。如果你打算把 Skill 目录提交到公共仓库，确认其中没有包含内部系统名称、域名、数据库连接信息等敏感数据。AI 工具运行时相当于一个半自动终端，任何脚本执行前都要理解它的副作用。

7.5 为 Agent 留出可解释性

SKILL.md 里可以要求 Agent 在返回结果时附带一句说明，例如“该架构图将系统划分为四层，调用链路为客户端到网关，再下沉到业务服务和数据存储”。这个说明对人类读者非常有帮助，也让架构图的使用者能快速判断结果是否符合预期。

8. 总结与下一步学习

围绕“一句话画出系统架构图”这件事，本文完整梳理了 Agent Skill 的概念、Skill 与普通 Prompt 和 Agent 的边界，并给出一套可运行的架构图生成 Skill。你现在应该已经理解：SKILL.md 如何控制 Agent 行为，JSON 中间格式为什么重要，Python 脚本如何把结构化数据渲染成 Mermaid 文本，以及如何把 Skill 接入主流 AI 工具。

下一步可以从三个方向继续深入：

• 扩展图表类型：在同一个 Skill 中加入时序图、流程图、部署图等生成能力。
• 反向解析：写一个解析器，从代码仓库自动提取组件依赖，生成实时架构图。
• 团队共享：把 Skill 放进 Git 仓库，配合 CI 检查架构图是否过期。

如果本文对你有帮助，可以收藏备用。实际动手配置一次 Skill，一定会比我文字描述更直观。欢迎在评论区聊聊你的 Skill 使用经验和踩坑经历。