之前团队画系统架构图通常要走一套固定流程先开会讨论模块边界再打开 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 可以拥有多个 SkillSkill 则服务于 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 均可。Python3.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目录中各个文件的职责如下文件或目录作用SKILL.mdSkill 的核心说明文件描述触发条件、处理步骤、输出规范scripts/存放辅助脚本用于完成结构化数据处理、文件生成等任务examples/存放输入输出样例方便 Agent 和人类理解 Skill 的用法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 作为图表 DSLMermaid 是一种用文本描述图表的 DSL领域特定语言。相比直接让 AI 生成图片文件文本 DSL 更适合 Agent 场景原因有三点文本可靠AI 生成文本远比生成图片文件稳定。跨工具兼容同一个 .mmd 文件可以在 Typora、draw.io、VS Code、GitLab 中渲染。可版本管理架构图进入 Git 仓库后diff 也能看清楚改动。5. 完整实战编写一个架构图生成 Skill5.1 创建目录结构在任意工作目录下创建架构图 Skill 的目录结构。这里以项目根目录为例mkdir -p architecture-diagram/scripts mkdir -p architecture-diagram/examples cd architecture-diagram5.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、typetype 取值范围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, encodingutf-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(fflowchart {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( idsafe_id, namename ) 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( descriptionGenerate Mermaid architecture diagram from JSON ) parser.add_argument(--input, requiredTrue, help输入 JSON 文件路径) parser.add_argument(--output, requiredTrue, 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}, filesys.stderr) return 1 output_path.parent.mkdir(parentsTrue, exist_okTrue) output_path.write_text(result, encodingutf-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会完成以下动作从用户描述中提取组件和关系。将数据整理成 JSON 中间格式。调用generate_architecture.py生成 .mmd 文件。将 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 的过程中可能会遇到下面这些问题。问题现象常见原因解决思路Agent 没有加载 Skill直接聊天式回答description 触发条件写得太模糊明确在 description 中加入触发词例如“画架构图、system architecture”调用脚本时报 Python 找不到模块当前 Python 环境异常或脚本依赖未被安装本文脚本只依赖标准库检查 python3 是否可用生成的 Mermaid 渲染报错节点 id 中包含特殊字符或引用关系错误在脚本 validate 阶段增加 id 合法性校验例如只允许大小写字母、数字、下划线中文标签乱码控制台编码或文件编码不一致写文件时显式指定 encodingutf-8脚本中已经处理Agent 绕过 Skill 直接生成 Mermaid模型认为不需要调用脚本也能完成在 SKILL.md 中明确要求“必须优先调用脚本”并把脚本路径写清楚下面重点展开两个高频问题的排查流程。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 使用经验和踩坑经历。