draw-io

draw-io skill 概覽

draw-io skill 是一套聚焦的工作流程，適合把 .drawio 圖表以 XML 形式建立、編輯與審閱，接著匯出成可用於文件或投影片的 .drawio.png。對開發者、技術寫作者、解決方案架構師，以及需要在不手動點擊 draw.io UI 的情況下，反覆而穩定地更新圖表的 AI 使用者來說，draw-io skill 特別實用。

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 圖示會從本機參考資料查找，而不是憑印象猜圖示名稱

哪些人應該安裝 draw-io

如果你已經在 Git 裡管理 draw.io 檔案、會從原始檔產生文件或投影片，或需要以程式化方式更新架構圖，那就很適合安裝 draw-io。如果你只是想在 GUI 裡做一次性的視覺腦力激盪，這套流程大概會比你真正需要的更重。

如何使用 draw-io skill

安裝 draw-io skill

使用你的 skill manager，從 repository 加入：

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

如果你的環境使用不同的安裝方式，重點是 softaworks/agent-toolkit 裡的 skill 路徑：skills/draw-io。

先確認本機前置需求

在正式依賴 draw-io install 之前，請先確認環境中有：

• 可用於匯出的 drawio CLI
• 執行轉換腳本需要的 bash
• 如果你希望自動把產生的 PNG 加入 staged，則需要 git
• 若你的 repo 採用該流程，也可能需要 mise 與 pre-commit

內建的轉換腳本會呼叫：

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

這代表會使用匯出模式、PNG 格式、2 倍縮放、透明背景，以及明確指定輸出路徑。

先讀這些檔案

若想最快上手，建議依序查看：

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 應視為產生出的成品檔。如果你的 repo 同時追蹤來源檔與匯出檔，代理就應該修改 XML 原始檔，然後再重新產生 PNG。

draw-io 需要哪些輸入資訊

draw-io 的使用品質，很大程度取決於你提供的輸入是否完整。較好的輸入通常會包含：

• 目標檔案路徑
• 是要新建還是編輯
• 圖表類型：架構圖、流程圖、類似 sequence 的流程等
• 預期閱讀方向：由左到右，或由上到下
• 必要的服務、節點、標籤與連線
• 任何投影片或文件上的限制
• 是否必須使用 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 特別好用，例如：

• 移動某個 cluster 以避免線條重疊
• 讓服務方塊水平對齊
• 把泛稱標籤改成正式 AWS 服務名稱
• 為了投影片相容性調整字型
• 在 XML 修改後重新產生 PNG

在這類情境下，直接編輯 XML 往往比手動操作 UI 更快，也更容易重現。

如果要上投影片，請遵守字型設定

如果圖表要用在 Quarto 投影片，或放在容易出現字型渲染差異的環境中，這個 skill 建議設定：

• 在 mxGraphModel 上設定 defaultFontFamily
• 在各個文字元素上設定 fontFamily

repository 也明確提到 Noto Sans JP 是支援日文的建議字型。就算你不需要日文，核心原則仍然很重要：只要你希望跨機器、跨匯出步驟都能維持一致輸出，就應該明確指定字型。

選擇符合你 repo 流程的轉換路徑

這個 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

請依照你的 repo 工作流程選用。如果專案本來就使用 pre-commit，就走那條路；如果只是要在本機臨時匯出一次，直接跑腳本通常最快。

不要猜 AWS 圖示，請直接查 draw-io 的 AWS 參考

如果你是在 AWS 比重很高的圖表裡使用 draw-io for Design Implementation，那麼 AWS 圖示參考資料會是這個 skill 最有價值的部分之一。它整理了：

• 官方服務命名，例如 Amazon ECS、AWS Lambda
• 目前採用的 mxgraph.aws4.* 圖示樣式慣例
• resource 與 product 圖示的使用模式

附帶的輔助腳本也能直接查詢參考資料：

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

這比靠記憶硬湊 resIcon 名稱安全得多。

有意識地套用版面配置指引

repository 裡的版面指引不是可有可無的補充，而是能實際提升輸出品質的預設原則：

• 清楚區分 cloud 邊界與 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 以外的精緻設計 mockup
• 純粹在 GUI 裡進行視覺化編輯
• 產出與 .drawio 無關格式的圖表

這個 skill 專注在 draw.io XML 與匯出操作，不是通用型平面設計工具。

draw-io 能處理 AWS 架構圖嗎？

可以，而且這正是它最明確的強項之一。AWS 圖示參考與查找腳本，能幫你使用官方命名與 mxgraph.aws4.* 圖示；當你在意一致性與辨識度時，這非常有價值。

draw-io 會自動修好很差的版面嗎？

不會神奇地自動修好。這個 skill 提供的是一套有方法的座標與版面調整流程。只要你能清楚提供位置意圖，例如群組方式、流程方向、間距與重疊優先順序，它就能明顯改善結果。

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

給 draw-io 更強的結構化輸入

想提升 draw-io 的使用效果，最快的方法不是多加形容詞，而是提供結構。與其說「幫我弄乾淨一點」，不如直接說：

• 把 database 移到 app tier 下方
• 所有 ingestion source 都放在左側欄位
• 若可行，讓箭頭不要交叉
• public subnet 與 private subnet 的資源分開成組
• 標籤要夠短，避免把方塊撐大

這類指令可以直接對應到 XML 與版面決策。

能從既有圖開始，就不要每次都從零生成

這個 skill 在編輯既有 .drawio 檔案時，通常比從頭發明整張圖更穩定。既有檔案能提供它：

• 現有元素 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 最常見的失敗模式

常見的 draw-io 問題，多半不是概念問題，而是實作細節出了錯：

• 編輯了 PNG，而不是 .drawio
• 忘記設定字型，導致文字渲染不一致
• 使用猜測出來的 AWS 圖示識別字
• 節點塞得太密，讓標籤互相碰撞
• 連線交叉太多，降低可讀性
• 改版面時沒有保住整體流程方向

你只要在提示詞中直接引用 repository 提供的腳本與指引，就能預防其中大多數問題。

用小步驟、可審查的方式反覆修改

面對複雜圖表時，不要一次要求全部改完。更好的做法通常是：

1. 先調整結構與群組
2. 再檢查間距與連線
3. 修正標籤與字型
4. 匯出 PNG
5. 最後做一次可讀性檢查

這樣產生的 diff 會更乾淨，也更容易判斷問題究竟是出在群組、圖示選擇，還是文字尺寸。

在提示中直接點名 repository 輔助檔案

如果你的代理支援感知檔案內容的提示方式，請直接提到具體參考檔：

• references/layout-guidelines.md：用於間距與流程方向
• references/aws-icons.md：用於 AWS 命名與圖示
• scripts/find_aws_icon.py：用於查圖示
• scripts/convert-drawio-to-png.sh：用於匯出

這個小動作通常就能明顯提升第一次產出的品質，因為代理會優先採用 repository 的既有慣例，而不是套用泛泛而談的圖表建議。