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
> run a visual diff review for this branch
> review ~/docs/refactor-plan.md against the current codebase
visual-explainer.mp4
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.
Pi:
pi install https://github.com/sup/visual-explainer-codexCodex (local skill folder):
git clone https://github.com/sup/visual-explainer-codex.git ~/.codex/skills/visual-explainerThis repository already includes Codex-compatible metadata in agents/openai.yaml.
| Prompt recipe | What it does |
|---|---|
prompts/generate-web-diagram.md |
Generate an HTML diagram for any topic |
prompts/generate-visual-plan.md |
Generate a visual implementation plan for a feature or extension |
prompts/generate-slides.md |
Generate a magazine-quality slide deck |
prompts/diff-review.md |
Visual diff review with architecture comparison and code review |
prompts/plan-review.md |
Compare a plan against the codebase with risk assessment |
prompts/project-recap.md |
Mental model snapshot for context-switching back to a project |
prompts/fact-check.md |
Verify accuracy of a document against actual code |
Use these by asking naturally (for example: "run a visual diff review of HEAD vs main") and the skill routes to the matching recipe.
The skill 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 workflow that produces a scrollable page supports --slides to generate a slide deck instead:
run a visual diff review --slides
create a project recap --slides 2w
visual-explainer-slides.mp4
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.
- Requires a browser to view
- Switching OS theme requires a page refresh for Mermaid SVGs
- Results vary by model capability
Borrows ideas from Anthropic's frontend-design skill and interface-design.
MIT