plannotator-visual-explainer — Claude Code skill: HTML visualizations
plannotator-visual-explainer is a Claude Code skill that creates HTML visualizations of plans, PR explainers, architecture diagrams, and slide decks in Plannotator's dark theme.
Apache-2.0 15,100 installs ★ 14,187 updated 2026-10-25
npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a claude-codeWhat plannotator-visual-explainer does
The skill builds standalone HTML documents with fixed Plannotator typography (serif for headings, mono for labels), palette, and component patterns. Implementation plans and design docs get vertical timelines without time estimates, inline SVG with highlighted new components, and risk tables with three severity tiers. PR explainers get a meta strip with file count and line stats, two-column before/after comparison, file cards with NEW/MOD/DEL badges, and syntax-highlighted diffs via Pierre.
Everything else (architecture diagrams, data tables, slide decks) delegates to visual-explainer with Plannotator token overrides. Mermaid diagrams require rendering in both light and dark palettes before delivery: an exception, empty SVG, or aria-roledescription="error" blocks the output. Zoomable diagrams need legible captions at maximum zoom and all pan extremes.
Delivery always goes through plannotator annotate <file> — no open or xdg-open. Plans and proposals get the --gate flag for approval.
What it helps with
- build an implementation plan with timeline, SVG diagram, and risk table
- visualize a PR for reviewers: file map, diff blocks, focus zones
- generate an architecture diagram or slide deck with Plannotator theme
- render Mermaid in light and dark palettes with error checks before delivery
- create HTML UI mockups directly in the document without descriptions
Example prompts for the agent
- Draw a migration plan to Postgres with timeline and SVG diagram — deliver via
plannotator annotatewith--gate - Make a PR explainer: meta strip, before/after comparison, file cards with status and risk map
- Build an architecture diagram with Plannotator theme and zoom controls — check both Mermaid renders before opening
How to install plannotator-visual-explainer
1Skills CLI (Vercel)
npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a claude-code2Manually: put the files in place
~/.claude/skills/plannotator-visual-explainer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/plannotator-visual-explainer/
1Skills CLI (Vercel)
npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a codex2Manually: put the files in place
.agents/skills/plannotator-visual-explainer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a cursor2Manually: put the files in place
.cursor/skills/plannotator-visual-explainer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install backnotprop/plannotator apps/skills/extra/plannotator-visual-explainer2Manually: put the files in place
.github/skills/plannotator-visual-explainer/SKILL.md1Skills CLI (Vercel)
npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a gemini-cli2Platform CLI
gemini skills install https://github.com/backnotprop/plannotator --path apps/skills/extra/plannotator-visual-explainerManually: put the files in place
.devin/skills/plannotator-visual-explainer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about plannotator-visual-explainer
How to install plannotator-visual-explainer in Claude Code?
Run npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a claude-code, then check ~/.claude/skills/plannotator-visual-explainer/SKILL.md.
What does plannotator-visual-explainer do?
Generates HTML visualizations of plans, PR explainers, and architecture diagrams with Plannotator theme. Plans get timelines and SVG diagrams, PRs get file cards with diff blocks, everything else delegates to visual-explainer with palette override.
What is the difference between the plan path and the PR path?
The plan path reads design-system.md and svg-patterns.md, builds timelines without time estimates, risk tables, and inline SVG. The PR path reads pr-components.md, draws a meta strip with line counts, file cards with NEW/MOD/DEL status, and diff blocks via Pierre.
Source text
SKILL.md · Apache-2.0
---
name: plannotator-visual-explainer
disable-model-invocation: true
description: >
Generate self-contained HTML visualizations with Plannotator theming. Use for implementation
plans, PR explainers, architecture diagrams, data tables, slide decks, and any visual
explanation of technical concepts. Plans and PR explainers follow Plannotator's prescriptive
approach; all other visual content delegates to nicobailon/visual-explainer.
---
# Plannotator Visual Explainer
Three paths depending on content type. Each has its own references and structure.
## Route by content type
**Implementation plan, design doc, or proposal** → Follow the [Plan path](#plan-path). Read `references/design-system.md` and `references/svg-patterns.md`. Prescriptive structure.
**PR explainer, diff review, or code change walkthrough** → Follow the [PR path](#pr-path). Read `references/design-system.md` and `references/pr-components.md`. Prescriptive structure.
**Everything else** (architecture diagrams, data tables, slide decks, project recaps, general visual explanations) → Follow the [Visual explainer path](#visual-explainer-path). Delegates to nicobailon/visual-explainer with Plannotator theme tokens.
## Delivery
Always deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.
For any deliverable that uses Mermaid, render every diagram with Mermaid 12 in both the light
and dark palettes before opening the annotation UI. Rendering is a hard gate: an exception,
empty SVG, or error output such as `aria-roledescription="error"` or `Syntax error in text`
means the explainer is not deliverable. Fix the diagram or theme configuration and rerun both
palettes until every SVG passes.
For zoomable diagram shells, additionally zoom to the maximum and pan to all extremes in both palettes before delivering: the figure caption must stay fully legible throughout (see `references/diagram-shell.md`).
**Plans/proposals** (user should approve/deny):
```bash
plannotator annotate <file> --gate
```
**Everything else** (informational):
```bash
plannotator annotate <file>
```
---
## Plan path
For implementation plans, design docs, feature specs, migration guides, and proposals.
**Before generating, read:**
1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns
2. `references/svg-patterns.md` — inline SVG building blocks for architecture diagrams, flowcharts, data flow
**Document structure (in order, pick what fits):**
1. **Header** — eyebrow label (mono, uppercase), title (serif, large), prompt box (the original brief)
2. **Summary strip** — 3-5 stat cards showing key numbers at a glance (components, endpoints, tables, etc.)
3. **Milestones / timeline** — vertical timeline showing phases without time estimates. Phases show sequence and dependencies, not duration.
4. **Architecture / data flow** — inline SVG diagram. Use for 3+ interacting components. Highlighted boxes for new components, dashed arrows for async paths.
5. **Mockups** — build UI mockups in HTML/CSS directly, not as descriptions
6. **Key code** — dark-theme code blocks with syntax highlighting. Only architecturally significant interfaces/schemas — not every function.
7. **Risks & mitigations** — table with severity badges (HIGH/MED/LOW)
8. **Open questions** — callout cards with decision owner ("Decide with: backend team")
Not every plan needs every section. Skip what doesn't serve the content. Never include time estimates, boilerplate sections, or exhaustive file lists.
**Adapt to the task:** Backend → lead with data flow. Frontend → lead with mockups. Refactoring → lead with before/after diagrams. Infrastructure → lead with architecture.
**Quality bar:** The plan answers "what, why, and how" within 30 seconds of reading. Whitespace is a feature — one idea per viewport.
---
## PR path
For PR walkthroughs, diff reviews, code change explainers, and reviewer guides.
**Before generating, read:**
1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns
2. `references/pr-components.md` — diff rendering, review comment bubbles, risk chips, file cards, before/after panels
**Document structure (in order, pick what fits):**
1. **Header** — PR title, meta strip (file count, +/- lines, branch, author)
2. **TL;DR** — bordered card with primary accent left border. 2-3 sentences. Readers who see nothing else should get the gist.
3. **Why** — motivation and before/after comparison (two-column grid)
4. **File tour** — collapsible cards per file. Each has: file path + badge (NEW/MOD/DEL) + line stats, a "why" paragraph, and important diff hunks. High-risk files expanded, safe files collapsed.
5. **Risk map** — visual chips showing which files need careful review vs. which are mechanical. Three tiers: attention (destructive), medium (warning), safe (success).
6. **Where to focus** — numbered callout cards. Each names a file/function and describes the concern.
7. **Test plan** — checkbox-style verification checklist
8. **Rollout** (if applicable) — phased deployment with feature flags
Use Pierre diffs via CDN for syntax-highlighted inline diffs — see `references/pr-components.md` for the pattern.
---
## Visual explainer path
For architecture diagrams, data tables, slide decks, project recaps, comparisons, and any other visual explanation.
**Before generating:**
1. Ensure `visual-explainer` is installed:
- Check: `~/.claude/skills/visual-explainer/SKILL.md` or `~/.agents/skills/visual-explainer/SKILL.md`
- If not found: do not install it on your own. Stop and ask the person whether to install it, showing the exact command:
`npx skills add nicobailon/visual-explainer -g --yes`
Run it only after they agree (their yes is the consent; without `--yes` the installer waits for input your shell can't give). They can also run the command themselves if they prefer. If they decline, say this path needs visual-explainer and stop. The Plan and PR paths do not need it and work without it.
2. Read visual-explainer's `SKILL.md` (workflow, diagram types, anti-slop rules)
3. Read the relevant visual-explainer references and templates for your content type
4. Read `references/theme-override.md` — Plannotator tokens replacing Nico's palettes
5. For zoomable Mermaid diagrams with controls and a caption: read `references/diagram-shell.md` and copy its shell — do not hand-roll viewport, canvas, or caption markup
Follow visual-explainer's structure, component classes (`.ve-card`, `.kpi-card`, `.pipeline`), and anti-slop rules. Overrides are the color/typography layer — Plannotator tokens instead of Nico's custom palettes — plus the zoomable diagram shell in `references/diagram-shell.md` when the deliverable has one.
---
## Design philosophy (all paths)
- **Whitespace is a feature.** Generous padding, large section gaps. If cramped, add space — don't shrink text.
- **One idea per viewport.** Hero section, then diagram, then detail grid — not all crammed together.
- **Show, don't describe.** A timeline shows sequencing. A diagram shows relationships. A code block shows the interface.
- **No time estimates.** Timelines show phases and dependencies. Never attach hour/day estimates.
© backnotprop · Apache-2.0 · backnotprop/plannotator