draw-io

draw-io skill の概要

draw-io skill は、.drawio 図を XML として作成・編集・レビューし、その後ドキュメントやスライド用に .drawio.png へ書き出すことに特化したワークフローです。draw.io の UI を毎回手作業で操作せず、再現性のある形で図を更新したい開発者、テクニカルライター、ソリューションアーキテクト、AI 活用ユーザーに特に向いています。

draw-io が最も力を発揮する場面

この draw-io skill が特に有効なのは、次のようなケースです。

• 既存の .drawio ファイルを安全に編集したい
• XML の座標を直接調整して、細かくレイアウトを直したい
• フォント設定など、図の標準ルールを揃えたい
• 高解像度・透過背景の PNG を生成したい
• AWS アーキテクチャアイコンを正しい mxgraph.aws4.* 識別子で使いたい

実際に解決したい仕事は何か

多くのユーザーが必要としているのは、抽象的な意味での「図の自動生成」ではありません。求めているのは、アーキテクチャ図を安定して更新し、スタイルを揃え、ドキュメント作成フローにそのまま載せられる書き出し済みアセットを作ることです。draw-io は、その作業を曖昧なプロンプト任せにせず、具体的なワークフローとして扱える点に価値があります。

一般的なプロンプトと比べて draw-io が違う点

普通のプロンプトでも図のアイデア自体は出せます。ですが、この skill には実務向けの運用ルールがあります。

• 生成済みの .drawio.png ではなく、.drawio XML を編集する
• 既知の CLI 設定で PNG を書き出す
• スライド互換性のために font-family を明示的に設定する
• グルーピング、フロー方向、可読性に関するレイアウト指針に従う
• AWS アイコン名を勘で決めず、ローカルのリファレンスから参照する

インストールをおすすめできる人

draw-io は、Git で 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 を自動で stage したい場合の git
• リポジトリでその運用をしている場合は、mise と pre-commit も任意で必要

付属の変換スクリプトでは、次のコマンドを呼び出します。

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

これは、export モード、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 は概念説明よりも実運用寄りで、ルール、レイアウト規約、補助スクリプトに価値の大半が詰まっているためです。

最重要の運用ルールを先に押さえる

使ううえで最も重要な制約はシンプルです。

• .drawio ファイルを編集する
• .drawio.png ファイルは直接編集しない

PNG は生成物として扱います。リポジトリでソースと書き出し結果の両方を管理している場合、エージェントは XML ソースを修正し、そのあとで PNG を再生成するべきです。

draw-io に必要な入力情報

draw-io usage の品質は、渡す入力次第で大きく変わります。良い入力には、通常次のような情報が含まれます。

• 対象ファイルのパス
• 新規作成か既存編集か
• 図の種類: architecture、flowchart、sequence-like flow など
• 想定する読み方向: left-to-right か top-to-bottom
• 必須のサービス、ノード、ラベル、接続関係
• スライドやドキュメント側の制約
• 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 を再生成する

こうした場面では、UI で手作業するより、XML を直接編集したほうが速くて再現性も高いことが少なくありません。

スライド用途ならフォント設定は守る

図を Quarto スライドや、フォント描画差分が出やすい環境で使うなら、この skill は次の設定を推奨しています。

• mxGraphModel 上の defaultFontFamily
• 各テキスト要素上の fontFamily

リポジトリでは、日本語対応の推奨フォントとして Noto Sans JP が明示されています。日本語を使わない場合でも、教訓は同じです。マシン差異や export 手順をまたいで見た目を安定させたいなら、フォントは明示指定したほうが安全です。

リポジトリの運用に合う変換経路を使う

この 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 アイコンのリファレンスを使う

AWS 色の強い図で draw-io for Design Implementation を行うなら、アイコンリファレンスはこの skill の中でも特に価値が高い部分です。そこには次の情報が整理されています。

• Amazon ECS や AWS Lambda といった公式サービス名
• mxgraph.aws4.* を使う現在のアイコンスタイル規約
• リソースアイコンとプロダクトアイコンのパターン

付属のヘルパースクリプトで検索もできます。

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

resIcon 名を記憶頼みででっち上げるより、はるかに安全です。

レイアウト指針は意図を持って使う

リポジトリ内のレイアウトガイドは、飾りではありません。出力品質を上げるための実践的な初期値がまとまっています。

• cloud boundary や subnet を明確にグループ化する
• 可能ならメインの流れを left-to-right に保つ
• フローの種類に応じて線種を使い分ける
• 関連要素は近くに配置する
• 矢印の交差を減らす
• 可読性のために十分な余白を取る

最初の一案から使える図にしたいなら、どの原則を優先したいかをエージェントに伝えると効果的です。

draw-io skill の FAQ

draw-io は初心者にも向いていますか？

はい、すでに draw.io ファイルを持っていて、その編集支援が欲しいなら有用です。具体的なルールやスクリプトがあるため、手探りを減らせます。一方で、ファイルベースの運用がなく、単に図解の概念を試したいだけの完全な初心者には、やや向かない場面もあります。

