mermaid-skill

Mermaid 図

.mmd テキストファイルを生成し、mmdc（ローカル）または Kroki API（インストール不要）を使って PNG／SVG／PDF にエクスポートします。

主な利点： テキストベースの構文で、レイアウトが完全に自動化されます。x/y 座標は不要です。

使用する場合／使用しない場合

このスキルを使用する場合： 自動レイアウトを使ったコードによる図の作成（フローチャート、シーケンス図、クラス図、状態遷移図、ER 図、ガントチャート、マインドマップ、アーキテクチャ図など）。Git で管理し、Markdown に埋め込めるテキストソースが必要な場合に適しています。

次の場合は使用せず、別のツールを使用してください：

• ピクセル単位で正確な配置、カスタムレイアウト、ブランドアイコン、または細かなスタイリング → drawio。
• 手描き風、またはラフな見た目 → excalidraw または tldraw。
• 自由形式のホワイトボード、またはフリーハンドのストローク → tldraw。
• 厳密で一般的な UML 表記 → plantuml。

前提条件

オプション A：ローカル（mmdc） — ヘッドレス Chrome も必要です（mmdc は Puppeteer 経由でレンダリングします）

npm install -g @mermaid-js/mermaid-cli
npx puppeteer browsers install chrome-headless-shell   # required — mmdc has no bundled browser
mmdc --version

Chrome がインストールされていなくても mmdc --version は成功しますが、その場合、すべてのエクスポートで Could not find Chrome が発生します。上記のブラウザーをインストールするか、PUPPETEER_EXECUTABLE_PATH にシステムの Chrome を設定してください。できない場合は、ブラウザーが不要な Kroki（オプション B）を使用してください。

CI／Docker： コンテナー内では、mmdc は Running as root without --no-sandbox というエラーでクラッシュします。同梱の puppeteer 設定を渡してください（scripts/puppeteer-config.json を参照）：

mmdc -p scripts/puppeteer-config.json -i diagram.mmd -o diagram.png

オプション B：Kroki API（インストール不要）

curl --version  # Just need curl

ワークフロー

1. 依存関係を確認 — Kroki で検証します（必要なのは curl のみ）。ローカルでエクスポートする場合（PNG の画質／PDF）が必要なときに限り、mmdc --version とヘッドレス Chrome を確認します
2. 図の種類を選択 — 以下の表から選びます
3. 生成 — .mmd ファイルをディスクに書き込みます
4. 検証 — まず Kroki で検証します（「検証」を参照。エクスポート前に必須です）
5. エクスポート — mmdc または Kroki API を使って PNG／SVG／PDF を生成します
6. セルフチェック（視覚確認） — エクスポートした PNG を確認し、自動レイアウトでは防げない可読性やレイアウト上の問題（ラベルの切れ、詰め込みすぎ、向きの誤り）を修正してから、再検証して再エクスポートします。最大 2 回まで行います。視覚確認ができない場合はスキップしてください。以下の**セルフチェック（視覚確認）**を参照してください。
7. レビューループ — 画像をユーザーに見せ、リクエストごとに必要最小限の .mmd 編集を適用し、承認されるまで再エクスポートします（安全策として最大 5 回）。以下のレビューループを参照してください。
8. 報告 — 出力ファイルのパスをユーザーに伝えます

検証（必須）

事前に検証せずに図をエクスポートしてはいけません。

検証にはまず Krokiを使用してください。ブラウザーが不要で、Could not find Chrome の問題を完全に回避できます。オフラインの場合に限り、検証に mmdc を使用してください。

# Validate with Kroki (preferred — no browser needed)
curl -s -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o /tmp/test.svg && echo "Valid" || echo "Invalid"

# Validate with mmdc (offline fallback — requires headless Chrome)
mmdc -i diagram.mmd -o /tmp/test.svg 2>&1

# If error, fix the .mmd file and validate again
# Only proceed to export after validation passes

よくある検証エラー：

• 特殊文字を含むラベルの引用符が不足している
• 矢印の構文が間違っている（シーケンス図では ->>、フローチャートでは --> を使用します）
• シーケンス図で参加者が宣言されていない

mmdc で Could not find Chrome（または puppeteer）エラーが発生するのは、図のエラーではなくセットアップの問題です。.mmd は完全に正しい可能性があります。正しい構文を「修正」するのではなく、Kroki で検証してください。

セルフチェック（ビジョン）

