AI Agent Skill 实战：一句话生成系统架构图的部署与原理

最近 Skill 这个词在 AI Agent 玩家里存在感一下子高了很多。不管是 Codex、Claude Code 还是国内的编程 Agent都在用“Skill”做同一件事把一段经常要重复执行的流程从“让模型现场发挥”变成“让模型照着既定模板执行”。这里面最有传播度、也最像“演示级功能”的场景就是一句话生成系统架构图。今天这篇文章就直接拆这个用法这类“系统架构图 Skill”到底是什么为什么它会火装一个需要准备什么环境怎么验证一句话生成架构图到底靠不靠谱以及怎么把它接到批量任务和自己的服务里。原文项目中可能没有包含完整的一键包所以本文会保留“CLI 工具 Skill 文件 渲染脚本”的完整部署链路每一步都给你能复制的命令和可以改成自己项目的空模板。无论你是技术负责人、售前架构师还是正在写技术文档的开发者这套 Skill 的部署逻辑和排查思路都值得保留一份。先说结论这类 Skill 的核心价值不是“让 AI 画图”而是“让 AI 按固定格式输出图再自动完成渲染”所以它的本质是约束流程而不是多一个画图插件。下面按部署顺序展开。1. 这个“系统架构图 Skill”的核心能力速览先看一张速览表方便快速判断这个东西适不适合你当前的工作流。能力项说明项目类型AI Agent Skill基于 Codex CLI / Claude Code 等终端编码代理运行核心功能输入一句话或一段系统描述输出系统架构图源码并渲染为 PNG/SVG 图片底层渲染方案Mermaid、Draw.io CLI、PlantUML按 Skill 配置选择运行方式在 Agent 终端中触发或由命令行脚本直接调用硬件要求Skill 本身不占用 GPU本地跑模型时按所用模型大小评估启动方式将 Skill 目录放入 Skills 目录重启 Agent 后自动识别是否需要一键包不需要依赖 Node.js、Python 及命令行工具API 支持官方没有统一 API可以通过二次封装脚本暴露 HTTP 接口批量任务支持给定多个系统描述批量生成 Mermaid 文件后统一渲染适合人群技术方案评审、架构文档编写、售前绘图、培训材料制作这类 Skill 的文件结构通常非常轻一个 SKILL.md 负责告诉 Agent“遇到画架构图的需求时你应该怎么做”一个 scripts 目录负责把模型输出的 Mermaid 源码变成真正的图片。真正占资源的是底层模型和渲染进程Skill 本身的运行成本可以忽略。2. 适用场景与使用边界先说适合什么场景。第一技术方案快速草拟。你正在给一个项目写设计文档需要一张“前端 - 网关 - 服务 - 数据库”的调用关系图不用等人工画图让 Agent 先生成一版 Mermaid渲染后贴进文档后续再手动调整。第二评审会议的即时图表。业务负责人口头描述一套新系统你现场用一句话让 Agent 画出候选架构讨论时有了共同视觉锚点。第三批量生成培训材料或教学示例。如果你要给多个子系统分别画架构图Skill 的批处理能力可以把重复劳动压缩到一次脚本执行。再说边界。这类 Skill 不适合精准的基础设施设计。它生成的图是“帮助理解的示意结构”不是可以直接交给云平台实施的配置图。需要精确网络策略、端口映射、权限边界的时候还是要把最终方案落在专门的设计工具里人工核对。另外涉及安全合规要求较高的系统时不要把带敏感信息的架构描述发给未授权的云端模型更不要把最终架构图直接上传到无法确认数据策略的在线服务。使用边界还包括版权和授权问题。如果 Agent 生成的图里用到了某个项目的架构命名、组件名或样式模板发布到对外材料前要保证你有权使用这些信息。涉及企业内部组件命名时也要遵守公司的信息安全规范。一句话总结Skill 可以帮你从零到一快速产出架构草图但“从草图到可发布方案”的审核和授权工作不能省略。3. 先搞清楚Skill、Agent、插件不是一回事很多人把 Skill 等同于“给 Agent 装插件”这个说法不够准确。Agent 是一个能调用工具、理解上下文、分步完成任务的模型运行环境。插件更多地指向“能扩展 Agent 能力的工具模块”比如搜索、执行代码、读文件它们解决的是“Agent 能做什么”。Skill 不一样它解决的是“Agent 应该按什么流程做”。Skill 可以引用脚本也可以只是几段 Markdown 指令它让 Agent 在特定场景下不要自由发挥而是按照你设定好的步骤输出。换一种说法没有 Skill 时你让 Agent 画一张系统架构图它可能会直接输出一段 Mermaid 文本到聊天窗口也可能生成一个文件也可能写一个 React 组件行为不稳定。有了 Skill 后Agent 会先检查输入识别系统组件和调用关系然后按照 SKILL.md 的要求生成固定格式的源码最后调用指定脚本渲染成图片并返回文件路径。这个“行为一致性”就是 Skill 最大的价值。具体到“一句话画系统架构图”这个需求实现链路通常是这样的用户在 Agent 终端里输入类似“帮我画一个电商系统的架构图包括用户端、网关、商品服务、订单服务、支付服务和数据库”。Agent 根据 Skill 的触发条件识别出这是一个架构图任务。Agent 按照 SKILL.md 中的步骤解析系统描述拆分组件、边界、调用关系。Agent 使用 Mermaid 语法生成架构图源码保存到指定目录。Skill 配套脚本读取源码调用 mermaid-cli 或 drawio CLI 渲染成 SVG/PNG。Agent 报告输出文件位置用户可以打开图片确认效果。整条链路里SKILL.md 解决“格式和步骤”脚本解决“从源码到图片”模型解决“从自然语言到结构化源码”。理解了这个分层后面部署和排查都会更顺。4. 环境准备与前置条件部署这类 Skill 不需要 GPU也不需要专门的显存评估它属于“命令行程式”的工作流工具。一个最小可用环境大概需要以下条件依赖用途说明Node.js 18运行 mermaid-cli部分 Agent 客户端也需要 Node.js用node -v检查版本npm安装 mermaid-cli 和 Agent 客户端一般随 Node.js 安装Python 3.10编写批量脚本和 API 封装可选但建议保留Codex CLI 或 Claude Code运行 Skill 的 Agent 环境二选一也可以都用mermaid-js/mermaid-cli将 Mermaid 源码渲染成图片需要下载 headless Chromiumdrawio CLI可选用于生成 .drawio 文件如果只需要 PNG/SVG 可以不装在常见 Linux 或 macOS 环境下先检查基础环境是否存在。node -v npm -v python3 --version如果 Node.js 版本低于 18建议先升级到 LTS 版本。Windows 用户建议在 Windows Terminal 或 WSL 中使用减少路径和权限问题。Agent 客户端的安装方式以官方文档为准常用方式如下# 安装 Codex CLI 的常见命令具体版本以官方文档为准 npm install -g openai/codex # 安装 Claude Code 的常见命令具体版本以官方文档为准 npm install -g anthropic-ai/claude-codemermaid-cli 推荐作为项目依赖安装避免全局版本污染。# 在要跑 Skill 的项目目录里初始化并安装 npm init -y npm install --save-dev mermaid-js/mermaid-cli安装完成后第一次执行渲染时 mermaid-cli 会下载 headless Chromium这个过程需要保持网络畅通且可能需要等待几分钟。如果下载失败可以检查 npm 代理配置或者确认系统是否已经安装 Chrome/Chromium再通过 puppeteer 配置指向本地浏览器。这个细节后面排查表里会再提。5. 安装部署Skill 目录结构与装载方式以 Codex CLI 和 Claude Code 这类支持 Skills 的 Agent 为例目录结构通常遵循“系统级或项目级 skills 目录下放一个 Skill 文件夹文件夹里放 SKILL.md”的约定。不同版本可能略有差异安装前先查阅当前 Agent 官方文档确认路径。一个典型的最小目录结构如下skills/ system-arch/ SKILL.md scripts/ render.sh其中 SKILL.md 是核心。它告诉 Agent 这个 Skill 在什么情况下启用、启用后按什么步骤执行。下面是一个可供参考的模板不同 Agent 对 frontmatter 字段的要求不同你需要按实际项目调整--- name: system-arch description: 当用户需要画系统架构图、系统流程图、模块关系图时使用。用户可能说“画架构图”“生成系统图”“描述一下模块关系”。请调用 system-arch Skill 完成。 --- # System Architecture Skill 这个 Skill 的用途是根据一段系统描述生成可渲染的 Mermaid 架构图源码并渲染为图片。 ## 执行步骤 1. 分析用户的系统描述识别以下元素 - 系统边界用户端、管理端、后台任务、外部系统。 - 核心组件网关、服务、中间件、数据库、消息队列。 - 调用关系箭头方向、同步调用、异步消息、数据流向。 2. 使用 Mermaid 的 graph TD 或 flowchart 语法编写架构图源码保存到 ./work/mermaid/ 目录文件命名使用简短英文例如 ecommerce-arch.mmd。 3. 调用 scripts/render.sh 脚本渲染该文件生成 SVG 和 PNG。 4. 向用户报告输出文件完整路径并用两句话概括图中展示的系统结构。 ## 注意事项 - 不要自行决定修改用户没有提到的架构边界。 - 如果用户没有指定技术栈保持组件命名通用。 - 如果描述中存在冲突或缺失先用列表形式向用户确认。Scripts 目录下的渲染脚本可以很简单。以 bash 为例#!/usr/bin/env bash # 渲染 Mermaid 文件为 SVG 和 PNG # 用法: bash scripts/render.sh input.mmd output-name set -euo pipefail INPUT${1:-architecture.mmd} OUTPUT${2:-architecture} OUTPUT_DIR$(dirname $INPUT) npx mmdc -i $INPUT -o $OUTPUT_DIR/$OUTPUT.svg -b white npx mmdc -i $INPUT -o $OUTPUT_DIR/$OUTPUT.png -b white echo 渲染完成: $OUTPUT_DIR/$OUTPUT.svg / $OUTPUT_DIR/$OUTPUT.png给脚本加执行权限启动 Agent 时它会自动读取 SKILL.md。chmod x skills/system-arch/scripts/render.sh装载方式分为系统级和项目级。如果你希望所有项目都能用把 skills 目录放到用户级目录例如~/.codex/skills/如果只想在某个仓库里用放进该仓库的.codex/skills/或.claude/skills/。装载完成后重启当前 Agent 会话让新 Skill 生效。验证是否成功一般可以在 Agent 里输入“列出已加载的 Skill”不同工具命令不同以官方文档为准。6. 功能测试一句话生成系统架构图部署完成后第一步最好用一个非常明确的例子来验证链路。这里以“电商系统”为例给出可复现的测试流程。先在项目目录下建好必要的目录mkdir -p work/mermaid outputs然后启动 Agent输入下面这句话帮我画一个电商系统的架构图。用户端包括 Web 和 App统一经过 API 网关商品服务、订单服务、支付服务是三个核心后端服务共用 MySQL 和 Redis支付服务还会调用外部支付 SDK。用这个 Skill 生成架构图。正常情况下Agent 会先识别出这不是普通的问答而是系统架构图任务然后按照 SKILL.md 的步骤生成 Mermaid 源码。输出文件可能类似于graph TD A[Web] -- C[API 网关] B[App] -- C[API 网关] C -- D[商品服务] C -- E[订单服务] C -- F[支付服务] E -- G[(MySQL)] F -- G[(MySQL)] D -- H[(Redis)] E -- H[(Redis)] F -- I[外部支付 SDK]随后 Agent 调用渲染脚本生成 SVG 和 PNG 文件。判断成功的标准有三个一是在work/mermaid/目录下能找到.mmd文件二是outputs/目录下出现对应的.svg和.png文件三是图片能正常打开组件之间的关系和文字描述一致。如果生成内容没有按预期进入文件而是直接输出在聊天窗口里说明 SKILL.md 的步骤约束没有生效或者 description 里的触发条件不够明确。这时先检查 Agent 是否真的加载了这个 Skill再检查 SKILL.md 中是否明确写了“保存到文件”的步骤。第一版验证通过后可以测试带约束条件的生成。例如还是这个电商系统这次用中文标签把支付服务单独放在一个虚线框里表示它与外部系统交互的边界。这类测试可以用来确认 Agent 是否理解 SKILL.md 中的“边界”和“通用组件语义”。如果输出缺少虚线框说明 Skill 模板里的注意项不够明确你可以补充一条“外部系统使用 subgraph dashed 样式”让下一次结果更稳定。7. 批量任务与 HTTP API 化这一类 Skill 最有价值的工程化用法是按目录批量处理。举例来说你准备了一批系统描述文件每个文件对应一个子系统希望一次性生成多张架构图。第一步让 Agent 批量读取描述并生成 Mermaid 源码。读取 ./descriptions/ 目录下的 5 个 .md 文件每个文件描述一个子系统。调用 system-arch Skill为每个描述生成对应的 Mermaid 源码保存到 ./work/mermaid/ 目录文件名与描述文件名保持一致。如果 Agent 支持同时处理多个任务它会逐个生成.mmd文件。如果一次生成效果不稳定可以改成逐个处理再手动确认。第二步用 shell 循环统一渲染。# 批量渲染 work/mermaid 目录下的所有 .mmd 文件 for file in ./work/mermaid/*.mmd; do name$(basename $file .mmd) echo rendering $name npx mmdc -i $file -o ./outputs/$name.svg -b white done这样描述文件到架构图图片的整条链路就自动化了。批量场景下建议在每个描述文件开头增加一行“系统名称”方便 Agent 生成文件名也便于后期人工核对。接口 API 化是另一个常见需求。Skill 本身并不暴露 HTTP 接口但你可以写一个轻量服务把渲染链路包装起来。下面是一个基于 FastAPI 的示例实际使用时需要把“LLM 生成 Mermaid”这一部分替换成你真正在用的模型接口或 Agent 命令。from fastapi import FastAPI, HTTPException from pydantic import BaseModel import subprocess import uuid import os app FastAPI() OUTPUT_DIR ./outputs os.makedirs(OUTPUT_DIR, exist_okTrue) class ArchRequest(BaseModel): description: str app.post(/arch) async def generate_arch(req: ArchRequest): # Step 1: 这里应接入真实的 LLM 或 Agent 调用把 description 转换为 Mermaid 源码 # 下面只是演示结构实际要替换为模型输出 mermaid graph TD\n A[用户] -- B[系统] # Step 2: 保存源码 task_id uuid.uuid4().hex[:8] mmd_path os.path.join(OUTPUT_DIR, f{task_id}.mmd) with open(mmd_path, w, encodingutf-8) as f: f.write(mermaid) # Step 3: 渲染成 SVG svg_path os.path.join(OUTPUT_DIR, f{task_id}.svg) result subprocess.run( [npx, mmdc, -i, mmd_path, -o, svg_path, -b, white], capture_outputTrue, textTrue, ) if result.returncode ! 0: raise HTTPException(status_code500, detailresult.stderr) return { task_id: task_id, svg_path: svg_path, preview: fhttp://127.0.0.1:8000/outputs/{task_id}.svg }启动服务uvicorn app:app --host 127.0.0.1 --port 8000调用示例curl -X POST http://127.0.0.1:8000/arch \ -H Content-Type: application/json \ -d {description: 用户端经过网关访问订单服务订单服务依赖 MySQL}这个接口本质上只完成了“格式整理 渲染”真正的智能生成部分需要你自己接 Agent 或模型。如果你希望在接口里直接触发 Agent建议把 Agent 的执行命令封装成子进程并设置合理的超时时间避免一次请求占死整个服务。8. 资源占用与性能观察对于“系统架构图 Skill”资源占用需要分三段来看。第一段是 Agent 本身。如果使用云端模型本机资源占用很低瓶颈通常在网络请求耗时。如果使用本地部署的模型显存和 CPU 占用取决于模型大小和 Skill 本身无关。Skill 的 SKILL.md 和脚本只是文本文件加上几十行命令可以忽略不计。第二段是 Mermaid 渲染。mermaid-cli 依赖 headless Chromium 做渲染这会导致一段固定的内存开销。图片简单时通常占用不高但如果你渲染超大流程图比如几百个节点的复杂架构浏览器渲染进程会明显变慢。实际占用需要以本机监控为准。可以用npx mmdc -w 4指定并发数控制同时渲染的任务量。第三段是批量场景。如果你在 shell 循环里连续执行大量 mmdc 命令建议串行或小并发执行避免短时间内存冲高。每次渲染完成后检查输出文件大小SVG 正常情况是几十 KB 到几百 KBPNG 会更大一些。如果渲染进程频繁崩溃优先检查 headless Chromium 是否能正常启动而不是盲目调大并发。性能观察建议三步走。第一步在批量渲染前用一条free -h记录内存基线。第二步执行渲染时另开终端用nvidia-smi或top观察占用。虽然 Skill 本身不占用 GPU但如果你本地跑了 Agent 模型GPU 使用率会有真实波动。第三步记录每个.mmd文件的节点数和渲染耗时方便后续判断是 Skill 流程慢还是渲染工具慢。9. 常见问题与排查方法问题现象可能原因排查方式解决方案Agent 不执行 Skill直接输出文本SKILL.md 未被加载或触发描述不够明确重启会话检查 skills 目录位置是否正确确认目录路径在 description 中加入更多触发词SKILL.md 已放置但仍未生效目录结构多了层级或 frontmatter 格式错误查看 Agent 日志对照官方目录结构检查把 SKILL.md 放在 Skill 文件夹根目录检查 YAML 格式生成的 Mermaid 源码无法渲染Agent 输出的语法高估了渲染器能力或中文字体缺失用编辑器打开 .mmd 文件检查括号和箭头在 SKILL.md 中限制只使用 graph/flowchart 基础语法中文显示为乱码headless Chromium 缺少中文字体打开生成的 PNG 检查安装系统中文字体如 fonts-noto-cjk图片渲染后布局混乱节点过多Mermaid 自动布局不够理想检查节点数量在 SKILL.md 中要求分组或用 subgraph 组织边界批量渲染内存飙高并发执行过多 mmdc 进程用 top/free 观察进程数量改为串行遍历或限制并发数drawio 文件无法导入导出的 XML 格式与 drawio 版本不兼容用 drawio 桌面版手动打开测试确认 drawio CLI 版本统一版本后再导出API 请求超时Agent 或模型推理耗时过长查看服务日志设置 HTTP 超时或改为异步任务队列渲染脚本提示找不到 npx项目依赖未安装检查 node_modules 是否存在执行npm install --save-dev mermaid-js/mermaid-cli排查任何问题第一步都是看文件是否真实生成。如果一个流程“看起来没反应”先用ls -la检查源码目录和输出目录确认 Agent 有没有执行到写文件这一步。这一步能快速区分问题出在“模型没有理解”还是“渲染脚本失败”。10. 最佳实践与合规提醒第一给 Skill 设计明确边界。SKILL.md 里除了告诉 Agent 要做什么还要告诉它“不做什么”。例如默认不修改用户未提及的架构边界不擅自添加云厂商组件不把内部服务命名随意外发到未授权平台。边界越清晰输出越稳定。第二第一次使用小参数验证。不要一开始就塞进复杂需求。先画一个“用户 - 网关 - 两个服务 - 数据库”的简单图确认整个过程跑通再逐步提高难度。第三版本控制 Skill 文件。SKILL.md 和脚本本质上是你自己定义的流程代码应该纳入版本管理。这样换电脑、换团队时可以直接复用。第四批量任务要加日志。批量生成时务必让脚本输出每个文件的状态“成功”或“失败”。不要只打印一条最终汇总否则某个子图失败时很难定位。第五接口服务要限制访问范围。如果按照前面示例把 Skill 封成了 HTTP 服务至少要绑定127.0.0.1不要直接暴露到公网。生产环境还要加鉴权、限流和任务队列。第六涉及敏感信息的合规处理。系统架构图通常承载了真实的组件名、数据库类型、网络拓扑这本身就是高风险数据。不要把包含内部命名的架构描述发送给未经授权的云端模型。可以选择企业内部部署的模型或者对地名、服务名、中间件型号做脱敏后再生成。第七生成结果人工复核后再发布。AI 生成的架构图很可能存在逻辑缺口例如漏掉某个调用链或把异步消息画成同步调用。建议把渲染出来的图当作“初稿”在评审会前由真实系统负责人核对一遍确认箭头方向、依赖关系和数据流是否符合实际。11. 总结与下一步这个“一句话画出系统架构图”的 Skill最值得尝试的点不是省去画图时间而是它带来了一种可重复、可约束、可审计的 Agent 工作流。你先用 SKILL.md 定义规则再用脚本固定产出格式最终让 Agent 的随机生成变成稳定输出。这个思路一旦跑通可以继续复制到时序图、流程图、部署拓扑图甚至知识库整理任务上。建议第一次动手时先验证一个最小闭环创建一个 Skill 目录写一份最简单的 SKILL.md放一个纯渲染脚本然后用一个三五个节点的例子跑通“文字描述 → Mermaid 源码 → PNG/SVG”全过程。最容易踩的坑是目录结构不对导致 Skill 不加载以及中文字体缺失导致渲染乱码这两类问题优先排查。后续扩展方向有三个一是把批量描述改成 JSON 或表格输入让非技术同事也能填表生成架构图二是把渲染脚本接到 CI 里每次技术方案变更自动生成一份最新架构图三是把 Skill 内部包一层异步任务服务用消息队列消化大量架构图生成请求。学会写第一个 Skill 之后你就会发现它本质上是一种“可交付的流程资产”可以不断积累和复用。