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, intentional 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:

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

Or from a local checkout:

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

The package manifest advertises the canonical skill and command templates:

"pi": {
  "skills": ["./plugins/visual-explainer"],
  "prompts": ["./plugins/visual-explainer/commands"]
}

If you previously used the old curl/manual installer, remove those copied files before using pi install; otherwise Pi will report skill and prompt conflicts because the user-level copies shadow the package resources:

rm -rf ~/.pi/agent/skills/visual-explainer
rm -f ~/.pi/agent/prompts/{diff-review,fact-check,generate-slides,generate-visual-plan,generate-web-diagram,plan-review,project-recap,share-page}.md

The legacy installer still works if you prefer copied files over package management:

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

# Optional, only if your Codex build supports prompt templates:
cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.codex/prompts/

rm -rf /tmp/visual-explainer

Invoke with $visual-explainer or ask Codex to use the visual-explainer skill. If prompts are installed and supported, use /prompts:diff-review, /prompts:plan-review, etc.

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

# Optional command templates:
cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.config/opencode/command/

rm -rf /tmp/visual-explainer

Activate it by asking OpenCode to use the visual-explainer skill. Command-template behavior depends on the installed OpenCode/opencode build.

Cursor:

Add configs/cursor/visual-explainer.mdc to your Cursor rules, or copy its contents into the project rules UI. This is rules-based guidance that points Cursor at the canonical skill; it does not claim native Agent Skills support.

OpenClaw:

Use configs/openclaw/AGENTS.md as lightweight project guidance and copy or reference plugins/visual-explainer/ as the canonical skill source. No native OpenClaw plugin adapter is included.

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.

/generate-web-diagram can also produce article-style explainers that combine prose, diagrams, screenshots, and tables in one page.

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

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

.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)
    ├── 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.

• Generated HTML is portable and self-contained, but auto-opening depends on the harness, browser access, and sandbox rules.
• All harnesses write visual output to ~/.agent/diagrams/ unless the user asks for a different path.
• /share-page uses plugins/visual-explainer/scripts/share.sh, which expects a Pi-compatible vercel-deploy skill in a standard Pi skill location. Other harnesses can still generate and open pages, but sharing may need that dependency installed separately.
• Results vary by model capability.

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

MIT