どんなときに通常の AI プロンプトより draw-io が優れていますか？

draw-io が強いのは、再現可能な編集、適切なファイル操作、export 手順、AWS アイコンの正確性が必要なときです。通常のプロンプトでも図の説明はできますが、.drawio ソース編集、export コマンド、フォント設定、補助スクリプト利用まで一貫して守らせるのは難しいことが多いです。

draw-io を使うのに draw.io の GUI は必須ですか？

必須ではありません。この skill は、ソースファイル編集と CLI ベースの PNG export を中心に設計されています。そのため、コード中心のワークフロー、差分レビュー、ドキュメント生成パイプラインと相性が良いです。

draw-io を使わないほうがよいのはどんなときですか？

次の用途が中心なら、この draw-io guide は見送ってよいでしょう。

• 自由度の高いホワイトボード用途
• draw.io 外で仕上げる洗練されたデザインモック
• GUI だけで完結する視覚編集
• .drawio とは無関係な形式の図生成

この skill は、汎用グラフィックデザインではなく、draw.io XML と export 作業に特化しています。

draw-io は AWS アーキテクチャ図にも使えますか？

はい。そこは最も分かりやすい強みのひとつです。AWS アイコンのリファレンスと検索スクリプトにより、公式名称と mxgraph.aws4.* アイコンを使いやすくなります。表記や見た目の一貫性が重要な場面で特に役立ちます。

draw-io はレイアウトの悪さを自動で直してくれますか？

魔法のように自動修正してくれるわけではありません。この skill は、座標や配置を意図的に調整するための方法を提供します。グルーピング、流れの方向、余白、重なり回避の優先度などを明確に伝えるほど、結果は良くなります。

draw-io skill を改善するには

draw-io に渡す構造情報を強くする

draw-io usage を最も手早く改善する方法は、形容詞ではなく構造を渡すことです。たとえば「もっと見やすく」ではなく、次のように伝えます。

• データベースを app tier の下に移動する
• すべての ingestion source を左列に揃える
• 可能なら矢印が交差しないようにする
• public subnet と private subnet のリソースを分けてグループ化する
• ラベルはボックスが広がりすぎない長さに収める

こうした指示は、そのまま XML とレイアウトの判断に落とし込めます。

可能なら既存の図から始める

この skill は、ゼロからすべてを発明させるより、既存の .drawio ファイルを編集させるほうがうまく動きます。既存ファイルがあると、次の情報を利用できます。

• 現在の要素 ID
• 既存のレイアウトパターン
• スタイルの慣例
• グループ構造
• 既知の export 先

チーム運用では、毎回まっさらな図を作らせるより、こちらのほうが安定した結果になりやすいです。

命名とアイコンの正確性は明示する

よくある失敗は、「ECS」「Lambda」のような曖昧なサービス名を使い、ラベルを正式名称にするのか決めないことです。AWS 図が重要なら、次の両方をはっきり指定してください。

• 表示ラベル: Amazon ECS, AWS Lambda, Amazon RDS
• アイコン要件: 公式の mxgraph.aws4.* サービスアイコンを使う

これで、命名スタイルの混在やアイコン対応ミスを防げます。

編集と export を一つのワークフローとして依頼する

実際に使える成果物が欲しいなら、ソース編集と export を一度に依頼してください。たとえば次のようにします。

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

こうしておくと、XML だけ更新されてプレビュー用アセットが古いまま、というよくある抜け漏れを防げます。

主な失敗パターンを把握しておく

よくある draw-io の問題は、概念的なものより実務的なものが中心です。

• .drawio ではなく PNG を編集してしまう
• フォント設定を省いて、文字描画が環境ごとにぶれる
• AWS アイコン識別子を推測で書く
• ノードを詰め込みすぎてラベルが衝突する
• コネクタが交差して可読性を落とす
• 全体の流れを保たずにレイアウト変更してしまう

こうした問題の多くは、プロンプト内で付属スクリプトやガイドを明示することで予防できます。

変更は小さく、レビューしやすく刻む

複雑な図では、一度に全部を依頼しないほうが得策です。おすすめの進め方は次のとおりです。

1. 構造とグルーピングを調整する
2. 余白とコネクタをレビューする
3. ラベルとフォントを直す
4. PNG を export する
5. 最後に可読性の観点で一巡確認する

この進め方なら差分がきれいになり、問題がグルーピング由来なのか、アイコン選択なのか、文字サイズなのかを切り分けやすくなります。

リポジトリ内の補助ファイルを名前で指定する

エージェントがファイル参照型のプロンプトに対応しているなら、参照先を正確に書いておくと効果的です。

• references/layout-guidelines.md は余白やフローの指針
• references/aws-icons.md は AWS の命名とアイコンの基準
• scripts/find_aws_icon.py はアイコン検索
• scripts/convert-drawio-to-png.sh は export 用

このひと手間で、一般論の図作成アドバイスではなく、そのリポジトリの規約に沿った初回出力になりやすくなります。