simple-explainer

Three agent skills that turn a topic into a clear explanation — the words, the figures, and the page — under one design language.

You ask your agent a question. One skill answers it in plain, well-structured text. A second draws the parts of the idea that gain from a picture. A third mounts the finished text as a web page you can keep and share. Each skill works alone. Together, they take you from "explain X" to a finished, shareable page.

No pipeline to run, no templates to fill. You talk; the skills do the rest.

The idea

   ┌─────────────────────────────────┐
   │  THE WRITING                    │
   │  one plain, well-written        │
   │  explanation (markdown)         │
   │  it stands for itself           │
   └───────┬────────────────┬────────┘
           │ on request     │ when asked, read it like a
           ▼                ▼ reader would — no special format
   ┌────────────┐   ┌────────────┐
   │  DIAGRAMS  │   │  WEBPAGE   │      (both implemented)
   └────────────┘   └────────────┘
          both obey ──►  DESIGN LANGUAGE  (design/ — one copy)

What you get

01 · explainer-writing — the words

One plain markdown explanation, right in the chat — no files, no frontmatter, no ceremony. The response is the product. Sentences stay short. The actor is named. One word keeps one meaning. The style target is "80% of the way to Simplified Technical English", softened for explainers — a busy non-native speaker understands every sentence on the first read.

Try: "Explain how a drip coffee machine works, in simplified technical English."

More: the two golden examples · docs/explainer-writing.md

02 · explainer-diagrams — the figures

Explanatory SVG diagrams — one self-contained .svg per figure, hand-authored in the "Paper Circuit" design language: warm paper, confident flat color, circuit-trace connections, giant type against whisper captions. A diagram is a second argument for the idea: remove all the text, and the structure alone must still communicate. The skill also tells you when not to draw — zero diagrams is a valid outcome.

Try: "Draw the main parts of a bicycle pump."

More: five example diagrams in skills/explainer-diagrams/examples/ — including an image classifier's training loop and forward pass · docs/explainer-diagrams.md

03 · explainer-webpage — the page

Desktop, 1440 px	Mobile, 390 px

The finished explanation, mounted as one self-contained HTML page. Hand-authored vanilla HTML, CSS, and JS. Fonts embedded. Zero external requests. It renders straight from file:// — download the file, double-click it, it works. The text is mounted, never rewritten, and the layout is checked at desktop and mobile widths: nothing clips, nothing overflows.

Try: "Make a webpage of this explanation."

Open the real thing: how-a-bicycle-pump-works.html — a single file, no server needed. Two more examples in skills/explainer-webpage/examples/ · docs/explainer-webpage.md

Install

The 30-second version — tell your agent

Paste this into your agent (Claude Code, Codex, Cursor, and friends):

Install the agent skills from https://github.com/zushicat/simple-explainer.
Follow the install instructions in the repo's AGENTS.md.

That is the whole instruction. The repo ships an AGENTS.md written for agents: your agent reads it and installs for every environment it can detect — the skills go into ~/.agents/skills/, the cross-agent location, and when it detects Claude Code it adds the plugin on top. Then it verifies and reports what went where. Claude Code also finds a CLAUDE.md that points to the same file.

Prefer to do it yourself? Three routes.

Route A — Claude Code plugin

The repo is a plugin and its own marketplace. One add, one install — updates arrive when the repo ships:

claude plugin marketplace add zushicat/simple-explainer
claude plugin install simple-explainer@simple-explainer

Inside a session, the same steps are /plugin marketplace add zushicat/simple-explainer and /plugin install simple-explainer@simple-explainer. Working from a local checkout? Run claude plugin marketplace add /path/to/simple-explainer, or point straight at it with claude --plugin-dir /path/to/simple-explainer.

The plugin installs into ~/.claude/plugins/cache/… — that is the correct place for a plugin: Claude Code manages it there and updates it through the marketplace. This route covers Claude Code only — it does not make the skills visible to other agents, and it does not touch ~/.claude/skills/. Do not add a manual copy there on top of the plugin, or Claude Code loads every skill twice.

Route B — skills CLI (any agent)

npx skills@latest add zushicat/simple-explainer

The installer asks which skills you want and writes them into your agents' skills directories as ordinary files you own — edit them freely, pull updates when you want them.

Route C — manual copy (works everywhere, needs nothing)

git clone --depth 1 https://github.com/zushicat/simple-explainer.git
cd simple-explainer
mkdir -p ~/.agents/skills
cp -R skills/explainer-writing  ~/.agents/skills/
cp -R skills/explainer-diagrams ~/.agents/skills/
cp -R skills/explainer-webpage  ~/.agents/skills/

This is the baseline install, and the one that works everywhere: agents and harnesses that follow the cross-agent .agents/skills convention read ~/.agents/skills/ in every project. Claude Code is the exception — it reads the plugin (Route A) or ~/.claude/skills/, not ~/.agents/skills/. For Claude Code without the plugin, copy into ~/.claude/skills/ instead (per-project: .claude/skills/ inside the project) — but never both. Symlink instead of copy if you plan to pull updates with git pull. Each skill folder is standalone: copy one, two, or all three — its rules travel with it.

Check it worked

Start a new session and ask your agent: "Which skills do you have installed?" — the three explainer-* skills should be listed. Where to look: in Claude Code they arrive through the plugin; everywhere else, check for the explainer-* folders in ~/.agents/skills/. Then try one of the prompts above.

Which skill runs when

You say	You get
"Explain X" · "simplify this draft" · "make it stricter"	one plain markdown explanation, in the chat
"Draw X" · "the main parts of X" · "how X works as a picture"	one self-contained SVG per figure
"Make a webpage of this" · "add an accordion"	one self-contained HTML page

The three skills stay out of each other's way. Writing owns the words. Diagrams own the figures. Webpage mounts both, verbatim. None edits another's output.

What's in the box

design/          the "Paper Circuit" design language — guide, tokens, specimen, fonts (frozen v2.0.0, one copy)
skills/          the three skills — SKILL.md + references/ + examples/ each
docs/            one detailed page per skill — start here
.agents/skills/  three symlinks to skills/ — project-scope discovery, see below

The similar-looking directories have different jobs:

Directory	Job
skills/ — in this repo	the source of truth. Every install route reads from here.
.agents/skills/ — in this repo	three symlinks to skills/. An agent opened inside this repo discovers the skills here, with no install step. No install route reads it.
~/.agents/skills/ — on your machine	the home-scope target that Route C copies into. Skills here are available in every project.

Detailed, user-facing docs: writing · diagrams · webpage

For maintainers: the decision record — every design decision and its reasoning — lives in plans/ in your working copy; it is kept out of the published repo.

This README follows the same plain, controlled-English style the writing skill targets.