Excalidraw スキルは何をしますか？

ステップ 0: インターフェースを選ぶ

3つのインターフェースが同じライブキャンバスを操作します。該当するものを最初に選んでください：

MCP ツール — ツール一覧に excalidraw/* ツール（例：batch_create_elements）が存在する場合、それらを優先します。結果は直接コンテキストに反映され、スクリーンショットはディスクに触れずに画像として返されます。
CLI（MCPツールがない場合のデフォルト）：
```
npx -y mcp-excalidraw-server <command>
```
セットアップは不要です。キャンバスに触れるコマンドは 自動的にキャンバスサーバーを起動 します（http://127.0.0.1:3000）。初回の npx 実行時にパッケージがダウンロードされます。CLIがグローバルにインストールされている場合（npm i -g mcp-excalidraw-server）、短いエイリアス excalidraw-canvas <command> も使用できます。
REST API（最終手段。例：アプリケーションコードから）：HTTPエンドポイント（http://127.0.0.1:3000）— ペイロードは references/cheatsheet.md を参照してください。サーバーは事前に起動している必要があります。

キャンバスのURLは EXPRESS_SERVER_URL から取得されます（デフォルトは http://127.0.0.1:3000）。ユーザーにそのURLをブラウザで開くよう促してください。スクリーンショット、画像エクスポート、Mermaid変換、ビューポート制御には開いているタブが必要です（タブがない場合、CLIは終了コード4を返します）。

CLI クイックリファレンス

結果はJSONがstdoutに出力されます。ただし、describe（プレーンテキスト）と、--out 省略時の生コンテンツ出力（export のシーンJSON、screenshot --format svg の生SVG）は例外です。診断メッセージはstderrに出力されます。終了コード：0 正常、1 エラー、2 使用方法エラー、3 キャンバスに到達不可、4 ブラウザタブが必要。

タスク	コマンド
サーバーの起動/停止/状態確認	`start`, `stop`, `status`
要素の作成（一括）	`add elements.json` または `echo '[...]'
1コールでの複数操作パッチ	`apply patch.json` — `{"create":[...],"update":[{"id":"a","set":{...}}],"delete":[...]}`
単一読み取り / 複数クエリ	`get <id>`, `query [--type t] [--bbox x0,y0,x1,y1] [--filter k=v] [--filter-json '{...}']`
更新 / 削除	`update <id> --set '{...}'`, `delete <id> [...]`
シーンを理解する	`describe`（プレーンテキスト要約：ID、位置、ラベル、接続）
シーンを確認する	`screenshot [--out f.png]`（`--out` なしPNG → JSON内の一時ファイルパス; `--out` なしSVG → 生SVG）
レイアウト操作	`arrange align
シーンファイル	`export [--out scene.excalidraw]`, `import [scene.excalidraw
Mermaid → キャンバス	`mermaid [diagram.mmd
スナップショット	`snapshot save
共有リンク	`share`（暗号化アップロード → excalidraw.com URL）
キャンバスをクリア	`clear --yes`
このスキルのインストール/アップグレード	`install-skill --dir <skills-root>`（エージェントがプロジェクト/グローバルルートを選択）

要素フォーマット（CLI および MCP）

CLIとMCPツールは同じエージェント向けフォーマットを受け入れ、自動的に正規化します：

ラベル: 任意の図形に "text": "My Label" を指定 — Excalidrawのバインドラベル形式に自動変換されます。
矢印のバインド: "startElementId": "a" / "endElementId": "b" — 矢印は自動的に要素の端にルーティングされます。
fontFamily: 文字列名（"helvetica", "cascadia", "excalifont", ...）または文字列番号 "1"–"8" を指定します。
points: [[x,y], ...] のタプルと [{"x":..,"y":..}] のオブジェクトの両方を受け付けます。
パッチ更新: apply 内の更新エントリでは、直接フィールド（{"id":"a","x":120}）または set オブジェクト（{"id":"a","set":{"x":120}}）のどちらかを使用できます。一つの更新エントリ内で両方の形式を混在させないでください。

生のRESTはより厳密です：ラベルは "label": {"text": "..."}、バインドは "start": {"id": "..."} / "end": {"id": "..."} で指定する必要があります。APIに直接POSTする場合のみ注意してください。

座標系

キャンバスは2D座標グリッドを使用します：(0, 0) が原点、x は右方向に増加、y は下方向に増加 します。JSONを記述する前にレイアウトを計画してください。

一般的な間隔のガイドライン：

階層間の垂直間隔：80～120px（矢印がラベルを圧迫しない十分な間隔）
兄弟間の水平間隔：最小40～60px、ラベル付き矢印には120px以上確保
図形の幅：max(160, labelCharCount * 12) でラベルを一行に収める
図形の高さ：一行ラベルで60px、二行ラベルで80px
背景/ゾーンのパディング：内包する要素の周囲に全方向50px

プロフェッショナルな外観のためのスタイリング：

図形には "fillStyle": "solid" を指定すると、すっきりとしたフラットな塗りになります（デフォルトはスケッチ風のハッチュアパターンです）
パステル調の backgroundColor 塗りと、それより暗い strokeColor を組み合わせます（パレットはチートシートにあります）
ゾーンの境界や非同期の矢印には "strokeStyle": "dashed" を使用すると、「境界 / 背景」として読み取れます

レイアウトのアンチパターン（複雑な図では重要）

これらは、読みにくい図を生み出す最も一般的な間違いです。すべて避けてください。

1. 大きな背景ゾーン矩形に `label.text`（または `text`）を使用しない

背景矩形にラベルを付けると、Excalidrawはその図形の中央にバインドテキスト要素を作成します。これはサービスボックスを配置する場所と重なり、ゾーン内のすべての要素の上にテキストが表示され、位置を変更できません。

間違い：

{"id": "vpc-zone", "type": "rectangle", "x": 50, "y": 50, "width": 800, "height": 400, "text": "VPC (10.0.0.0/16)"}

正しい — ゾーンの上端に固定された独立したテキスト要素を使用：

{"id": "vpc-zone", "type": "rectangle", "x": 50, "y": 50, "width": 800, "height": 400, "backgroundColor": "#e3f2fd"},
{"id": "vpc-label", "type": "text", "x": 70, "y": 60, "width": 300, "height": 30, "text": "VPC (10.0.0.0/16)", "fontSize": 18}

独立したテキスト要素はゾーンの上部コーナーに配置され、内部の要素と干渉しません。

2. 複雑な図ではゾーンをまたぐ矢印を避ける

あるレイアウトゾーンの要素から遠くのゾーンの要素への矢印は、間にあるすべてのものを横切る長い対角線を描きます。マルチゾーンのインフラ図では、これは読みにくいスパゲッティの絡まりを生み出します。

設計ルール： 矢印は同じゾーンまたは階層内に留めてください。ゾーン間の関係を示すには、注釈テキストを使用するか、ゾーンの端が隣接するように分離し（間に要素を置かない）、矢印を端に沿ってルーティングします。

どうしてもゾーンをまたぐ必要がある場合は、外周に沿って進むエルボー矢印を使用してください。決して別のゾーンの中央を通らないでください。

3. 矢印ラベルは控えめに使用する

矢印ラベルは矢印の中点に配置されます。短い矢印では両端の図形と重なります。混雑した図では、近くの要素と衝突します。

関係名が本当に不可欠な場合（例：プロトコル、ポート番号、データ方向）にのみ矢印ラベルを追加してください。
すべての矢印にラベルを追加している場合は、再考してください。通常は視覚的なノイズを増やし、明確さを損ないます。
矢印ラベルは12文字以内に抑えてください。密度の高い図では、完全に省略することを推奨します。

品質：なぜ重要か（そして確認方法）

Excalidrawの図は視覚的なコミュニケーションです。テキストが切れたり、要素が重なったり、矢印が無関係な図形を横切ったりすると、図は混乱を招き、プロフェッショナルでなくなります。図を描く目的そのものが失われます。そのため、要素のバッチごとに、追加する前に確認してください。

品質チェックリスト

各 add / apply / batch_create_elements の後、スクリーンショットを撮って以下を確認してください：

テキストの切り詰め — すべてのラベルテキストが完全に表示されていますか？切り詰められたテキストは図形が小さすぎることを示します。width や height を増やしてください。
重なり — 同じスペースを共有する図形はありませんか？背景ゾーンは子要素をパディング付きで完全に内包する必要があります。
矢印の交差 — 矢印が無関係な要素を横切っていませんか？その場合は、カーブ矢印またはエルボー矢印を使用して迂回させてください（下記の矢印ルーティングを参照）。
矢印ラベルの重なり — 矢印ラベルは中点に配置されます。図形と重なる場合は、ラベルを短くするか、矢印のパスを調整してください。
間隔 — 要素間は少なくとも40pxの隙間を確保してください。窮屈なレイアウトは読みにくいです。
可読性 — 本文はフォントサイズ16以上、タイトルは20以上にしてください。
ゾーンラベルの配置 — 背景ゾーン矩形に text/label.text を使用した場合、ゾーンラベルがゾーンの中央に配置され、内部のすべてと重なります。修正：バインドテキスト要素を削除し、代わりにゾーンの上部に独立したテキスト要素を追加してください（上記のレイアウトアンチパターンを参照）。

問題が見つかった場合：停止し、修正し、再度スクリーンショットを撮り、その後続行してください。 問題を無視するのではなく、「[問題]が見つかりました。修正しています」と発言してください。すべてのチェックが合格した場合のみ先に進んでください。

ワークフロー：新しい図の作成

Mermaid vs 直接作成 — どちらを使うべきか？

mermaid / create_from_mermaid を使用する場合：ユーザーがすでにMermaid図を持っている場合、または構造が標準のMermaid構文でフローチャート/シーケンス図/ER図にきれいにマッピングできる場合。高速で変換を自動処理しますが、正確なレイアウトを制御できません。

直接要素を作成する場合：正確なレイアウト制御が必要な場合、図の種類がMermaidにうまくマッピングされない場合（例：カスタムアーキテクチャ、注釈付きクラウド図）、または要素を特定の座標グリッドに配置したい場合。

手順（CLIで表示；MCPツールは1:1対応 — チートシートを参照）

座標グリッドを計画 — JSONを記述する前に階層とx位置をマッピングします。（MCPモード：色/サイズについては read_diagram_guide を呼び出してください。同じガイダンスが references/cheatsheet.md にもあります。）
オプションで最初からやり直す場合：npx -y mcp-excalidraw-server clear --yes

1回の呼び出しで図形と矢印を作成します。カスタムの id フィールド（例："id": "auth-svc"）を使用すると、後での更新が簡単になります：

npx -y mcp-excalidraw-server add - <<'EOF'
[
  {"id": "lb", "type": "rectangle", "x": 300, "y": 50, "width": 180, "height": 60, "text": "Load Balancer"},
  {"id": "svc-a", "type": "rectangle", "x": 100, "y": 200, "width": 160, "height": 60, "text": "Web Server 1"},
  {"id": "svc-b", "type": "rectangle", "x": 450, "y": 200, "width": 160, "height": 60, "text": "Web Server 2"},
  {"id": "db", "type": "rectangle", "x": 275, "y": 350, "width": 210, "height": 60, "text": "PostgreSQL"},
  {"type": "arrow", "x": 0, "y": 0, "startElementId": "lb", "endElementId": "svc-a"},
  {"type": "arrow", "x": 0, "y": 0, "startElementId": "lb", "endElementId": "svc-b"},
  {"type": "arrow", "x": 0, "y": 0, "startElementId": "svc-a", "endElementId": "db"},
  {"type": "arrow", "x": 0, "y": 0, "startElementId": "svc-b", "endElementId": "db"}
]
EOF

（- の位置指定はオプションです。ファイル引数がない場合、add はstdinを読み取ります。）

図形の幅は max(160, labelLength * 12) を使用して設定します。
screenshot → ファイルを表示 → 品質チェックリストを実行 → 次のバッチの前に問題を修正します。

矢印ルーティング — 重なりを避ける

直線の矢印は複雑な図で要素を横切ることがあります。必要に応じてカーブ矢印またはエルボー矢印を使用してください。

カーブ矢印（障害物をスムーズな弧で迂回）：

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [50, -40], [200, 0]],
  "roundness": {"type": 2}
}

中間ウェイポイント [50, -40] が矢印を上方向に持ち上げます。roundness: {type: 2} でスムーズな曲線になります。

エルボー矢印（直角 / L字型ルーティング）：

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [0, -50], [200, -50], [200, 0]],
  "elbowed": true
}

どちらを使用するか：

ファンアウト（1つのソース → 複数のターゲット）：ウェイポイントで広がるカーブ矢印、重なりを避ける
クロスレーン（サイドパネルへの接続）：上に、横に、下に進むエルボー矢印
長い水平接続：わずかに垂直オフセットを持つカーブ矢印

ルール： 矢印が無関係な図形を通過する場合は、ウェイポイントを追加して迂回させてください。

ワークフロー：反復的な洗練

describe と screenshot を組み合わせることが、このスキルを強力にするポイントです。

describe（MCPでは describe_scene）→ 構造化テキスト：要素ID、タイプ、位置、ラベル、接続。プログラムによる更新の前に、キャンバス上に何があるかを把握するために使用します（IDを見つけ、バウンディングボックスを理解する）。
screenshot（MCPでは get_canvas_screenshot）→ 実際にレンダリングされたキャンバスのPNG。視覚的な品質検証に使用します。ユーザーが見るもの（切り詰め、重なり、矢印ルーティングを含む）を正確に表示します。CLIは保存されたファイルパスをJSONとして出力します。そのファイルを読み取って表示してください。

フィードバックループ：

要素を追加
  → スクリーンショット → 表示 → 「auth-svcのテキストが切れている」
  → auth-svcを更新 --set '{"width": 220}' → スクリーンショット → 「auth-svcとrate-limiterが重なっている」
  → rate-limiterを更新 --set '{"x": 520}' → スクリーンショット → 「すべてのチェック合格」
  → 続行

ワークフロー：既存図の洗練

describe で現在の状態を把握 — 要素IDと位置をメモします。
要素を id またはラベルテキストで特定します（x/y座標ではなく、それらは変わります）。
update <id> --set '{...}' でサイズ変更/色変更/移動、delete <id> で削除、またはすべてを1つの apply パッチにまとめます。バインドされた矢印は、端点を移動またはサイズ変更すると自動的に再ルーティングされます — 削除して再作成する必要はありません。
screenshot で変更が正しく見えることを確認します。
更新が失敗した場合：get <id> でIDが存在するか確認し、ロックされている場合は arrange unlock --ids <id> でロックを解除します。

ワークフロー：Mermaid変換

echo 'graph TD
  A[Client] --> B[API]
  B --> C[(DB)]' | npx -y mcp-excalidraw-server mermaid

開いているブラウザタブが必要です（変換はフロントエンドで実行されます。終了コード4はキャンバスURLを開くように促します）。その後、screenshot でレイアウトを確認します。自動レイアウトが不十分な場合（ノードが密集、エッジが交差）、describe で問題の要素を見つけ、update で再配置します。

ワークフロー：ファイルI/O

シーンのエクスポート：export --out diagram.excalidraw（--out なし → JSONをstdoutに出力）
シーンのインポート：import diagram.excalidraw（追加）または import diagram.excalidraw --replace
画像：screenshot --out diagram.png / screenshot --format svg --out diagram.svg（ブラウザタブが必要）
共有リンク：share — シーンを暗号化して共有可能なURLを返します

Excalidraw スキル