What is the visual-explainer skill?
Visual-explainer is a skill by nicobailon that has your agent generate one HTML file for diagrams, diff reviews, plan audits, comparison tables, project recaps and slide decks. The file holds inline CSS, JS and SVG, opens in a browser, and defaults to figures with short captions rather than long prose.
Visual-explainer is built around one default output: a single HTML page whose spine is figures, with text as captions. The README opens with a complaint that agents fall back to ASCII art and pipe-drawn tables once a diagram gets past three boxes.
Output lands in ~/.agent/diagrams/ unless you name a path, as one file with inline CSS, JS and an SVG favicon. When a terminal table would run to 4 or more rows or 3 or more columns, the agent renders HTML instead.
What changes in your agent's output
- Hand-drawn inline SVG diagrams replace ASCII art, and every arrow carries a verb such as writes, invalidates or polls 30s.
- Each figure sits in a figure element with a caption that states one claim.
- Numbers get a picture beside them, such as a waffle chart, bars or a sparkline.
- Cases like failure modes or options become small multiples, not a table of sentences.
- Pages follow prefers-reduced-motion and define colors as tokens for light and dark schemes.
Commands it ships
/generate-web-diagramdraws a diagram of a system or flow./diff-reviewand/plan-reviewreview a diff, or compare a plan file against the code./project-recapproduces a recap of a project./generate-slidesbuilds a slide deck, with PPTX export only on request./generate-videobuilds a video deck rendered to MP4.- Command templates for
/fact-checkand/generate-visual-planalso sit in the commands folder.
Who visual-explainer is for
Best for
- Understanding a large diff or refactor plan before merge, with the evidence laid out as figures.
- Architecture overviews, data flows and sequence diagrams that outgrow a terminal. Its style guide asks for a 12-column grid, which pairs with layout grid habits.
- Recaps or slide decks generated from a project the agent just read.
Not for
- Designing a product interface. It explains things and does not build your UI. To check a built page, see frontend visual QA.
- Setups without a browser. The compatibility note says a browser is needed to view the HTML.
- Video export without ffmpeg, Chrome and playwright-core, which the README says are installed separately.
- Motion rules for your own site. See web motion design.
Use it with UiChemy
Visual-explainer produces explainer pages, not WordPress sites. Use it to map a project or review a plan, then build the site itself with UiChemy Composer inside Elementor or Gutenberg. Click Get Started on uichemy.com.
How to install Visual Explainer Skill: Turn Diffs and Plans into HTML Pages
/plugin marketplace add nicobailon/visual-explainerAdd the marketplace
In Claude Code, run
/plugin marketplace add nicobailon/visual-explainer.Install the plugin
Run
/plugin install visual-explainer@visual-explainer-marketplace. Claude Code plugins namespace commands as /visual-explainer:command-name.Codex CLI
Run
git clone --depth 1 https://github.com/nicobailon/visual-explainer.git, then copy plugins/visual-explainer to ~/.codex/skills/visual-explainer. Invoke it with$visual-explainer.Cursor
Copy plugins/visual-explainer to ~/.cursor/skills/visual-explainer for every project, or to .cursor/skills/visual-explainer for one workspace.
Pi
Run
pi install git:github.com/nicobailon/visual-explainer. The README also covers OpenCode, Antigravity CLI and MCP hosts.
Check that it loaded
Ask the agent to draw a diagram of a flow in your project. It should write an HTML file to ~/.agent/diagrams/ and reply with a one line summary.
Key features
- Figures lead, words labelSKILL.md makes figures the spine of the page and text the caption. The first viewport shows the main idea as a picture plus one sentence.
- Draw the mechanismA request path through a cache beats a box labeled cache. Diagrams are drawn by hand in inline SVG, and Mermaid is used only when you ask or supply Mermaid source.
- Four visual registersInstrument, Blueprint, Paper and Editorial are matched to the content: reviews and metrics, architecture, concepts and reading, or recaps and decks.
- Accessibility rulesBody text is at least 16px, labels at least 12px, text contrast at least 4.5 to 1, and keyboard focus stays visible. Both color schemes must work.
- Slide decks and PPTXSlides are made only when asked. PPTX export runs on request or with --pptx, HTML stays the source, and the PPTX has no animation or live diagrams.
- Captioned or narrated video/generate-video renders a video deck to a 1080p MP4. It is narrated only when a speech API key is set, otherwise silent with captions.
- Quick modeA literal --quick on /generate-web-diagram, /diff-review, /plan-review or /project-recap emits a JSON spec that a bundled renderer turns into HTML.
- Visual plansImplementation plans are written as plan tags and rendered with a bundled script. The reader answers inside the page, and the agent treats that response as data.
- Local MCP servervisual-explainer-mcp is a stdio server with three tools: visual_explainer_prepare, visual_explainer_render_html and visual_explainer_render_quick. It starts no HTTP listener.
Frequently asked questions
What is the visual-explainer skill?
It is an agent skill by nicobailon that turns complex output into styled, self-contained HTML. Ask for a diagram, a diff review or a plan review and the agent writes a page with real typography, hand-drawn SVG diagrams and light and dark themes, then opens it in your browser.
How do I install visual-explainer?
For Claude Code, add the marketplace with /plugin marketplace add nicobailon/visual-explainer, then run /plugin install visual-explainer@visual-explainer-marketplace. Other agents use a clone and a copy of plugins/visual-explainer into their skills folder, and Pi has its own install command.
Which AI coding agents can use visual-explainer?
The README table lists Claude Code, Pi, MCP hosts, Antigravity CLI, Codex CLI, OpenCode, Cursor, Agent Plugins clients, OpenClaw, and VS Code Copilot or Copilot CLI. Support level varies by row, from a marketplace plugin to guidance only, so read the row for your agent.
Does visual-explainer need a browser or other dependencies?
It needs a browser to view the generated HTML. Normal use has no build step. The optional MCP server and PPTX export use small Node dependencies, and video export needs ffmpeg, Chrome and playwright-core installed separately.
Can visual-explainer make slides or video?
Yes, when asked. /generate-slides builds an HTML deck, and PPTX export is best effort with HTML kept as the source. /generate-video records a deck to a 1080p MP4, narrated when a speech API key is set and captioned otherwise.
Where does visual-explainer save its files?
The skill writes to ~/.agent/diagrams/ with a descriptive name, or to the path you give. For the MCP server and the Pi tool, the VISUAL_EXPLAINER_OUTPUT_DIR variable moves that output directory. Render tools do not open a browser unless you set open to true.
Does visual-explainer use Mermaid?
Not by default. SKILL.md says to draw every diagram by hand in inline SVG for exact placement, fonts, theme tokens and animation. It uses Mermaid only when you ask for it or supply Mermaid source, with a list of traps to avoid.
What license does visual-explainer use?
The repository is MIT licensed. The SKILL.md frontmatter and the README badge both say MIT, and GitHub detects the same license. The skill folder also lists a plugin.json under .claude-plugin for marketplace use.