SkillHub

Skills backnotprop plannotator

plannotator-visual-explainer

Use it when:
You'd rather review a plan, a pull request or a technical explanation as a designed page than as Markdown.
It does:
Picks a path by content: its own fixed structure for plans and for PR explainers, or nicobailon's visual-explainer skill for anything else.
You get:
A self-contained HTML file in Plannotator's theme, opened in its annotation UI; plans open with an approve-or-deny gate.
Plans can include:
Key numbers, phases without time estimates, an SVG architecture diagram, UI mockups, risks with severity badges and open questions.
Needs:
The Plannotator CLI; the general path also needs visual-explainer, which it installs only if you agree.
Runs:
Only when you call it.

Needs the Plannotator CLI to show its pages.

TL;DR

One of Plannotator's extra skills. Plannotator is a local, browser-based review surface where you mark up an agent's plans, documents and diffs and send the feedback back to it. The plan path adapts its lead section to the task: data flow for backend work, mockups for frontend, before-and-after diagrams for refactoring. A PR explainer has a TL;DR card, why the change was made, a tour of each file with its key diff hunks, a risk map separating files that need careful review from mechanical ones, where to focus, a test plan and, if relevant, a rollout. Everything else, such as architecture diagrams, data tables, slide decks and project recaps, follows visual-explainer's structure and anti-slop rules with Plannotator's colors and fonts swapped in. Any Mermaid diagram must render cleanly in both light and dark palettes before the page is delivered. Across all paths: generous whitespace, one idea per screen, show rather than describe.

Summarizes the skill at a35cc47.

npx skills add https://github.com/backnotprop/plannotator --skill plannotator-visual-explainer

skills.sh pageSource on GitHubAll skills from backnotprop/plannotator

Total Downloads
13,800 on skills.sh, Nov 9, 2026
Repo stars
9,916 backnotprop/plannotator
First seen
May 12, 2026 on skills.sh
Weekly Downloads
527
-11% over the 8 weeks to Nov 9
Weekly values
Week toInstalls
Sep 21593
Sep 28641
Oct 5647
Oct 12862
Oct 19762
Oct 26761
Nov 2757
Nov 9527
Category
category:planningcategory:sciencecategory:software-engineering

Make the agent question you and write the plan down before it writes code.

Research reproduction, financial data, charts and diagrams.

Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type
type:workflow

A multi-step process the agent follows: interview, debug, run a TDD loop, review.
Effect
effect:local

Its own steps create or change files, git state or local tools.
Needs
needs:cli

A specific command-line tool or desktop app must be installed, such as gh, agent-browser, LibreOffice, Obsidian or a vendor CLI.
Publisher
by:official

A verified publisher on skills.sh, or the company or maintainer behind the product the skill operates.
Topics
planningcode-reviewdiagrams
Stack
stack:plannotator

SKILL.md

From backnotprop/plannotator at a35cc47. Checked daily, last changed Nov 6, 2026.

Frontmatter
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. Read references/design-system.md and references/svg-patterns.md. Prescriptive structure.

PR explainer, diff review, or code change walkthrough → Follow the 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. 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):

plannotator annotate <file> --gate

Everything else (informational):

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.