mermaid-skill — インストール & ライブデモ

なぜ使うのか

主な機能

10種類以上の Mermaid ダイアグラムタイプに対応
mmdc によるローカルレンダリング（PNG / SVG / PDF）
エッジの交差を避ける自動レイアウトヒント
フィードバックに基づくダイアグラムの反復改善
リポジトリ内で動作し、ダイアグラムをコードと一緒にコミット可能

ライブデモ

実際の動作

mermaid-skill.replay ▶ 準備完了

0/0

インストール

作者のリポジトリ · Claude Skills の公式ドキュメント

ユースケース

実用的な使い方： mermaid-skill

現在のプロジェクトのアーキテクチャ図を作成する

👤 ドキュメント、ADR、オンボーディングガイドを書く開発者 ⏱ ~20 min beginner

使うタイミング： Slack でアーキテクチャの説明を繰り返していて、図が欲しいとき。

フロー

システムを説明する

Use mermaid-skill. Draw a flowchart of our service: client → API gateway → (auth / orders / payments) → Postgres / Redis / Stripe.✓ コピーしました

→ 意味のあるノード名を持つ .mmd ソースが生成され、docs/ に PNG がレンダリングされる
詳細を追加する

Add labels on each edge showing the protocol (HTTPS, gRPC, TCP) and auth type.✓ コピーしました

→ ソースが更新され、再レンダリングされる
コミットする

Commit docs/architecture.mmd and its PNG.✓ コピーしました

→ git add とコミットが実行される

結果： Confluence の古いスライドではなく、リポジトリ内の生きたダイアグラム。

注意点

ダイアグラムがエッジだらけの迷路になる — Claude にサブグラフと方向ヒントを使わせること。すべてを1つのレイヤーに詰め込まない

組み合わせ： filesystem · git

デバッグ中にシーケンス図を作成する

👤 クロスサービスのバグを追跡しているエンジニア ⏱ ~15 min beginner

使うタイミング： 非同期のやりとりを理解しようとしていて、文章だけでは伝わらないとき。

フロー

フローを説明する

Use mermaid-skill. Sequence diagram: browser → SSR → auth service → session store → page render, with failure mode when session is stale.✓ コピーしました

→ 障害パターンが注釈されたシーケンス図
バグに注釈を付ける

Highlight the line where the bug manifests.✓ コピーしました

→ 問題のメッセージにボックス/ノートの注釈が追加される

結果： バグチケットに貼り付けられる図。

実際のデータベーススキーマから ERD を生成する

👤 データエンジニア、バックエンド開発者 ⏱ ~20 min intermediate

使うタイミング： 設計レビューのためにスキーマを可視化したいとき。

フロー

スキーマを解析する

Use mermaid-skill. Read the schema.sql (or query the live DB via postgres MCP) and produce a Mermaid ERD.✓ コピーしました

→ リレーションとカーディナリティを含む .mmd ERD
ノイズを除去する

Drop audit tables and focus on the core domain entities.✓ コピーしました

→ 整理された ERD

結果： 手作業なしで正確な ERD が得られる。

注意点

推測時にカーディナリティが不正確になる — 実際の外部キー定義を提供すること。モデルに推測させない

組み合わせ： postgres

組み合わせ

他のMCPと組み合わせて10倍の力を

mermaid-skill + filesystem

ダイアグラムを対象コードと同じ場所に保管する

services/ 内の各サービスに docs/architecture.mmd を追加してレンダリングする。✓ コピーしました

mermaid-skill + postgres

本番データベースから ERD を自動生成する

ステージング DB に接続し、スキーマを Mermaid ERD としてレンダリングする。✓ コピーしました

mermaid-skill + git

ダイアグラムをコード変更と一緒にバージョン管理する

コード変更と同じ PR で、更新されたダイアグラムをコミットする。✓ コピーしました

ツール

このMCPが提供する機能

ツール	入力	呼び出すタイミング	コスト
write_mermaid	description, diagram type	ダイアグラムのリクエスト時	0
render_mmdc	.mmd path, output format	ソースが確定した後	local mmdc
iterate_diagram	current diagram + feedback	レビューアーからのフィードバック時	0

コストと制限

運用コスト

APIクォータ: なし
呼び出しあたりのトークン: 少量 — Mermaid ソースはコンパクト
金額: 無料（mmdc はオープンソース）
ヒント: 大きなダイアグラムの場合、大規模な書き直しのリトライを避けるためにサブグラフを個別に生成してください。

セキュリティ

権限、シークレット、影響範囲

認証情報の保管： なし

データ送信先： スキル自体からのデータ送出なし

トラブルシューティング

よくあるエラーと対処法

mmdc not found

グローバルにインストールしてください: npm i -g @mermaid-js/mermaid-cli

確認： which mmdc

Render fails with syntax error — レンダリング時の構文エラー

Mermaid にはバージョン固有の構文があります。mmdc --version を実行し、スキルが想定するバージョンと一致させてください

確認： mmdc --version

Diagram is a mess of crossing edges — エッジが交差して見づらい

方向ヒント（TD/LR）を追加するか、サブグラフでグループ化するか、複数のダイアグラムに分割してください

代替案

mermaid-skill 他との比較

代替案	代わりに使う場面	トレードオフ
PlantUML / draw.io	より細かい制御や Mermaid 以外の構文が必要なとき	セットアップが多く、レンダリングツールチェーンが異なる
paperbanana-skill	学術出版品質のダイアグラムが必要なとき	より重量級で、美的目標が異なる

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る