visual-explainer-marketplace

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

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, hand-drawn diagrams that animate and respond to the reader. Normal skill use has no build step and no dependency beyond a browser; optional MCP and PPTX utilities use small Node dependencies.

Step through a state machine one event at a time: the route each event took lights up, jobs pile into queues and drain, and each step says why it happened (example).

Install

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, command templates, and Pi tool:

"pi": {
  "extensions": ["./plugins/visual-explainer/extension.ts"],
  "skills": ["./plugins/visual-explainer"],
  "prompts": ["./plugins/visual-explainer/commands"],
  "image": "./banner.png"
}

The Pi extension registers one native visual_explainer tool. Use action: "prepare" to plan a visual explanation after generating or reviewing a substantial plan, architecture, diff, or implementation, and action: "render" to render a page source (path) or complete HTML to ~/.agent/diagrams/, or to VISUAL_EXPLAINER_OUTPUT_DIR when set, with the same output jail as the MCP server. Render can open with viewer: "browser" by default, viewer: "glimpse" when glimpseui is installed, or viewer: "auto" to try Glimpse and fall back to the browser. /generate-web-diagram remains the bundled prompt template command.

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/{compare,diff-review,fact-check,generate-slides,generate-video,generate-visual-plan,generate-web-diagram,plan-review,project-recap,state-machine}.md
rm -f ~/.pi/agent/prompts/s[h]are*.md

The legacy installer still works if you prefer copied skill and prompt files over package management, but it does not install the native Pi tool:

curl -fsSL https://raw.githubusercontent.com/nicobailon/visual-explainer/main/install-pi.sh | bash

MCP:

Use visual-explainer-mcp from a package install, or run npm install --no-package-lock before pointing your host at plugins/visual-explainer/mcp/server.mjs from a checkout. Some hosts need an absolute path to the binary. The MCP server is local stdio only. It does not call an LLM, start an HTTP listener, handle credentials, or write outside its configured output directory (default ~/.agent/diagrams/). Set VISUAL_EXPLAINER_OUTPUT_DIR to move that jail to another directory on the same machine; unset keeps the default path byte-identical. A configured jail must resolve to itself, so symlinked jail paths, including macOS /tmp, are rejected before anything is created. The default directory follows a symlinked ~/.agent. Render targets reject existing symlinks and are written through a temporary file rename. Point the jail at a directory only your user can write; avoid world-writable or group-writable shared folders so another local user cannot replace render targets between validation and write.

Example package configuration:

{
  "mcpServers": {
    "visual-explainer": {
      "command": "visual-explainer-mcp"
    }
  }
}

Example checkout configuration:

{
  "mcpServers": {
    "visual-explainer": {
      "command": "node",
      "args": ["/absolute/path/to/visual-explainer/plugins/visual-explainer/mcp/server.mjs"]
    }
  }
}

The server exposes two tools: visual_explainer_prepare and visual_explainer_render_html. Render defaults to open: false; set open: true only when you want the server to request a browser or Glimpse window. It also exposes the bundled command templates as MCP prompts and the canonical SKILL.md, its references/*.md, the kit stylesheet, and command markdown as read-only resources.

Antigravity CLI:

Antigravity CLI is the supported Google successor path for consumer Gemini CLI workflows. It loads Agent Skills from .agents/skills/ at the workspace level or ~/.gemini/antigravity-cli/skills/ globally.

Global install:

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

mkdir -p ~/.gemini/antigravity-cli/skills
cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.gemini/antigravity-cli/skills/visual-explainer

rm -rf /tmp/visual-explainer

PowerShell (global):

$ErrorActionPreference = 'Stop'
$tmp = Join-Path $env:TEMP ("visual-explainer-" + [guid]::NewGuid().ToString())
$dest = Join-Path $env:USERPROFILE ".gemini\antigravity-cli\skills\visual-explainer"
$parent = Split-Path -Parent $dest
$run = $null
$staging = $null
$backup = $null
$moved = $false
$attempted = $false
$installed = $false
New-Item -ItemType Directory -Force -Path $tmp | Out-Null
try {
  $repo = Join-Path $tmp 'repo'
  git clone --depth 1 https://github.com/nicobailon/visual-explainer.git $repo
  if ($LASTEXITCODE -ne 0) { throw "git clone failed with exit code $LASTEXITCODE" }
  New-Item -ItemType Directory -Force -Path $parent | Out-Null
  $run = Join-Path $parent (".visual-explainer-install-" + [guid]::NewGuid().ToString())
  $staging = Join-Path $run 'staging'
  $backup = Join-Path $run 'backup'
  New-Item -ItemType Directory -Force -Path $run | Out-Null
  Copy-Item -LiteralPath (Join-Path $repo 'plugins\visual-explainer') -Destination $staging -Recurse -Force
  if (-not (Test-Path -LiteralPath (Join-Path $staging 'SKILL.md') -PathType Leaf)) { throw 'staged skill is incomplete' }
  if (Test-Path -LiteralPath $dest) { Move-Item -LiteralPath $dest -Destination $backup; $moved = $true }
  $attempted = $true
  Move-Item -LiteralPath $staging -Destination $dest
  $installed = $true
} finally {
  if (-not $installed -and $attempted) {
    if (Test-Path -LiteralPath $dest) { Move-Item -LiteralPath $dest -Destination (Join-Path $run 'failed') -ErrorAction SilentlyContinue }
    if ($moved -and (Test-Path -LiteralPath $backup) -and -not (Test-Path -LiteralPath $dest)) { Move-Item -LiteralPath $backup -Destination $dest -ErrorAction SilentlyContinue }
  }
  if ($run -and ((-not (Test-Path -LiteralPath $backup)) -or $installed)) { Remove-Item -LiteralPath $run -Recurse -Force -ErrorAction SilentlyContinue }
  Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue
}

Workspace install:

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

mkdir -p .agents/skills
cp -R /tmp/visual-explainer/plugins/visual-explainer .agents/skills/visual-explainer

rm -rf /tmp/visual-explainer

PowerShell (workspace):