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

visual-explainer.mp4

Why

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.

Install

Pi:

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

Claude Code:

git clone https://github.com/nicobailon/visual-explainer.git ~/.claude/skills/visual-explainer
mkdir -p ~/.claude/commands
cp ~/.claude/skills/visual-explainer/prompts/*.md ~/.claude/commands/

Commands

Command	What it does
/generate-web-diagram	Generate an HTML diagram for any topic
/generate-visual-plan	Generate a visual implementation plan for a feature or extension
/generate-slides	Generate a magazine-quality slide deck
/diff-review	Visual diff review with architecture comparison and code review
/plan-review	Compare a plan against the codebase with risk assessment
/project-recap	Mental model snapshot for context-switching back to a project
/fact-check	Verify accuracy of a document against actual code

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.

Slide Deck Mode

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

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

visual-explainer-slides.mp4

How It Works

SKILL.md (workflow + design principles)
    ↓
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)
    ↓
templates/            ← reference templates with different palettes
├── architecture.html
├── mermaid-flowchart.html
├── data-table.html
└── slide-deck.html
    ↓
~/.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.

Limitations

• Requires a browser to view
• Switching OS theme requires a page refresh for Mermaid SVGs
• Results vary by model capability

Credits

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

License

MIT