draw-io

draw-io skill 概览

draw-io skill 是一套聚焦于 .drawio 图表创建、编辑与审查的工作流：直接以 XML 形式修改源文件，再导出为用于文档或幻灯片的 .drawio.png。它尤其适合开发者、技术写作者、解决方案架构师，以及需要稳定、可重复地更新图表、又不想每次都手动点 draw.io UI 的 AI 用户。

draw-io 最擅长什么

当你需要以下能力时，这个 draw-io skill 的优势最明显：

• 安全地编辑已有 .drawio 文件
• 通过调整 XML 坐标做精确布局修改
• 统一图表规范，例如字体设置
• 生成高分辨率透明 PNG
• 使用正确的 mxgraph.aws4.* 标识符调用 AWS 架构图标

它真正解决的工作问题是什么

大多数用户并不是真的需要抽象意义上的“图表生成”。他们需要的是：让代理可靠地更新架构图、保持样式一致，并产出可以直接进入文档流水线的导出文件。draw-io 的价值就在于，它把这件事落成了一套明确工作流，而不是一个模糊提示词。

draw-io 和通用提示词有什么不同

普通提示词也许能给出一个图表思路，但这个 skill 增加了实际可执行的操作规则：

• 编辑的是 .drawio XML，而不是生成后的 .drawio.png
• 用明确的 CLI 参数导出 PNG
• 显式设置 font-family，保证幻灯片兼容性
• 按分组、流向和可读性规则处理布局
• 从本地参考中查 AWS 图标，而不是猜图标名

哪些人应该安装它

如果你本来就在 Git 里维护 draw.io 文件、需要从源码生成文档或幻灯片，或者要以程序化方式更新架构图，那么值得安装 draw-io。但如果你只是想在 GUI 里做一次性的可视化头脑风暴，那这套流程大概率比你实际需要的更重。

如何使用 draw-io skill

安装 draw-io skill

用你的 skill manager 从仓库添加它：

npx skills add softaworks/agent-toolkit --skill draw-io

如果你的环境用的是别的安装方式，关键是定位到 softaworks/agent-toolkit 中的 skill 路径 skills/draw-io。

先确认本地前置条件

在真正依赖 draw-io install 之前，先确认你的环境具备：

• 可用于导出的 drawio CLI
• 用于转换脚本的 bash
• 如果希望自动将生成的 PNG 加入暂存区，则需要 git
• 如果你的仓库走这套流程，可选安装 mise 和 pre-commit

仓库自带的转换脚本会调用：

drawio -x -f png -s 2 -t -o output.drawio.png input.drawio

这表示：导出模式、PNG 格式、2 倍缩放、透明背景，以及显式指定输出路径。

先看这些文件，draw-io 上手最快

为了最快上手，建议按下面顺序查看：

1. skills/draw-io/SKILL.md
2. skills/draw-io/README.md
3. skills/draw-io/references/layout-guidelines.md
4. skills/draw-io/references/aws-icons.md
5. skills/draw-io/scripts/convert-drawio-to-png.sh
6. skills/draw-io/scripts/find_aws_icon.py

这个阅读顺序很重要，因为这个 skill 的价值更多体现在“怎么执行”，而不是“概念介绍”：规则、布局约定和辅助脚本才是核心内容。

先记住 draw-io 的核心操作规则

最重要的使用约束其实很简单：

• 编辑 .drawio 文件
• 不要直接编辑 .drawio.png 文件

PNG 应被视为生成产物。如果你的仓库同时跟踪源文件和导出文件，代理应该先修改 XML 源文件，再重新生成 PNG。

draw-io 需要什么样的输入

draw-io usage 的效果，很大程度上取决于你提供的输入是否具体。高质量输入通常会包含：

• 目标文件路径
• 是新建还是编辑
• 图表类型：架构图、流程图、类时序流等
• 预期阅读方向：从左到右，或从上到下
• 必需的服务、节点、标签和连接关系
• 幻灯片或文档方面的限制
• 是否必须使用 AWS 官方图标
• 当前是否需要导出 PNG