無料の事前チェック： ビジョン機能を使う前に、PNG の寸法を確認します（macOS では sips -g pixelWidth -g pixelHeight diagram.png、それ以外では file diagram.png）。縦横比が極端（長辺が短辺の 8 倍を超える）な場合は「向きが不適切」という欠陥です。ビジョン機能を使わずに修正してください。

上記の検証で確認できるのは構文が正しいことだけです。レンダリングされた図が読みやすいかどうかは分かりません。エクスポート後、エージェントのビジョン機能を使って PNG を読み取り、自動レイアウトでは防げない問題を見つけてください。Mermaid はすべての要素を自動配置するため、ここで扱う問題は重なりではなく、コンテンツと読みやすさに関するものです。

チェック項目	確認すること	修正方法
ラベルの切り詰め	ノード／エッジのテキストがクリップされている、または切れている	ラベルを短くするか、<br/> で改行します
詰め込みすぎで読みにくい密度	ノードが多すぎて密集している、線が絡み合っている	方向を切り替える（TD↔LR）、subgraph に分割する、またはノードを減らします
向き／アスペクト比の不適切さ	図が横長または縦長すぎて読めない	flowchart TD↔LR を切り替える（または class/state で direction を設定します）
エッジのスパゲッティ化	多数のエッジが交差していて追いにくい	接続されたノードが隣接するようにノード宣言の順序を変更する、subgraph でグループ化する
図の種類の不適切さ	内容に図の種類が合っていない（例：タイムラインにフローチャートを使っている）	図の種類を切り替える（gantt、sequenceDiagram、stateDiagram-v2、…）
コントラスト不足	テキストがノードの塗りつぶし色に埋もれている	classDef／テーマを調整して、テキストと塗りつぶしのコントラストを高めます

• セルフチェックは最大 2 回 までです。2 回修正しても問題が残る場合は、そのままユーザーに提示してください。
• 修正のたびに、構文を再検証して再エクスポートしてください。
• ビジョン機能が利用できない場合は、セルフチェックを省略し、PNG をそのまま提示してください。

レビューループ

セルフチェック後、エクスポートした画像を表示してフィードバックを集めます。リクエストごとに最小限の .mmd 編集を行い、再検証して再エクスポートしてください。

ユーザーのリクエスト	編集内容
ラベルの変更	.mmd 内のノード／エッジのテキストを編集します
ノードまたはエッジの追加／削除	対応する行を追加または削除します
色の変更	classDef と class <node> <className> を追加／調整します
レイアウト方向の変更	TD↔LR を切り替える（フローチャートの場合）、または direction を設定する（class／state の場合）
再構成／グループ化	関連するノードを subgraph で囲むか、再生成します

• 毎回、同じ diagram.mmd／diagram.png を上書きします。v1、v2、…のような名前は作成しないでください。
• 安全策： 5 回のレビューを終えたら、ユーザーがブラウザーで現在の図を微調整できるよう、mermaid.live への引き継ぎリンクを生成します（次のセクションを参照）。

Mermaid.live への引き継ぎ

レビューループの終了時（承認後または安全策の適用時）に、現在の .mmd を mermaid.live エディターで開き、インタラクティブに微調整できるワンクリックリンクを生成します。

python3 scripts/mermaid_live_link.py diagram.mmd
# -> https://mermaid.live/edit#pako:...

純粋な zlib + base64（raw-deflate + URL-safe base64。mermaid.live と同じエンコード方式）で、オフラインで動作します。スクリプトは出力前に、往復デコードで自動検証します。

バッチモード（リポジトリの調査）

ユーザーがリポジトリ全体の図解を依頼した場合（「このコードベースを調査して」「アーキテクチャを図にして」など）：

1. スキャン — コードベース内のスキーマ（SQL／ORM モデル）、API ルート、ステートマシン／ライフサイクルの列挙型を探します
2. 提案 — 見つかった項目ごとに図を 1 つ提案します。スキーマには ER 図、主要な API フローにはシーケンス図、ライフサイクルには状態図、サービス全体の構成にはフローチャートを用意します。生成前に図の構成をユーザーに確認します
3. 生成とエクスポート — 図ごとに標準ワークフローを実行し、1 つの出力フォルダーに保存します
4. 概要ページ — エクスポートしたすべての SVG を 1 つの自己完結型 index.html にインラインで埋め込みます（タイトルと図ごとのセクションを含み、CDN は使用しません）。ユーザーは 1 つのファイルを開くだけで済みます

バッチ内のすべての図に、同じ検証ルールとセルフチェックルールが適用されます。

