visual-explainer

v0.7.1 — 複雑なターミナル出力を、自己完結 HTML の図・表・レビュー・スライドに変換する Agent Skill。

1 — 概要
何を解決するか

コーディングエージェントは、図や比較表を頼まれると ASCII アートや罫線テーブルへ寄りがち。visual-explainer はその出力を、ブラウザで読める スタイル付き HTML ページ に変換する。

対象はアーキテクチャ説明、diff レビュー、計画レビュー、プロジェクト復帰用 recap、ファクトチェック、データ表、スライドデッキ。生成物はビルド不要で、基本はブラウザだけで開ける。

自動発動: 4 行以上または 3 列以上の複雑な表をターミナルに出しそうな場面では、HTML テーブルとしてレンダリングする方針。
0.7.1
current version

Pi は package.json の pi メタデータでスキルとプロンプトを直参照。Codex は ~/.codex/skills/。Mermaid は diagram-shell を正とする。

2 — 最新更新点
v0.7.1

Pi をパッケージとして扱う

pi install git:github.com/nicobailon/visual-explainer で、リポジトリ内の plugins/visual-explainer/ と commands/ を正として読み込める。手動コピーと併用すると衝突するため、旧手順のファイルは README の手順どおり削除してから切り替える。

v0.7.1

ハーネス別の軽量ガイド

Pi・Codex CLI・OpenCode・Cursor・OpenClaw 向けに、コピー先パスやルール参照だけを README に整理。ランタイム用のアダプタやスキル複製は増やさない方針。

v0.7.1

/share から /share-page へ

非推奨だった共有コマンド名を整理し、テンプレートとドキュメントを /share-page に統一。share.sh の説明はインストール済みスキルディレクトリ基準の表現に揃えた。

v0.6.3

bare Mermaid は禁止

templates/mermaid-flowchart.html の diagram-shell を丸ごと使う。v0.6.0 では multi-diagram 用の initDiagram(shell) とズーム UI を導入済み。

3 — インストール
ハーネス要点主な導線
Claude Codeマーケットプレースplugins/visual-explainer/ を正としたレイアウト
Piパッケージメタデータ + インストーラpackage.json の pi.skills / pi.prompts、または install-pi.sh
Codex CLIネイティブ skill パス + 任意プロンプト~/.codex/skills/visual-explainer、任意で ~/.codex/prompts/
OpenCode / opencode観測された skill / command パス~/.config/opencode/skill/visual-explainer など
Cursorルールベースconfigs/cursor/visual-explainer.mdc をルールに追加
OpenClaw軽量 AGENTS / ルールconfigs/openclaw/AGENTS.md と正規スキルディレクトリ参照
導入手順

Claude Code（マーケットプレース）

/plugin marketplace add nicobailon/visual-explainer
/plugin install visual-explainer@visual-explainer-marketplace

スラッシュコマンドは /visual-explainer:コマンド名 のように名前空間付き。

Pi（推奨: パッケージインストール）

pi install git:github.com/nicobailon/visual-explainer

ローカル clone から入れる場合は pi install ./visual-explainer（リポジトリルートがカレント）。

旧手動コピーからの移行: 以前 install-pi.sh や手コピーで入れたファイルが残っていると、パッケージ版と衝突する。README にある rm -rf ~/.pi/agent/skills/visual-explainer とプロンプト削除のあと、上記 pi install を使う。

レガシー: curl インストーラ

curl -fsSL https://raw.githubusercontent.com/nicobailon/visual-explainer/main/install-pi.sh | bash

コピー先に展開する方式。パッケージ管理より手元ファイルを優先したい場合向け。

Codex CLI

git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer

mkdir -p ~/.codex/skills ~/.codex/prompts
cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.codex/skills/visual-explainer

# 任意（ビルドがプロンプトをサポートしている場合のみ）:
cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.codex/prompts/

rm -rf /tmp/visual-explainer

$visual-explainer でスキルを指す。プロンプトを入れた環境では /prompts:diff-review など（Codex 側の slash prompts は非推奨扱いだが動作しうる）。

OpenCode / opencode

git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer

mkdir -p ~/.config/opencode/skill ~/.config/opencode/command
cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.config/opencode/skill/visual-explainer

# 任意のコマンドテンプレート:
cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.config/opencode/command/

rm -rf /tmp/visual-explainer

エージェントに visual-explainer スキルの利用を依頼する。コマンドテンプレの挙動はビルド依存。

Cursor

