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

Each one produces a single .html file styled with Tailwind CSS v4 and shadcn/ui design tokens, with automatic dark/light theme support, a settings panel, interactive Mermaid diagrams, and ApexCharts visualizations. No build step, no dependencies beyond a browser.

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 that nobody would put in a presentation or share with a team.

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.

The skill follows the Agent Skills specification. Clone it into your agent's skills directory:

# Claude Code
git clone https://github.com/strefethen/visual-explainer.git ~/.claude/skills/visual-explainer

# Other agents — point at the directory containing SKILL.md,
# or paste its contents into your system prompt

If you have surf-cli installed, the skill can also generate illustrations via Gemini and embed them in pages. The agent detects surf automatically and skips image generation if it's not there.

The agent loads the skill when you mention diagrams, architecture, flowcharts, schemas, or visualizations. It 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 and opens it in the browser. Output goes to ~/.agent/diagrams/.

The skill ships with five prompt templates:

/diff-review is probably the most useful. Run it with no arguments to diff against main, or pass any git ref:

/diff-review                   # feature branch vs main (default)
/diff-review abc123            # single commit
/diff-review main..HEAD        # committed changes only
/diff-review #42               # pull request

It generates a full page with before/after architecture diagrams, KPI dashboard, structured Good/Bad/Ugly code review, decision log with confidence indicators, and re-entry context for your future self.

/plan-review does something similar but for implementation plans — pass it a plan file and it cross-references every claim against the actual codebase, produces current vs. planned architecture diagrams, and flags risks and gaps:

/plan-review ~/docs/refactor-plan.md

/project-recap is designed for context-switching back to a project after days away. It scans recent git activity and produces an architecture snapshot, decision log, and cognitive debt hotspots. /fact-check takes any document that makes claims about code and verifies every one of them.

SKILL.md (workflow + design principles)
    ↓
references/           ← agent reads before each generation
├── design-system.md  (Tailwind v4 + shadcn tokens, boilerplate, component patterns)
├── libraries.md      (Mermaid theming, ApexCharts, PivotTable.js, font pairings)
└── responsive-nav.md (sticky sidebar TOC for multi-section pages)
    ↓
templates/            ← agent reads the matching reference template
├── architecture.html (Tailwind Grid cards with design token theming)
├── mermaid-flowchart.html (Mermaid + ELK + zoom controls)
└── data-table.html   (tables, KPIs, pivot tables with ApexCharts)
    ↓
~/.agent/diagrams/filename.html → opens in browser

The agent reads the design system reference and the matching template, generates a self-contained HTML file with automatic dark/light theming via shadcn tokens, and opens it. The skill handles 11 diagram types — Mermaid for anything with connections (flowcharts, sequences, ER, state machines, mind maps), Tailwind Grid for text-heavy architecture overviews, HTML tables for data, ApexCharts for dashboards — and routes to the right approach automatically.

Every page includes a settings panel with theme toggle (Auto/Light/Dark) and font scale slider. To customize the output directory, browser command, or add your own diagram types, edit the files directly. The agent reads them fresh each time.

• Requires a browser to view — no inline terminal rendering
• Switching OS theme requires a page refresh for Mermaid SVGs (CSS-styled elements respond instantly)
• Results vary by model capability — the skill provides design guidance, not pixel-perfect specs

This is a fork of nicobailon/visual-explainer, which established the core concept: an agent skill that replaces ASCII art and box-drawing tables with styled HTML pages. The original's architecture — SKILL.md workflow, reference/template structure, diagram type taxonomy, and proactive table rendering — provided an excellent foundation.

This fork rewrites the rendering stack. The original used hand-rolled CSS with bespoke palettes per template. This fork replaces that with Tailwind CSS v4, shadcn/ui design tokens (OKLCH color space), and a unified component system. Other changes: Chart.js → ApexCharts v5, new PivotTable.js integration, mandatory settings panel with theme toggle and font scaling, and a complete design system reference (design-system.md) replacing the original css-patterns.md. The templates and ~58% of SKILL.md were rewritten to match.

The scope of the changes made contributing back impractical — the rendering approach is fundamentally different — but the original project's design decisions made this rewrite possible.

Original concept and architecture by nicobailon. Also borrows ideas from Anthropic's frontend-design skill and interface-design.

MIT