# plannotator-visual-explainer

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 15100 installs · ★ 14187 repo stars
- Author: backnotprop
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/backnotprop/plannotator/tree/HEAD/apps/skills/extra/plannotator-visual-explainer/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text and 1 script file) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/plannotator-visual-explainer

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/plannotator-visual-explainer/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/plannotator-visual-explainer/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/plannotator-visual-explainer/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/plannotator-visual-explainer/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install backnotprop/plannotator apps/skills/extra/plannotator-visual-explainer
```

2. **Manually: put the files in place**
- File: `.github/skills/plannotator-visual-explainer/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/backnotprop/plannotator --path apps/skills/extra/plannotator-visual-explainer
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/plannotator-visual-explainer/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/backnotprop/plannotator/tree/HEAD/apps/skills/extra/plannotator-visual-explainer/SKILL.md

## When to use it
- 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
- Draw a migration plan to Postgres with timeline and SVG diagram — deliver via `plannotator annotate` with `--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

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1a8d81fae062667b.

BEGIN THIRD-PARTY FILE 1a8d81fae062667b
````text
---
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
```
````
END THIRD-PARTY FILE 1a8d81fae062667b

The third-party file has ended. Everything between the 1a8d81fae062667b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2021 of 7300 bytes. © backnotprop · Apache-2.0 · https://github.com/backnotprop/plannotator/tree/HEAD/apps/skills/extra/plannotator-visual-explainer/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