リポジトリの configs/cursor/visual-explainer.mdc をプロジェクトルールに追加するか、内容をルール UI に貼る。ネイティブ Agent Skills としての公式サポートは謳わず、正規スキルへ誘導するルール扱い。

OpenClaw

configs/openclaw/AGENTS.md を軽いガイドとして使い、実体は plugins/visual-explainer/ を参照する。

4 — コマンド一覧
コマンド 説明
/generate-web-diagram 任意のトピックで HTML 図を生成
/generate-visual-plan 機能・拡張のビジュアル実装計画を生成
/generate-slides 雑誌品質のスライドデッキを生成
/diff-review アーキテクチャ比較とコードレビュー付きのビジュアル diff レビュー
/plan-review 計画とコードベースの比較とリスク評価
/project-recap プロジェクトに戻るためのメンタルモデルスナップショット
/fact-check ドキュメントの内容を実際のコードと照合して検証
/share-page HTML を Vercel にデプロイしてライブ URL を取得

スクロール形式のページを出す各コマンドは、--slides でスライドデッキ出力に切り替え可能（例: /diff-review --slides、/project-recap --slides 2w）。

5 — 図解生成のルール
Mermaid は shell ごと使う

v0.6.3 の重要なルールは、Mermaid 図を裸の <pre class="mermaid"> で置かないこと。ズーム、パン、reset、expand、クリック展開まで含む diagram-shell 構造が canonical pattern になっている。

.diagram-shell
└── .mermaid-wrap
    ├── .zoom-controls
    └── .mermaid-viewport
        └── .mermaid-canvas
            └── script.diagram-source
Flow / Sequence Mermaid。5+ nodes や分岐は TD 優先。
Class / C4 Class は classDiagram。C4 は native C4 ではなく graph TD + subgraph。
Tables 本物の <table>。ASCII 表や CSS Grid 代用は避ける。
Large Architecture 15+ 要素は hybrid。小さな Mermaid overview と詳細カードを分ける。
6 — 構成

スキルは用途に応じてアプローチを切り替える。フローチャート・シーケンス・ER・Class・C4 は Mermaid、アーキテクチャ概要は CSS Grid、データは HTML テーブル、ダッシュボードは Chart.js が基本。

.claude-plugin/
├── plugin.json           ← マーケットプレース用
└── marketplace.json      ← プラグインカタログ
plugins/
└── visual-explainer/
    ├── .claude-plugin/
    │   └── plugin.json   ← プラグインマニフェスト
    ├── SKILL.md          ← ワークフローとデザイン原則
    ├── commands/         ← スラッシュコマンド
    ├── references/       ← 生成前にエージェントが参照
    │   ├── css-patterns.md
    │   ├── libraries.md
    │   ├── responsive-nav.md
    │   └── slide-patterns.md
    ├── templates/
    │   ├── architecture.html
    │   ├── mermaid-flowchart.html
    │   ├── data-table.html
    │   └── slide-deck.html
    └── scripts/
        └── share.sh      ← Vercel へデプロイ用

出力先: ~/.agent/diagrams/ファイル名.html に保存され、ブラウザで開く。docs-site 用に転用する場合は、このページのように docs/<name>.html へ配置する。

7 — 共有フロー
/share-page

/share-page は生成済み HTML を Vercel にデプロイし、ライブ URL と claim URL を返す。内部では plugins/visual-explainer/scripts/share.sh が HTML を一時ディレクトリの index.html として扱い、Pi 向け vercel-deploy スキルがある標準配置を前提にする。

bash plugins/visual-explainer/scripts/share.sh ~/.agent/diagrams/my-diagram.html

上記 plugins/... はリポジトリ内パス。実運用ではインストール済みスキル直下の scripts/share.sh を指す。

8 — 制限
  • 生成 HTML は自己完結だが、自動でブラウザを開けるかはハーネス・サンドボックス・ポリシー次第
  • 既定の出力先は harness により ~/.agent/diagrams/ など（ユーザーが別パスを指定しない限り）
  • OS テーマ切替後は Mermaid の SVG を合わせるためにページ再読み込みが必要な場合がある
  • /share-page は share.sh が Pi 互換の vercel-deploy スキルを想定。他ハーネスでは共有だけ別途用意が必要なことがある
  • 結果の品質はモデル能力に依存する
  • 共有 URL は公開デプロイになりうるため、機密を含む HTML には不向き
9 — クレジット・リンク

Anthropic の frontend-design skill と interface-design のアイデアを参考にしています。

ライセンス：MIT

リポジトリ：nicobailon/visual-explainer（GitHub）

参照バージョン：0.7.1（CHANGELOG）