図の種類

種類	キーワード	用途
フローチャート	flowchart TD/LR	プロセス、パイプライン、意思決定
シーケンス	sequenceDiagram	API 呼び出し、メッセージの受け渡し
クラス	classDiagram	OOP モデル、データ構造
ER	erDiagram	データベーススキーマ
状態	stateDiagram-v2	状態機械、ライフサイクル
ガント	gantt	プロジェクトのタイムライン
円グラフ	pie	比率
Git グラフ	gitGraph	ブランチ戦略
C4 コンテキスト	C4Context	高レベルのシステムコンテキスト
アーキテクチャ	architecture-beta	クラウド／CI/CD サービスのレイアウト
マインドマップ	mindmap	トピックの分類
ユーザージャーニー	journey	ユーザーエクスペリエンスのフロー
ユースケース	usecase-beta	アクターとシステムのやり取り（UML）
Cynefin	cynefin-beta	センスメイキング／複雑性の領域
イベントモデリング	eventmodeling	イベント駆動型システムのタイムライン
ツリービュー	treeView-beta	ファイル／ディレクトリ階層
Wardley マップ	wardley-beta	ビジネス戦略／バリューチェーン

構文リファレンス

フローチャート： reference/FLOWCHART.md を参照してください シーケンス： reference/SEQUENCE.md を参照してください クラスと ER： reference/CLASS-ER.md を参照してください アーキテクチャ： reference/ARCHITECTURE.md を参照してください ユースケース： reference/USECASE.md を参照してください その他の種類： reference/OTHER-TYPES.md を参照してください テーマとスタイル設定： reference/THEMES.md を参照してください

例

reference/EXAMPLES.md で、実際に作成した4つの例（JWT 認証シーケンス、マイクロサービスアーキテクチャ、注文の状態機械、クラウドアーキテクチャ）をご覧ください。各例には、ユーザープロンプト、生成された .mmd、出力ファイルが含まれています。

エクスポートコマンド

オプション1：ローカルでエクスポート（mmdc）

ローカルに mmdc をインストールする必要があります。オフラインでの使用に最適です。

# PNG (recommended: 2048px wide, white background)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white

# PNG with theme — valid -t values: default | dark | neutral | forest
# (`base` is NOT a valid -t value; it only works inside a %%{init: {'theme':'base'}}%% directive)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white --theme neutral

# SVG
mmdc -i diagram.mmd -o diagram.svg

# PDF
mmdc -i diagram.mmd -o diagram.pdf

オプション2：Kroki API（インストール不要）

mmdc を利用できない場合は、Kroki を使用してください。ローカルに依存関係をインストールする必要はありません。

# SVG via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o diagram.svg

# PNG via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/png -o diagram.png

# PDF is NOT supported by Kroki for Mermaid — POSTing to /mermaid/pdf returns
# HTTP 400 ("Unsupported output format: pdf for mermaid. Must be one of png or svg").
# For PDF, use the local mmdc path instead:  mmdc -i diagram.mmd -o diagram.pdf

Kroki の利点：

• ローカルへのインストールが不要
• curl が使えるあらゆるシステムで動作
• 20 種類以上の図に対応（PlantUML、GraphViz、D2 など）

Kroki を使用する場合：

• mmdc のインストールに失敗した場合
• すぐに作成する単発の図
• Node.js を使用しない CI/CD パイプライン

よくある間違い

間違い	解決策
mmdc が見つからない	npm install -g @mermaid-js/mermaid-cli
mmdc エラー Could not find Chrome	ヘッドレスブラウザーをインストールします：npx puppeteer browsers install chrome-headless-shell（または Kroki を使用します）
Kroki の PDF 出力が HTTP 400 で失敗する	Kroki が Mermaid で対応しているのは PNG／SVG のみです。PDF にはローカルの mmdc を使用してください
有効な図が mmdc に「無効」と報告される	このエラーは Chrome／puppeteer のセットアップ失敗が原因であり、構文エラーではありません。正しい .mmd を書き換えず、ブラウザーを修正するか Kroki で検証してください
シーケンス図の矢印が間違っている	リクエストには ->>、レスポンスには -->> を使用します
ラベルに特殊文字が含まれている	引用符で囲みます：A["Label: value"]
出力が空、または小さい	-w 2048 フラグを追加します
参加者の順序が間違っている	冒頭で participant を明示的に宣言します
サブグラフ名にスペースが含まれている	引用符で囲みます：subgraph "My Layer"