visual-explainer

An agent skill that turns complex terminal output into styled HTML pages you actually want to read.

Ask your agent to explain a system architecture, review a diff, or compare requirements against a plan. Instead of ASCII art and box-drawing tables, it generates a self-contained HTML page and opens it in your browser.

> draw a diagram of our authentication flow
> /diff-review
> /plan-review ~/docs/refactor-plan.md

Every coding agent defaults to ASCII art when you ask for a diagram. Box-drawing characters, monospace alignment hacks, text arrows. It works for trivial cases, but anything beyond a 3-box flowchart turns into an unreadable mess.

Tables are worse. Ask the agent to compare 15 requirements against a plan and you get a wall of pipes and dashes that wraps and breaks in the terminal. The data is there but it's painful to read.

This skill fixes that. Real typography, dark/light themes, interactive Mermaid diagrams with zoom and pan. No build step, no dependencies beyond a browser.

Claude Code (marketplace):

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

Note: Claude Code plugins namespace commands as /visual-explainer:command-name.

Pi:

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

Or clone and run:

git clone --depth 1 https://github.com/nicobailon/visual-explainer.git
cd visual-explainer && ./install-pi.sh

OpenAI Codex:

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

# Install skill
cp -r /tmp/visual-explainer/plugins/visual-explainer ~/.agents/skills/visual-explainer

# Optional: Install slash commands (deprecated, but works)
mkdir -p ~/.codex/prompts
cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.codex/prompts/

rm -rf /tmp/visual-explainer

Invoke with $visual-explainer or let Codex activate it implicitly. With prompts installed, use /prompts:diff-review, /prompts:plan-review, etc.

The agent also kicks in automatically when it's about to dump a complex table in the terminal (4+ rows or 3+ columns) — it renders HTML instead.

Any command that produces a scrollable page supports --slides to generate a slide deck instead:

/diff-review --slides
/project-recap --slides 2w

You can set a preferred color palette so every generated page uses consistent colors. Create a config file in your project:

# .claude/visual-explainer.local.md
---
theme: dracula
---

The agent reads this file and applies the theme's colors instead of picking its own. Fonts, layout, and animations are still chosen freely — only the color palette is fixed.

Available themes:

Every theme includes both light and dark mode support via prefers-color-scheme. Every generated page includes an interactive theme picker with all 11 themes.

Adding custom themes: Create a new file in themes/<name>.md following the same structure as existing themes. Define CSS custom properties (using the same variable names) and Mermaid themeVariables.

.claude-plugin/
├── plugin.json           ← marketplace identity
└── marketplace.json      ← plugin catalog
plugins/
└── visual-explainer/
    ├── .claude-plugin/
    │   └── plugin.json   ← plugin manifest
    ├── SKILL.md           ← workflow + design principles
    ├── commands/          ← slash commands
    ├── references/        ← agent reads before generating
    │   ├── css-patterns.md   (layouts, animations, theming)
    │   ├── libraries.md      (Mermaid, Chart.js, fonts)
    │   ├── responsive-nav.md (sticky TOC for multi-section pages)
    │   └── slide-patterns.md (slide engine, transitions, presets)
    ├── themes/            ← 11 pre-built color themes
    │   ├── dracula.md, nord.md, one-dark.md, ...
    │   └── (add custom themes here)
    ├── templates/         ← reference templates with different palettes
    │   ├── architecture.html
    │   ├── mermaid-flowchart.html
    │   ├── data-table.html
    │   └── slide-deck.html
    └── scripts/
        └── share.sh       ← deploy HTML to Vercel for sharing

Output: ~/.agent/diagrams/filename.html → opens in browser

The skill routes to the right approach automatically: Mermaid for flowcharts and diagrams, CSS Grid for architecture overviews, HTML tables for data, Chart.js for dashboards.

• Requires a browser to view
• Results vary by model capability

Borrows ideas from Anthropic's frontend-design skill and interface-design.

MIT