Skip to content
Back to search

visual-explainer-marketplace

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nicobailon-visual-explainer/badge.svg)](/listings/nicobailon-visual-explainer)

HTML

<a href="/listings/nicobailon-visual-explainer"><img src="/api/listings/nicobailon-visual-explainer/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

| Harness | Support | Install path / behavior | |---|---|---| | Claude Code | Marketplace plugin | Preserved marketplace shape with source at `plugins/visual-explainer/` | | Pi | Package metadata plus installer | `package.json` advertises the skill, prompts, and native `visual_explainer` tool with `prepare` and `render` actions; `install-pi.sh` installs copied skill/prompt resources for legacy manual installs | | MCP hosts | Local stdio MCP server | `visual-explainer-mcp` exposes prepare and render tools, prompt templates, and read-only skill resources without starting an HTTP server | | PPTX export | Best-effort static utility | `visual-explainer-pptx` converts simple HTML slide decks to `.pptx`; HTML remains the source of truth | | Video export | Local renderer (needs ffmpeg, Chrome, and `playwright-core`, installed separately) | `/generate-video` writes a video deck and `visual-explainer-video` records it to a 1080p MP4, frame by frame, narrated when a speech API key is set and captioned otherwise | | Antigravity CLI | Native Agent Skills path | Copy `plugins/visual-explainer/` to `~/.gemini/antigravity-cli/skills/visual-explainer` for global use or `.agents/skills/visual-explainer` for one workspace | | Codex CLI | Native skill path plus optional prompts | Copy to `~/.codex/skills/visual-explainer`; optional prompts go in `~/.codex/prompts/` if your Codex build supports them | | OpenCode/opencode | Observed skill/command paths | Copy to `~/.config/opencode/skill/visual-explainer`; optional commands go in `~/.config/opencode/command/` | | Cursor | Native Agent Skills path | Copy `plugins/visual-explainer/` to `~/.cursor/skills/visual-explainer` globally or `.cursor/skills/visual-explainer` per workspace; optional legacy rule in `configs/cursor/` | | Agent Plugins clients | [Agent Plugins](https://agent-plugins.org/) 1.0.0 plugin | The repository root is the plugin: `plugin.json` plus `skills/visual-explainer`, a link to `plugins/visual-explainer/`. On Windows, clone with `git -c core.symlinks=true` so the link resolves | | OpenClaw | Lightweight AGENTS/rules guidance | Use the supplied AGENTS guidance with the canonical skill directory | | VS Code Copilot / Copilot CLI | Custom instructions or rules guidance | Add the supplied AGENTS guidance to your supported workspace instruction or rules setup |

**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 the output directory (see below), 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.

Pi output directory

Output defaults to `~/.agent/diagrams/`, regardless of global or `--local` installation. **Merge** this field into existing personal (`~/.pi/agent/settings.json`) or project (`<project>/.pi/settings.json`) settings, then run `/reload` or restart Pi:

{

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 38 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "visual-explainer-marketplace",
  3. "owner": {
  4. "name": "nicobailon"
  5. },
  6. "metadata": {
  7. "description": "Plugin distribution for visual-explainer",
  8. "version": "0.15.0",
  9. "pluginRoot": "./plugins"
  10. },
  11. "plugins": [
  12. {
  13. "name": "visual-explainer",
  14. "source": "./plugins/visual-explainer",
  15. "description": "Generate beautiful HTML pages for diagrams, diff reviews, plan reviews, slides, and data tables",
  16. "version": "0.15.0",
  17. "author": {
  18. "name": "nicobailon"
  19. },
  20. "repository": "https://github.com/nicobailon/visual-explainer",
  21. "license": "MIT",
  22. "keywords": [
  23. "diagrams",
  24. "html",
  25. "visualization",
  26. "diff-review",
  27. "slides"
  28. ],
  29. "category": "visualization",
  30. "tags": [
  31. "diagrams",
  32. "html-generation",
  33. "code-review",
  34. "slides"
  35. ]
  36. }
  37. ]
  38. }
README.md · README · 555 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p>
  2. <img src="banner.png" alt="visual-explainer" width="1100">
  3. </p>
  4. # visual-explainer
  5. **An agent skill that turns complex terminal output into styled HTML pages you actually want to read.**
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
  7. 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.
  8. ```
  9. > draw a diagram of our authentication flow
  10. > /diff-review
  11. > /plan-review ~/docs/refactor-plan.md
  12. ```
  13. https://github.com/user-attachments/assets/55ebc81b-8732-40f6-a4b1-7c3781aa96ec
  14. ## Why
  15. 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.
  16. 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.
  17. 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.
  18. <img src="replay.gif" alt="A job queue drawn as a state machine and replayed one event at a time: five jobs pile into the queue, two workers take jobs, a timed-out job lights the retry route back to the end of the queue, the queue drains, then jobs flow through the full picture" width="720">
  19. 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](examples/replay-job-queue.html)).
  20. ## Install
  21. | Harness | Support | Install path / behavior |
  22. |---|---|---|
  23. | Claude Code | Marketplace plugin | Preserved marketplace shape with source at `plugins/visual-explainer/` |
  24. | Pi | Package metadata plus installer | `package.json` advertises the skill, prompts, and native `visual_explainer` tool with `prepare` and `render` actions; `install-pi.sh` installs copied skill/prompt resources for legacy manual installs |
  25. | MCP hosts | Local stdio MCP server | `visual-explainer-mcp` exposes prepare and render tools, prompt templates, and read-only skill resources without starting an HTTP server |
  26. | PPTX export | Best-effort static utility | `visual-explainer-pptx` converts simple HTML slide decks to `.pptx`; HTML remains the source of truth |
  27. | Video export | Local renderer (needs ffmpeg, Chrome, and `playwright-core`, installed separately) | `/generate-video` writes a video deck and `visual-explainer-video` records it to a 1080p MP4, frame by frame, narrated when a speech API key is set and captioned otherwise |
  28. | Antigravity CLI | Native Agent Skills path | Copy `plugins/visual-explainer/` to `~/.gemini/antigravity-cli/skills/visual-explainer` for global use or `.agents/skills/visual-explainer` for one workspace |
  29. | Codex CLI | Native skill path plus optional prompts | Copy to `~/.codex/skills/visual-explainer`; optional prompts go in `~/.codex/prompts/` if your Codex build supports them |
  30. | OpenCode/opencode | Observed skill/command paths | Copy to `~/.config/opencode/skill/visual-explainer`; optional commands go in `~/.config/opencode/command/` |
  31. | Cursor | Native Agent Skills path | Copy `plugins/visual-explainer/` to `~/.cursor/skills/visual-explainer` globally or `.cursor/skills/visual-explainer` per workspace; optional legacy rule in `configs/cursor/` |
  32. | Agent Plugins clients | [Agent Plugins](https://agent-plugins.org/) 1.0.0 plugin | The repository root is the plugin: `plugin.json` plus `skills/visual-explainer`, a link to `plugins/visual-explainer/`. On Windows, clone with `git -c core.symlinks=true` so the link resolves |
  33. | OpenClaw | Lightweight AGENTS/rules guidance | Use the supplied AGENTS guidance with the canonical skill directory |
  34. | VS Code Copilot / Copilot CLI | Custom instructions or rules guidance | Add the supplied AGENTS guidance to your supported workspace instruction or rules setup |
  35. **Claude Code (marketplace):**
  36. ```shell
  37. /plugin marketplace add nicobailon/visual-explainer
  38. /plugin install visual-explainer@visual-explainer-marketplace
  39. ```
  40. Note: Claude Code plugins namespace commands as `/visual-explainer:command-name`.
  41. **Pi:**
  42. ```bash
  43. pi install git:github.com/nicobailon/visual-explainer
  44. ```
  45. Or from a local checkout:
  46. ```bash
  47. git clone --depth 1 https://github.com/nicobailon/visual-explainer.git
  48. pi install ./visual-explainer
  49. ```
  50. The package manifest advertises the canonical skill, command templates, and Pi tool:
  51. ```json
  52. "pi": {
  53. "extensions": ["./plugins/visual-explainer/extension.ts"],
  54. "skills": ["./plugins/visual-explainer"],
  55. "prompts": ["./plugins/visual-explainer/commands"],
  56. "image": "./banner.png"
  57. }
  58. ```
  59. 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 the output directory (see below), 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.
  60. #### Pi output directory
  61. Output defaults to `~/.agent/diagrams/`, regardless of global or `--local` installation. **Merge** this field into existing personal (`~/.pi/agent/settings.json`) or project (`<project>/.pi/settings.json`) settings, then run `/reload` or restart Pi:
  62. ```json
  63. {
  64. "visualExplainer": {
  65. "outputDir": "project"
  66. }
  67. }
  68. ```
  69. Precedence: default → personal settings → trusted project settings → nonblank `VISUAL_EXPLAINER_OUTPUT_DIR`. Pi handles merging and project trust.
  70. - `"project"` uses the session's Git root plus `.agent/diagrams/`, or the session directory outside Git.
  71. - Other strings are paths: `"docs/diagrams"`, `"/some/destination"`, or `"~/Documents/my diagrams"`. Relative paths use the session directory; only the exact `"project"` is special.
  72. - Blank values select the default; non-strings are an error. The environment variable keeps its existing behavior (resolved against Pi's launch directory, no `~`).
  73. Prepare reports `outputDir`; `/fact-check` uses it when no path is given. Only the native Pi tool reads this setting; a Pi without `getSettings()` keeps the default.
  74. 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:
  75. ```bash
  76. rm -rf ~/.pi/agent/skills/visual-explainer
  77. 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
  78. rm -f ~/.pi/agent/prompts/s[h]are*.md
  79. ```
  80. 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:
  81. ```bash
  82. curl -fsSL https://raw.githubusercontent.com/nicobailon/visual-explainer/main/install-pi.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 113 on GitHub
  83. ```
  84. **MCP:**
  85. 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.
  86. Example package configuration:
  87. ```json
  88. {
  89. "mcpServers": {
  90. "visual-explainer": {
  91. "command": "visual-explainer-mcp"
  92. }
  93. }
  94. }
  95. ```
  96. Example checkout configuration:
  97. ```json
  98. {
  99. "mcpServers": {
  100. "visual-explainer": {
  101. "command": "node",
  102. "args": ["/absolute/path/to/visual-explainer/plugins/visual-explainer/mcp/server.mjs"]
  103. }
  104. }
  105. }
  106. ```
  107. 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.
  108. **Antigravity CLI:**
  109. 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.
  110. Global install:
  111. ```bash
  112. git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer
  113. mkdir -p ~/.gemini/antigravity-cli/skills
  114. cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.gemini/antigravity-cli/skills/visual-explainer
  115. rm -rf /tmp/visual-explainer
  116. ```
  117. PowerShell (global):
  118. ```powershell
  119. $ErrorActionPreference = 'Stop'
  120. $tmp = Join-Path $env:TEMP ("visual-explainer-" + [guid]::NewGuid().ToString())
  121. $dest = Join-Path $env:USERPROFILE ".gemini\antigravity-cli\skills\visual-explainer"
  122. $parent = Split-Path -Parent $dest
  123. $run = $null
  124. $staging = $null
  125. $backup = $null
  126. $moved = $false
  127. $attempted = $false
  128. $installed = $false
  129. New-Item -ItemType Directory -Force -Path $tmp | Out-Null
  130. try {
  131. $repo = Join-Path $tmp 'repo'
  132. git clone --depth 1 https://github.com/nicobailon/visual-explainer.git $repo
  133. if ($LASTEXITCODE -ne 0) { throw "git clone failed with exit code $LASTEXITCODE" }
  134. New-Item -ItemType Directory -Force -Path $parent | Out-Null
  135. $run = Join-Path $parent (".visual-explainer-install-" + [guid]::NewGuid().ToString())
  136. $staging = Join-Path $run 'staging'
  137. $backup = Join-Path $run 'backup'
  138. New-Item -ItemType Directory -Force -Path $run | Out-Null
  139. Copy-Item -LiteralPath (Join-Path $repo 'plugins\visual-explainer') -Destination $staging -Recurse -Force
  140. if (-not (Test-Path -LiteralPath (Join-Path $staging 'SKILL.md') -PathType Leaf)) { throw 'staged skill is incomplete' }
  141. if (Test-Path -LiteralPath $dest) { Move-Item -LiteralPath $dest -Destination $backup; $moved = $true }
  142. $attempted = $true
  143. Move-Item -LiteralPath $staging -Destination $dest
  144. $installed = $true
  145. } finally {
  146. if (-not $installed -and $attempted) {
  147. if (Test-Path -LiteralPath $dest) { Move-Item -LiteralPath $dest -Destination (Join-Path $run 'failed') -ErrorAction SilentlyContinue }
  148. if ($moved -and (Test-Path -LiteralPath $backup) -and -not (Test-Path -LiteralPath $dest)) { Move-Item -LiteralPath $backup -Destination $dest -ErrorAction SilentlyContinue }
  149. }
  150. if ($run -and ((-not (Test-Path -LiteralPath $backup)) -or $installed)) { Remove-Item -LiteralPath $run -Recurse -Force -ErrorAction SilentlyContinue }
  151. Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue
  152. }
  153. ```
  154. Workspace install:
  155. ```bash
  156. git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer
  157. mkdir -p .agents/skills
  158. cp -R /tmp/visual-explainer/plugins/visual-explainer .agents/skills/visual-explainer
  159. rm -rf /tmp/visual-explainer
  160. ```
  161. PowerShell (workspace):
  162. ```powershell
  163. $ErrorActionPreference = 'Stop'
  164. $tmp = Join-Path $env:TEMP ("visual-explainer-" + [guid]::NewGuid().ToString())
  165. $dest = ".agents\skills\visual-explainer"
  166. $parent = Split-Path -Parent $dest
  167. $run = $null
  168. $staging = $null
  169. $backup = $null
  170. $moved = $false
  171. $attempted = $false
  172. $installed = $false
  173. New-Item -ItemType Directory -Force -Path $tmp | Out-Null
  174. try {
  175. $repo = Join-Path $tmp 'repo'
  176. git clone --depth 1 https://github.com/nicobailon/visual-explainer.git $repo
  177. if ($LASTEXITCODE -ne 0) { throw "git clone failed with exit code $LASTEXITCODE" }
  178. New-Item -ItemType Directory -Force -Path $parent | Out-Null
  179. $run = Join-Path $parent (".visual-explainer-install-" + [guid]::NewGuid().ToString())
  180. $staging = Join-Path $run 'staging'
  181. $backup = Join-Path $run 'backup'
  182. New-Item -ItemType Directory -Force -Path $run | Out-Null
  183. Copy-Item -LiteralPath (Join-Path $repo 'plugins\visual-explainer') -Destination $staging -Recurse -Force
  184. if (-not (Test-Path -LiteralPath (Join-Path $staging 'SKILL.md') -PathType Leaf)) { throw 'staged skill is incomplete' }
  185. if (Test-Path -LiteralPath $dest) { Move-Item -LiteralPath $dest -Destination $backup; $moved = $true }
  186. $attempted = $true
  187. Move-Item -LiteralPath $staging -Destination $dest
  188. $installed = $true
  189. } finally {
  190. if (-not $installed -and $attempted) {
  191. if (Test-Path -LiteralPath $dest) { Move-Item -LiteralPath $dest -Destination (Join-Path $run 'failed') -ErrorAction SilentlyContinue }
  192. if ($moved -and (Test-Path -LiteralPath $backup) -and -not (Test-Path -LiteralPath $dest)) { Move-Item -LiteralPath $backup -Destination $dest -ErrorAction SilentlyContinue }
  193. }
  194. if ($run -and ((-not (Test-Path -LiteralPath $backup)) -or $installed)) { Remove-Item -LiteralPath $run -Recurse -Force -ErrorAction SilentlyContinue }
  195. Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue
  196. }
  197. ```
  198. Launch `agy` in the project and use `/skills` to confirm `visual-explainer` is discovered. Ask Antigravity to use the `visual-explainer` skill for diagrams, visual reviews, slide decks, and complex tables. Antigravity SDK projects can reuse the same `SKILL.md` content as an Agent Skill resource, but this repo does not ship a separate SDK wrapper. The bundled prompt templates remain reference markdown under `plugins/visual-explainer/commands/`; no separate Antigravity plugin adapter is included.
  199. **Codex CLI:**
  200. ```bash
  201. git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer
  202. mkdir -p ~/.codex/skills ~/.codex/prompts
  203. cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.codex/skills/visual-explainer
  204. # Optional, only if your Codex build supports prompt templates:
  205. cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.codex/prompts/
  206. rm -rf /tmp/visual-explainer
  207. ```
  208. PowerShell:
  209. ```powershell
  210. $ErrorActionPreference = 'Stop'
  211. $tmp = Join-Path $env:TEMP ("visual-explainer-" + [guid]::NewGuid().ToString())
  212. $dest = Join-Path $env:USERPROFILE ".codex\skills\visual-explainer"
  213. $parent = Split-Path -Parent $dest
  214. $promptDir = Join-Path $env:USERPROFILE ".codex\prompts"
  215. $run = $null
  216. $staging = $null
  217. $backup = $null
  218. $moved = $false
  219. $attempted = $false
  220. $installed = $false
  221. New-Item -ItemType Directory -Force -Path $tmp | Out-Null
  222. try {
  223. $repo = Join-Path $tmp 'repo'
  224. git clone --depth 1 https://github.com/nicobailon/visual-explainer.git $repo
  225. if ($LASTEXITCODE -ne 0) { throw "git clone failed with exit code $LASTEXITCODE" }
  226. New-Item -ItemType Directory -Force -Path $parent, $promptDir | Out-Null
  227. $run = Join-Path $parent (".visual-explainer-install-" + [guid]::NewGuid().ToString())
  228. $staging = Join-Path $run 'staging'
  229. $backup = Join-Path $run 'backup'
  230. New-Item -ItemType Directory -Force -Path $run | Out-Null
  231. Copy-Item -LiteralPath (Join-Path $repo 'plugins\visual-explainer') -Destination $staging -Recurse -Force
  232. if (-not (Test-Path -LiteralPath (Join-Path $staging 'SKILL.md') -PathType Leaf)) { throw 'staged skill is incomplete' }
  233. # Optional, only if your Codex build supports prompt templates:
  234. Copy-Item -Path (Join-Path $staging 'commands\*.md') -Destination $promptDir -Force
  235. if (Test-Path -LiteralPath $dest) { Move-Item -LiteralPath $dest -Destination $backup; $moved = $true }
  236. $attempted = $true
  237. Move-Item -LiteralPath $staging -Destination $dest
  238. $installed = $true
  239. } finally {
  240. if (-not $installed -and $attempted) {
  241. if (Test-Path -LiteralPath $dest) { Move-Item -LiteralPath $dest -Destination (Join-Path $run 'failed') -ErrorAction SilentlyContinue }
  242. if ($moved -and (Test-Path -LiteralPath $backup) -and -not (Test-Path -LiteralPath $dest)) { Move-Item -LiteralPath $backup -Destination $dest -ErrorAction SilentlyContinue }
  243. }
  244. if ($run -and ((-not (Test-Path -LiteralPath $backup)) -or $installed)) { Remove-Item -LiteralPath $run -Recurse -Force -ErrorAction SilentlyContinue }
  245. Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue
  246. }
  247. ```
  248. 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.
  249. **OpenCode/opencode:**
  250. ```bash
  251. git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer
  252. mkdir -p ~/.config/opencode/skill ~/.config/opencode/command
  253. cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.config/opencode/skill/visual-explainer
  254. # Optional command templates:
  255. cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.config/opencode/command/
  256. rm -rf /tmp/visual-explainer
  257. ```
  258. PowerShell:
  259. ```powershell
  260. $ErrorActionPreference = 'Stop'
  261. $tmp = Join-Path $env:TEMP ("visual-explainer-" + [guid]::NewGuid().ToString())
  262. $dest = Join-Path $env:USERPROFILE ".config\opencode\skill\visual-explainer"
  263. $parent = Split-Path -Parent $dest
  264. $promptDir = Join-Path $env:USERPROFILE ".config\opencode\command"
  265. $run = $null
  266. $staging = $null
  267. $backup = $null
  268. $moved = $false
  269. $attempted = $false
  270. $installed = $false
  271. New-Item -ItemType Directory -Force -Path $tmp | Out-Null
  272. try {
  273. $repo = Join-Path $tmp 'repo'
  274. git clone --depth 1 https://github.com/nicobailon/visual-explainer.git $repo
  275. if ($LASTEXITCODE -ne 0) { throw "git clone failed with exit code $LASTEXITCODE" }
  276. New-Item -ItemType Directory -Force -Path $parent, $promptDir | Out-Null
  277. $run = Join-Path $parent (".visual-explainer-install-" + [guid]::NewGuid().ToString())
  278. $staging = Join-Path $run 'staging'
  279. $backup = Join-Path $run 'backup'
  280. New-Item -ItemType Directory -Force -Path $run | Out-Null
  281. Copy-Item -LiteralPath (Join-Path $repo 'plugins\visual-explainer') -Destination $staging -Recurse -Force
  282. if (-not (Test-Path -LiteralPath (Join-Path $staging 'SKILL.md') -PathType Leaf)) { throw 'staged skill is incomplete' }
  283. # Optional command templates:
  284. Copy-Item -Path (Join-Path $staging 'commands\*.md') -Destination $promptDir -Force
  285. if (Test-Path -LiteralPath $dest) { Move-Item -LiteralPath $dest -Destination $backup; $moved = $true }
  286. $attempted = $true
  287. Move-Item -LiteralPath $staging -Destination $dest
  288. $installed = $true
  289. } finally {
  290. if (-not $installed -and $attempted) {
  291. if (Test-Path -LiteralPath $dest) { Move-Item -LiteralPath $dest -Destination (Join-Path $run 'failed') -ErrorAction SilentlyContinue }
  292. if ($moved -and (Test-Path -LiteralPath $backup) -and -not (Test-Path -LiteralPath $dest)) { Move-Item -LiteralPath $backup -Destination $dest -ErrorAction SilentlyContinue }
  293. }
  294. if ($run -and ((-not (Test-Path -LiteralPath $backup)) -or $installed)) { Remove-Item -LiteralPath $run -Recurse -Force -ErrorAction SilentlyContinue }
  295. Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue
  296. }
  297. ```
  298. Activate it by asking OpenCode to use the `visual-explainer` skill. Command-template behavior depends on the installed OpenCode/opencode build.
  299. **Cursor:**
  300. Cursor loads Agent Skills from `~/.cursor/skills/` globally and `.cursor/skills/` at the workspace level. Copy the canonical skill directory there and Cursor discovers it from the `name:` field in `SKILL.md`.
  301. Global install:
  302. ```bash
  303. set -euo pipefail
  304. tmp="$(mktemp -d "${TMPDIR:-/tmp}/visual-explainer.XXXXXX")"
  305. dest="$HOME/.cursor/skills/visual-explainer"
  306. parent="$(dirname "$dest")"
  307. run=''
  308. stage=''
  309. backup=''
  310. moved=0
  311. installed=0
  312. cleanup() {
  313. status=$?
  314. if [ "$status" -ne 0 ] && [ "$moved" -eq 1 ] && [ "$installed" -eq 0 ]; then
  315. if [ -e "$dest" ]; then mv -- "$dest" "$run/failed" || true; fi
  316. if [ -e "$backup" ]; then mv -- "$backup" "$dest" || true; fi
  317. fi
  318. if [ -n "$run" ] && { [ "$installed" -eq 1 ] || [ ! -e "$backup" ]; }; then
  319. rm -rf -- "$run" || true
  320. fi
  321. rm -rf -- "$tmp" || true
  322. }
  323. trap cleanup EXIT
  324. if git clone --depth 1 https://github.com/nicobailon/visual-explainer.git "$tmp/repo"; then :; else
  325. status=$?
  326. echo "git clone failed with exit code $status" >&2
  327. exit "$status"
  328. fi
  329. mkdir -p "$parent"
  330. run="$(mktemp -d "$parent/.visual-explainer-install.XXXXXX")"
  331. stage="$run/staging"
  332. backup="$run/backup"
  333. cp -R "$tmp/repo/plugins/visual-explainer" "$stage"
  334. test -f "$stage/SKILL.md"
  335. if [ -e "$dest" ]; then mv -- "$dest" "$backup"; moved=1; fi
  336. mv -- "$stage" "$dest"
  337. installed=1
  338. ```
  339. Workspace install:
  340. ```bash
  341. set -euo pipefail
  342. tmp="$(mktemp -d "${TMPDIR:-/tmp}/visual-explainer.XXXXXX")"
  343. dest=".cursor/skills/visual-explainer"
  344. parent="$(dirname "$dest")"
  345. run=''
  346. stage=''
  347. backup=''
  348. moved=0
  349. installed=0
  350. cleanup() {
  351. status=$?
  352. if [ "$status" -ne 0 ] && [ "$moved" -eq 1 ] && [ "$installed" -eq 0 ]; then
  353. if [ -e "$dest" ]; then mv -- "$dest" "$run/failed" || true; fi
  354. if [ -e "$backup" ]; then mv -- "$backup" "$dest" || true; fi
  355. fi
  356. if [ -n "$run" ] && { [ "$installed" -eq 1 ] || [ ! -e "$backup" ]; }; then
  357. rm -rf -- "$run" || true
  358. fi
  359. rm -rf -- "$tmp" || true
  360. }
  361. trap cleanup EXIT
  362. if git clone --depth 1 https://github.com/nicobailon/visual-explainer.git "$tmp/repo"; then :; else
  363. status=$?
  364. echo "git clone failed with exit code $status" >&2
  365. exit "$status"
  366. fi
  367. mkdir -p "$parent"
  368. run="$(mktemp -d "$parent/.visual-explainer-install.XXXXXX")"
  369. stage="$run/staging"
  370. backup="$run/backup"
  371. cp -R "$tmp/repo/plugins/visual-explainer" "$stage"
  372. test -f "$stage/SKILL.md"
  373. if [ -e "$dest" ]; then mv -- "$dest" "$backup"; moved=1; fi
  374. mv -- "$stage" "$dest"
  375. installed=1
  376. ```
  377. Ask Cursor to use the `visual-explainer` skill for diagrams, visual reviews, slide decks, and complex tables.
  378. Optional legacy rule: add `configs/cursor/visual-explainer.mdc` to your Cursor rules if you prefer rules-based guidance over relying on skill discovery alone.
  379. **OpenClaw:**
  380. 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.
  381. **VS Code Copilot / Copilot CLI:**
  382. Use `configs/copilot/AGENTS.md` as custom instructions or rules guidance. For VS Code, copy it into a supported workspace custom-instructions file, such as `.github/copilot-instructions.md`. For Copilot CLI, add it through the workspace instruction or rules setup supported by your installed version. Both read the canonical skill from `plugins/visual-explainer/`; this repository does not provide native Agent Skills support, a Copilot package, or a tested Copilot plugin adapter.
  383. ## Commands
  384. | Command | What it does |
  385. |---------|-------------|
  386. | `/generate-web-diagram` | Generate a figure-first page for any topic: diagrams, data, or a concept explained |
  387. | `/generate-visual-plan` | An implementation plan you answer in the page: the change drawn, a short tree of claims, decisions with suggested defaults, then one response to paste back. After the build, the same page shows what was built |
  388. | `/generate-slides` | Generate a magazine-quality slide deck |
  389. | `/generate-video` | Generate a narrated MP4 explainer, or record a walkthrough of a live web app |
  390. | `/diff-review` | Visual diff review with architecture comparison and code review |
  391. | `/plan-review` | Check a plan against the codebase: each finding shows its evidence and a fix you accept or reject in the page |
  392. | `/project-recap` | Mental model snapshot for context-switching back to a project |
  393. | `/compare` | Draw two or more options side by side, recommend one, and let you pick in the page; the pick comes back to the agent |
  394. | `/fact-check` | Verify accuracy of a document against actual code |
  395. | `/state-machine` | Draw a state machine from the code itself: the page walks every state and shows the states you forgot, the events that never fire, the dead ends, and each rule the code breaks as a path you can replay |
  396. 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.
  397. ## Slide Deck Mode
  398. Any command that produces a scrollable page supports `--slides` to generate a slide deck instead:
  399. ```
  400. /diff-review --slides
  401. /project-recap --slides 2w
  402. ```
  403. For a portable presentation file, add `--pptx` to `/generate-slides` or run the exporter after generating an HTML deck:
  404. ```bash
  405. visual-explainer-pptx ~/.agent/diagrams/my-deck.html ~/.agent/diagrams/my-deck.pptx
  406. ```
  407. PPTX export is best-effort and static. It extracts titles, text, bullets, simple tables, code blocks, and Mermaid source placeholders from `<section class="slide">` elements. It does not preserve animations, reader navigation, responsive layout, custom fonts, live Mermaid/Chart.js/SVG/canvas rendering, or JavaScript behavior. Use the HTML deck for final fidelity.
  408. https://github.com/user-attachments/assets/342d3558-5fcf-4fb2-bc03-f0dd5b9e35dc
  409. ## Themes
  410. Ask for switchable themes, or name a palette, and the page gets a picker — colored dots for the palette and `Aa` chips for the font pair, both swapping live:
  411. ```
  412. "explain this pipeline, use Gruvbox"
  413. "diagram the auth flow, let me switch themes"
  414. ```
  415. Eleven palettes ship with it: Dracula, Nord, One Dark, Catppuccin Mocha, Tokyo Night, Gruvbox Dark, Synthwave '84 (dark) and Solarized Light, GitHub Light, Catppuccin Latte, Gruvbox Light. The font chips offer the pairs the skill already recommends. Diagrams draw with the page tokens, so they always match the active selection. Set `theme:` or `font:` in `visual-explainer.config.md` to choose what loads first. Claude Code users can keep personal overrides in `.claude/visual-explainer.local.md`; shared project defaults should use the harness-neutral file.
  416. The picker is opt-in. Pages that don't ask for one still get a single palette and font pair chosen to fit the content.
  417. ## How It Works
  418. ```
  419. .claude-plugin/
  420. ├── plugin.json ← marketplace identity
  421. └── marketplace.json ← plugin catalog
  422. plugins/
  423. └── visual-explainer/
  424. ├── .claude-plugin/
  425. │ └── plugin.json ← plugin manifest
  426. ├── SKILL.md ← workflow + design principles
  427. ├── extension.ts ← Pi native tool
  428. ├── commands/ ← slash commands
  429. ├── kit/ ← shared page CSS and script, renderer, page check, vendored Pele for Mermaid
  430. ├── mcp/ ← local stdio MCP server
  431. ├── pptx/ ← best-effort static PPTX exporter
  432. ├── video/ ← MP4 renderer for video decks
  433. ├── references/ ← read on demand
  434. │ ├── style-guide.md (four registers, layout, figure rules, topic motif, your own CSS)
  435. │ ├── kit.md (kit marker, parts, data tags, <ve-flow>)
  436. │ ├── diagrams.md (hand-drawn SVG kit, dimensions, callouts, linked highlighting)
  437. │ ├── motion.md (stepper, scene player, replay, live figures, three.js)
  438. │ ├── slides.md (deck budget, engine contract, delivery check)
  439. │ ├── video.md (video deck contract, script and look rules, voice clips, tutorials)
  440. │ ├── extras.md (Mermaid, images, older recipes)
  441. │ └── themes.md (11 palettes + runtime theme/font picker)
  442. └── templates/
  443. ├── page.html (figure-first reference page, Instrument register)
  444. └── slide-deck.html (slide engine + reference deck)
  445. ```
  446. **Output:** `~/.agent/diagrams/filename.html` by default (native Pi can configure the directory above) → opens in browser. The agent writes a short source, `filename.src.html`, that links the shared kit; the renderer builds the page from it and keeps it for small revisions. When Chrome and `playwright-core` are available, the renderer also checks the page in a browser and writes `filename.sheet.png`, a contact sheet of the first screen, the figures, and every step, which the agent looks at instead of taking its own screenshots. On request, the agent also writes `filename.md` as an AI-readable companion; it asks before replacing one. In Pi, agents can offer `visual_explainer` `prepare` after a substantial plan, architecture, diff, or implementation, then `render` to write and open the page. MCP hosts use the `visual-explainer-mcp` stdio server, whose render tool defaults to `open: false`.
  447. Pages are figure-first: the first screen shows the answer as a picture and one sentence. Each page uses one of four registers (Instrument for reviews and metrics, Blueprint for architecture, Paper for concepts, Editorial for recaps and decks), each with fixed fonts, a contrast-checked palette, and one shared spacing and type scale. Terms in the text and parts of the figure light up together on hover. Diagrams are hand-drawn inline SVG, so they match the page and can step through a process. Mermaid is used only when you ask for it. Tables carry status chips, metrics get bars and sparklines, and prose follows a Simplified Technical English style.
  448. ## Limitations
  449. - Generated HTML is portable and self-contained, but auto-opening depends on the harness, browser access, and sandbox rules.
  450. - PPTX export is a static best-effort handoff. The HTML deck remains the source of truth for full visual fidelity.
  451. - Output defaults to `~/.agent/diagrams/`. Native Pi supports `visualExplainer.outputDir`; Pi and MCP accept a nonblank `VISUAL_EXPLAINER_OUTPUT_DIR` override. Other harnesses can follow a user-supplied path.
  452. - Results vary by model capability.
  453. ## Credits
  454. Borrows ideas from [Anthropic's frontend-design skill](https://github.com/anthropics/skills) and [interface-design](https://github.com/Dammyjay93/interface-design).
  455. Mermaid diagrams are drawn by [Pele](https://github.com/obsidianmd/pele) from Obsidian (MIT), bundled in `kit/vendor/`.
  456. ## License
  457. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.