diagram-d2

name	diagram-d2
description	情報源（Notion / GitHub / コード / 会話）を整理して D2 で図解を作り、SVG にレンダーして Notion 等に貼れる形にするスキル。図の正本は .d2 テキストファイルに一元化し、差分編集することで「ここ直して」が崩れないようにする。ユーザーが「図にして」「ダイアグラム作って」「構成図/フロー/関係図を描いて」と言ったとき、または Notion/GitHub の内容を可視化したいときに使う。
license	MIT
user-invocable	true
disable-model-invocation	false
allowed-tools	Bash(*), Read, Write, Edit, WebSearch, WebFetch
argument-hint	["図にしたい対象：Notionページ / GitHubリポジトリ / ファイル / 説明"]
metadata	{"version":"1.0"}

diagram-d2: D2 で「わかりやすい程度に整った」図解を作る

LLM作図の標準方針を実行するスキル。派手さは狙わず、読めば分かる水準を低労力で出す。 なぜ D2 か・他ツールとの比較は README を参照。

D2の書き方に迷ったら references/d2-syntax.md（形・接続・コンテナ・クラス・sql_table/ sequence_diagram・テーマ・アイコン・落とし穴まで。d2 0.7.1 で動作確認済み）を読むこと。

中核原則

• 図の正本は .d2 テキストファイル、ただ1つ。SVG は使い捨てのビルド成果物。
• 「ここ直して」は 必ず .d2 を Edit で差分編集 → 再レンダー。SVG を手で編集して二重管理にしない。
• レイアウト座標を手置きしない。D2 の自動レイアウト（dagre/ELK）に任せる。
• GUI 作図ツールの MCP は使わない。

前提：d2 CLI の確認/導入

command -v d2 || echo "NOT installed"

未インストールなら導入：

# 公式インストーラ（推奨）
curl -fsSL https://d2lang.com/install.sh | sh -s --
# または Homebrew
brew install d2

導入をユーザーに確認してから実行すること（ネットワーク越しのインストールのため）。

実行フロー

1. 対象とゴールを確定する

• 何を：Notionページ / GitHubリポジトリ / ローカルのコード・ファイル / 口頭説明。
• どんな図：システム構成 / データフロー / 画面遷移 / 概念関係 / シーケンス 等。
• 曖昧なら 1〜2 個だけ質問して絞る（質問攻めにしない）。

2. 対象を調べて理解する

図を描く前段。指定された1ページ／1リポジトリを取ってくるだけで終わらせず、対象が腑に落ちるまで調べる。

• 裏取りしながら理解を作る：関連リンク・サブページ・周辺コード・ドキュメントをたどり、構造・登場物・関係が分かるまで確かめる。調べる深さは図の規模に見合わせる（小さい図なら軽く、大きい図なら周辺まで）。
  • Notion：接続されている Notion MCP（notion-fetch / notion-search 等）があれば利用。
  • GitHub：GitHub MCP、またはローカルなら Read/Glob/Grep。
• ユーザー自身の事情は聞き直さない：好みのテーマ・用途・制約などは、メモリ・エージェントの設定ファイル・進行中の会話から既にコンテキストとして供給されている前提。ここで本人に事情を尋ねない。確認が要るのは「対象そのもの」が曖昧なときだけ（それも最小限）。
• 調べた内容から 図の骨子（ノード・関係・グルーピング）を構造化する。生データを図に丸写ししない。

3. .d2 を生成する（明瞭さを稼ぐ標準装備を入れる）

出力先はプロジェクトの作業ディレクトリ（例：out/）に something.d2 として Write。最低限：

• direction（流れに沿って right か down）
• 関連要素を コンテナでグルーピング（group: { ... }）
• 辺にラベル（A -> B: 呼び出し）で関係を言語化
• 役割を形で示す（DB=shape: cylinder、外部=shape: hexagon、人=shape: person）
• 必要なら vars: { d2-config: { layout-engine: elk, theme-id: 0 } }
• アイコンが要るときは icons.terrastruct.com を利用

最小例：

direction: right
user: { shape: person }
api: API Gateway
db: { shape: cylinder }
user -> api: request
api -> db: query

4. レンダーする

d2 out/diagram.d2 out/diagram.svg      # SVG（第一候補・劣化なし）
d2 out/diagram.d2 out/diagram.png      # 崩れたとき/ラスタが要るとき

生成後、SVG をユーザーに見せて確認を促す。

5. 「直して」ループ

• 修正指示が来たら .d2 を Edit で該当箇所だけ書き換え → 再レンダー。全再生成しない。
• 満足したら成果物（SVG / 必要なら PNG）を確定。

6. Notion に貼る場合

• Notion は SVG を公式サポート（画像ブロック、<5MB）。崩れたら PNG。
• ページには SVG を貼りつつ元 .d2 をトグル or コードブロックで併置しておくと、後日の「直して」が .d2 差し替えで済む。

やらないこと

• Mermaid で出す（図タイプ縛りで要件に合わない。ユーザーが明示的に Mermaid を要求した場合のみ例外）。
• SVG を直接手編集して正本を二重化する。
• 1枚に詰め込みすぎる（密で読めなくなったら 図を分割する。デザインで無理に詰めない）。

人間側の編集環境（案内用）

• VSCode 拡張 terrastruct/d2-vscode（シンタックスハイライト＋ライブプレビュー）。
• D2 Playground: https://play.d2lang.com