最近在技术社区里“一句话画出系统架构图”成了挺热门的演示场景输入“画一下外卖订单从创建到支付完成的核心链路”几秒后就能得到一张带服务边界、调用关系和存储设计的架构图。这个功能看起来像“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 生成成功率高应用架构、调用链、流程图、时序图Mermaid Live Editor、VS Code 插件、GitLab MarkdownPlantUML表达力强支持丰富 UML 元素类图、部署图、状态图PlantUML 在线服务、IDE 插件Draw.io XML与 Draw.io 编辑器强绑定团队白板协作、大型复杂架构图draw.io、diagrams.net实际项目中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.mdSKILL.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 是大脑里可按需调取的教材。教材在平时不翻开当遇到对应题目时才自动打开。概念粒度是否执行动作是否可复用典型存在形式Prompt小否通常不可复用对话上下文Skill中否但可引导调用 Tool是目录 SKILL.mdTool小是是函数、API、命令行Agent大是是系统、配置、脚本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参考示例文件然后经过以下步骤识别用户提到的六个核心元素。判断这些元素应该归入接入层、应用层还是基础设施层。补充示例中没有明确说出的“用户”边界用于表达外部入口。构建依赖关系例如“订单服务访问订单数据库”“支付服务访问支付数据库”。按模板输出 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 高频问题对照表问题现象常见原因检查方式处理建议Agent 完全没有使用 Skilldescription 未命中、目录路径不对查看工具是否有 Skill 加载日志或调试模式缩小 description 范围确认目录路径符合工具要求输出的是文字叙述没有 Mermaid 代码块Skill 中输出格式约束不强制查看 SKILL.md 是否有“必须输出代码块”指令在输出格式中明确写“先输出代码块再解释”Mermaid 渲染报错节点名含特殊字符、引号、括号将代码贴到 Mermaid Live Editor 看错误行简化节点命名避免使用括号和中文标点图太复杂节点之间连线混乱缺少节点数量和箭头数量的限制检查 SKILL.md 是否包含数量约束增加分层抽象规则要求先输出 12 个以内的主节点每次生成结构都不一样SKILL.md 里没有固定模板对比多次输出的开头部分增加“输出模板约束”章节要求先填模板再扩展跨设备运行时 Skill 失效Skill 只放在本地目录未随项目仓库提交检查团队成员的 Skill 目录是否一致将 Skill 放入项目目录并纳入 Git 管理6.2 推荐排查顺序遇到“一句话画图失败”时不要一开始就怀疑模型能力。建议按以下顺序排查先看输入是否清晰。系统边界、关键组件、依赖关系是否都能从一句话中提取。输入太模糊时任何模板都救不了。再看 Skill 是否被加载。很多工具会在日志或调试面板中显示加载了哪些 Skill。如果没有加载优先改 description。再看 SKILL.md 本身。有没有输出模板、有没有校验规则、示例文件在不在正确路径。注意SKILL.md 中引用的examples/xxx.md如果路径写错模型即使在加载 Skill 后也拿不到示例。再看 Mermaid 语法。把输出代码复制到 Mermaid Live Editor如果渲染失败通常有错误行提示。最后才考虑是否要调模型或调参数。多数情况下问题出在前四步。注意验证时不要只看“模型生成了几张图”还要验证“生成了几次完全相同的结构”。稳定性是架构图 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 能画图”这个现象而是把团队对架构的表达标准固化下来。当每个层级都遵循同一套模板和校验规则时架构图才不只是“一张图”而是可沟通、可审查、可演化的设计文档。对新手来说最好的练习是从本文的电商系统案例开始先跑通一次渲染再把失败案例逐条转成规则最后把规则分享给团队。这条路比到处收藏“画图提示词”要扎实得多。