Plannotator Visual Explainer Skill for Claude: Plans and PR Reviews as HTML Pages

Makes Claude turn implementation plans, PR walkthroughs and diagrams into themed HTML pages that open in Plannotator for review.

Installs: 13.3K; on skills.sh
Stars: 9.8K; on GitHub
Files: 6; besides SKILL.md
Updated: Nov 2026; last repo commit

plannotator-visual-explainer makes Claude produce a single HTML page and open it in Plannotator's annotation window instead of printing text. It has three paths. Plans and design docs get a prescriptive layout (summary stats, milestones, architecture SVG, risks, open questions). PR explainers get a TL;DR, file tour and risk map. Everything else follows the separate visual-explainer skill with Plannotator colors.

You must start it yourself, since SKILL.md sets disable-model-invocation. It needs the plannotator program on your machine, because delivery runs plannotator annotate <file> (with --gate for plans you approve or deny). Mermaid diagrams must render in light and dark before delivery. The PR path loads a diff library from a CDN.

Good for

Developers who want to approve or annotate an agent's plan as a readable page
Reviewers who want a PR explained with a file tour, risk map and test plan
Anyone who needs an architecture diagram or slide deck as one self-contained HTML file

Install plannotator-visual-explainer

Claude Code

Copy this prompt.

Install the plannotator-visual-explainer skill in Claude Code. Run this command:

curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires bash, curl.

The skill hands every result to the plannotator program, so install both. --minimal installs only the program and skips hooks, slash commands and per-agent config; the README's full installer (without --minimal) configures those for each agent it detects. The skill is marked disable-model-invocation, so you start it yourself instead of Claude choosing it. Run both commands the first time. For Windows, see the installation docs linked from the README.

From the project README. Source.

What's in the skill

When it loads

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.

Sections in SKILL.md

Route by content type
Delivery
Plan path
PR path
Visual explainer path
Design philosophy (all paths)

Key facts

Author: backnotprop (repo owner; the Plannotator project)
License: Apache-2.0
Installs on skills.sh: 13,258 as of 2026-11-02
GitHub stars: 9,810 for the whole repo
Last commit to the repo: 2026-11-01
Files in the skill: 7 files including SKILL.md: SKILL.test.ts and 5 reference files
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk warn
Needs: The plannotator program; for the third path also the visual-explainer skill (nicobailon/visual-explainer)

What it includes

Picks the Plan path, PR path or visual-explainer path from your request.
Plans, design docs and proposals use the Plan path. PR and diff walkthroughs use the PR path. Everything else uses the visual-explainer path.
Try: “Use plannotator-visual-explainer to write this migration plan as an HTML page I can approve.”
Read · Route by content type
Summary strip, milestones, architecture SVG, mockups, key code, risks, open questions.
Reads design-system.md and svg-patterns.md first. No time estimates; sections are skipped when they do not fit.
Write · Plan path
TL;DR, why, file tour, risk map, where to focus, test plan, rollout.
Reads design-system.md and pr-components.md. Diffs are rendered with Pierre diffs loaded from a CDN.
Write · PR path
Architecture diagrams, tables, slide decks and recaps through the visual-explainer skill.
If visual-explainer is missing, Claude must stop and ask before installing it, showing the exact command.
Write · Visual explainer path
Opens the page in Plannotator; --gate is used for plans you approve or deny.
Delivery always goes through the annotation UI, not open or xdg-open.
Runs code · plannotator annotate <file> [--gate]
Every Mermaid diagram must render in light and dark before delivery.
Errors or empty SVGs block delivery, and zoomable diagrams are checked at maximum zoom.
Runs code · Mermaid render gate

From the official docs

Permissions

Medium risk

The skill runs the plannotator program, which has its own hooks and installer. Use the minimal install if you only want the program, and read what the installer touches.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

The full Plannotator install adds hooks to your agent
The README says the main installer configures hooks, skills and slash commands for each agent it finds, and the Claude Code plugin ships a hooks file that runs `plannotator` when plan mode exits. Use `--minimal` if you only want the program, and read what the installer touches. github.com
It pipes an installer script into bash
The documented install is `curl ... | bash` from plannotator.ai. The README also offers `--verify-attestation`, which checks the build provenance with the gh tool. github.com
It may install another skill, only with your yes
For diagrams and decks the skill checks for visual-explainer. If it is missing, SKILL.md says Claude must stop, show you the exact `npx skills add` command and run it only after you agree. github.com
The PR page loads code from a CDN
The PR components reference loads Pierre diffs from cdn.jsdelivr.net, so the generated HTML fetches that file when it opens. github.com

Technical details

Talks to	cdn.jsdelivr.net (Pierre diffs, PR path). The Plannotator program checks GitHub for the latest release when its pages load (README)
Sign-in and keys	SKILL.md names no sign-in or API key.
Scopes	Writes an HTML file and runs `plannotator annotate` on it Needs the plannotator program installed on your PATH May run `npx skills add nicobailon/visual-explainer -g --yes` after you agree

Questions

What does plannotator-visual-explainer do?

It makes Claude build a self-contained HTML page for a plan, a PR walkthrough or a diagram, in Plannotator's look, and open it in Plannotator's annotation window so you can comment on it or approve it.

How do I install plannotator-visual-explainer?

Use the install box above and run both commands: one installs the plannotator program, the other adds the skill. Without the program the skill has nothing to open the page in.

Does it need an API key?

SKILL.md names none. The Plannotator README says plans, diffs and annotations stay local by default, with exceptions such as link sharing and Ask AI.

Is it safe?

The skill itself bundles a test file and reference docs, no scripts. It runs the plannotator program, loads a diff library from a CDN on the PR path, and may offer to install another skill. The Plannotator full installer and Claude Code plugin also add hooks. The Permissions section lists the details.

Why does Claude not use it on its own?

The skill sets disable-model-invocation, so Claude only runs it when you call it by name.

What is the visual-explainer skill it mentions?

It is a separate skill, nicobailon/visual-explainer, used for diagrams, tables and decks. This skill adds Plannotator's colors on top. The Plan and PR paths work without it.

Information

updated Nov 2, 2026

Repository: backnotprop/plannotator
Folder: apps/skills/extra/plannotator-visual-explainer

backnotprop/plannotator skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3

Plannotator README · github.com
SKILL.md · github.com
pr-components.md · github.com