如果缺少这些信息，代理就只能自己猜结构、间距和命名。

把模糊目标变成高质量 draw-io 提示词

弱提示词：

“Update our AWS diagram.”

更好的提示词：

“Edit assets/system.drawio. Add Amazon S3 on the left as the ingestion source, route data to AWS Lambda, then to Amazon RDS. Keep a left-to-right flow. Preserve existing group structure. Use official AWS icons, avoid crossing arrows, and regenerate assets/system.drawio.png.”

为什么这种写法更有效：

• 指明了文件
• 说明了要新增哪些组件
• 给出了流程方向
• 明确要求图标准确
• 包含布局目标
• 指定了导出产物

把 draw-io 用在精确修改上，而不只是生成

当你已经有现成图表，只需要做定点修改时，这个 skill 特别有用，比如：

• 挪动某个集群，避免线条重叠
• 将多个服务框水平对齐
• 把泛化标签替换为 AWS 官方服务名称
• 为了适配幻灯片而修改字体
• 在 XML 修改后重新生成 PNG

这类场景下，直接编辑 XML 往往比手动操作 UI 更快，也更容易复现。

如果图要上幻灯片，务必遵循字体设置

如果图表要用于 Quarto slides，或所在环境经常出现字体渲染问题，这个 skill 建议设置：

• 在 mxGraphModel 上设置 defaultFontFamily
• 在各个文本元素上设置 fontFamily

仓库里明确提到，Noto Sans JP 是适合日文支持的推荐字体。即使你不需要日文，这里的通用经验同样重要：只要你希望跨机器、跨导出步骤保持一致输出，就要显式指定字体。

选择和仓库流程匹配的导出方式

这个 skill 支持多种 PNG 导出方式：

• 通过 pre-commit 处理全部文件：mise exec -- pre-commit run --all-files
• 通过 pre-commit 处理单个文件：mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio
• 直接运行脚本：bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio

怎么选取决于你的仓库工作流。如果项目本来就在用 pre-commit，就沿用那条路径；如果只是本地一次性导出，直接跑脚本最快。

不要猜 AWS 图标，直接用 draw-io 自带参考

如果你在做 AWS 比较重的图，尤其是 draw-io for Design Implementation 这类场景，图标参考是这个 skill 最有价值的部分之一。它明确记录了：

• 官方服务命名，例如 Amazon ECS 和 AWS Lambda
• 当前图标风格约定，使用 mxgraph.aws4.*
• resource 和 product 两类图标模式

附带的辅助脚本还可以直接搜索参考：

python ~/.claude/skills/draw-io/scripts/find_aws_icon.py lambda

这比凭记忆去编 resIcon 名称安全得多。

有意识地应用布局指南

仓库里的布局指南不是可有可无的补充，它给的是一组能直接提升产出质量的默认实践：

• 清楚划分 cloud boundary 和 subnet 分组
• 主流程尽量保持从左到右
• 用不同线型区分不同流类型
• 相关元素彼此靠近
• 减少箭头交叉
• 留出足够留白，保证可读性

如果你希望代理第一版就更接近可用状态，最好直接指出这些原则里哪一条对你的图最重要。

draw-io skill 常见问题

draw-io 适合新手吗？

适合，但前提是你已经在处理 draw.io 文件，并且希望有人帮你编辑它们。这个 skill 通过明确规则和脚本减少猜测成本。但如果你是完全新手，只是想在没有文件工作流的前提下探索“图表怎么画”，那它未必是最理想的起点。

draw-io 什么时候比普通 AI 提示词更好用？

当你需要可复现的修改、正确的文件处理、完整的导出步骤，或者 AWS 图标准确性时，draw-io 会明显优于普通提示词。普通提示词也许能把图表思路描述得不错，但通常不会强制执行 .drawio 源文件编辑、导出命令、字体设置和辅助脚本使用这些关键环节。

draw-io 一定需要 draw.io GUI 吗？

不一定。这个 skill 的设计核心就是基于源文件编辑和 CLI 导出 PNG，所以它非常适合以代码为中心的工作流、可审查 diff，以及文档流水线。

什么情况下不该用 draw-io？

如果你需要的是以下场景，就可以跳过这份 draw-io guide：

• 自由白板式协作
• draw.io 之外的精致设计稿
• 完全基于 GUI 的纯视觉编辑
• 与 .drawio 无关的其他图表格式生成

这个 skill 的专长是 draw.io XML 与导出流程，不是通用平面设计工具。

draw-io 能帮助处理 AWS 架构图吗？

可以，而且这是它最明确的优势之一。AWS 图标参考和查找脚本能帮助你使用官方命名和 mxgraph.aws4.* 图标；当一致性和识别度很重要时，这一点尤其有价值。

draw-io 会自动修复糟糕布局吗？

不会神奇地自动修好。这个 skill 提供的是一套可操作的方法：通过有意识地调整坐标和布局来改进结果。当你能明确表达分组、流向、间距和避免重叠等意图时，它的效果会更好。

如何改进 draw-io skill 的使用效果

给 draw-io 更强的结构化输入

提升 draw-io usage 效果最快的方法，不是多用形容词，而是提供结构化指令。与其说“让它更清爽”，不如直接说：

• 把数据库移动到应用层下面
• 所有 ingestion source 保持在左侧一列
• 如果可能，箭头不要交叉
• public subnet 和 private subnet 资源分开分组
• 标签尽量短，避免撑大框体

这类指令可以直接映射到 XML 和布局决策上。

能从现有图开始，就不要每次都从零生成

当它是在编辑已有 .drawio 文件，而不是从头猜完整张图时，这个 skill 的表现通常最好。现有文件能提供：

• 当前元素 ID
• 已有布局模式
• 现成样式规范
• 已建立的分组结构
• 已知导出目标

对团队来说，这通常比每次都要求生成一张全新图更稳定、更可靠。

明确命名规则和图标准确性要求

一个常见失败点是服务命名过于含糊，比如写“ECS”或“Lambda”，但没有决定标签是否要使用完整官方服务名。如果 AWS 图很重要，建议同时明确两件事：

• 显示标签：Amazon ECS、AWS Lambda、Amazon RDS
• 图标要求：使用官方 mxgraph.aws4.* 服务图标

这样可以避免命名风格混杂，也能减少图标映射错误。

把“编辑 + 导出”当成一个完整工作流来提要求

如果你想拿到的是可直接使用的结果，就应该在同一条指令里同时要求修改源文件和执行导出。例如：

“Update docs/arch.drawio, then regenerate docs/arch.drawio.png with the skill’s standard PNG export settings.”

这样可以减少一种很常见的问题：XML 已经改了，但预览产物还是旧的。

重点防范这些常见失败模式

常见的 draw-io 问题往往不是概念层面的，而是执行层面的：

• 改了 PNG，却没改 .drawio
• 忘记设置字体，导致文本渲染不一致
• AWS 图标标识符靠猜
• 节点塞得太密，标签互相撞
• 连线交叉过多，影响阅读
• 调整布局时破坏了整体流向

要避免这些问题，最有效的做法之一就是在提示词里直接点名引用仓库提供的脚本和指南。

用小步、可审查的方式迭代

面对复杂图表时，不要一次性提出所有修改。更好的做法是分阶段：

1. 先调整结构和分组
2. 再检查间距和连线
3. 修正标签和字体
4. 导出 PNG
5. 最后做一轮可读性检查

这样 diff 会更干净，也更容易判断某个布局问题到底是分组、图标选择，还是文字尺寸导致的。

在提示里直接点名仓库辅助文件

如果你的代理支持基于文件上下文的提示，建议直接提到这些具体参考：

• references/layout-guidelines.md：用于间距和流向
• references/aws-icons.md：用于 AWS 命名和图标
• scripts/find_aws_icon.py：用于图标查找
• scripts/convert-drawio-to-png.sh：用于导出

这个小动作通常能明显改善第一版结果，因为代理会优先遵循仓库已有约定，而不是套用泛泛的图表建议。