Explainer Kit agent skill

Lets coding agents (Claude Code, Codex, Cursor and others) find kit illustrations by meaning and add them to your pages, decks and docs.

Latest version: 1.4.3 (2026-11-05)

Get started

The simplest way: share this page’s link with your coding agent and ask it to install the Explainer Kit skill. It will find everything it needs below. For example, say:

Install the Sketchplanations Explainer Kit skill from https://sketchplanations.com/kit/skill

Your access token

Bought the kit? Sign in and come back to this page to get the token your agent needs.

Then try it

Start a new session and ask for illustrations in plain words. For example:

“Please use the Sketchplanations Explainer Kit skill to improve this page with illustrations.”
“Use the Explainer Kit skill to find an illustration for ‘giving feedback’ and add it to the hero section.”
“Add Explainer Kit illustrations to my slides, one for each key idea.”

I used this exact prompt here:

“Please use the explainer kit skill to improve this skill page.”

Install or update manually

Run this once. For Claude Code it installs for every project; for Codex use ~/.agents/skills instead of ~/.claude/skills. Then start a new session.

curl -fsSL https://sketchplanations.com/kit/skill/sketchplanations-explainer-kit.zip -o /tmp/sketchplanations-explainer-kit.zip
mkdir -p ~/.claude/skills
unzip -oq /tmp/sketchplanations-explainer-kit.zip -d ~/.claude/skills

Installed version 1.1.0 or later can check and update itself:

node ~/.claude/skills/sketchplanations-explainer-kit/scripts/kit.mjs update --check
node ~/.claude/skills/sketchplanations-explainer-kit/scripts/kit.mjs update

For agents

The latest version, download link and checksum are in a small manifest: https://sketchplanations.com/kit/skill/latest.json. Compare its version with the metadata.version in the installed SKILL.md. If the manifest is newer, download zip, check sha256, and unzip over the installed folder.

Changelog

What’s new in 1.4.3 (2026-11-05)

- A required update: older versions are told to update before doing anything else. They stop at once, as 1.4.1 and later do. Step 0 now says the check is the first action, before reading the user's page or any other file, since reading a large file first is wasted work when the update is required.
- SKILL.md is shorter and says each thing once. "Keeping the skill current" and "The shape of every job" are folded into step 0 and a short overview, and the repeated "show the options" and "don't wait" lines are cut back to step 4.
- Less shouting: most bold "always" and "failure" wording is plain, and the reasons (users can't judge an id, clients cut text before a tool call) carry the instruction. Behaviour is unchanged: version check first, options and at least two alternatives before placing, the caption order, and no placing when images weren't asked for.
- An optional update (not a required one) is now mentioned at the end of the job, after the work is done, not straight away.

Earlier versions

1.4.2 (2026-11-05)

- `sheet` now prints a caption draft under the file path: an intro line, then for each spot a bold heading with a Selected bullet and an Alternatives bullet (ids in backticks, a few words each from the catalogue), ending with **View Selection and Alternatives**. The agent pastes it, names the page in the intro and trims long descriptions, instead of writing the caption by hand each time. `--for "<what it is for>"` fills the first sentence ("Here are the options for the No matches state on search results."), so the opening line is consistent.
- An optional update: nothing breaks for installs on 1.4.1.

1.4.1 (2026-11-05)

- New step 0: before any other work, run `update --check`. If the update is required, the agent stops at once and tells the user, instead of reading files and planning first and only hitting the "no longer supported" error later. If it isn't required, the agent works as before and mentions an optional update at the end.
- `update --check` now prints "UPDATE REQUIRED" (and tells the agent to stop and ask) when the installed version is below the site's minimum, using `minVersion` from the manifest.
- The "no longer supported" error now tells the agent to stop, do no other work, and ask the user whether to update.

1.4.0 (2026-11-05)

- "Show the options" is now its own numbered step (4), straight after choosing and before fetching. It is unconditional, even for a single image: send one contact sheet of the selected option plus at least two alternatives, each described in words with its id. Previously this was a sub-section of "Choose" that agents treated as optional.
- The step doesn't block placement. After sending the sheet the agent carries on in the same turn: fetch, place and verify the selected option. The user looks while the work happens and names an id to swap, with no re-search.
- `sheet` takes ids alone and pulls thumbnails from the catalogue, so it runs straight after choosing, before any `fetch`.
- "Report back" has a self-check: no sheet or links sent before placing means the step was skipped, so do it now.
- The written list of options (selected option, alternatives in words, with ids) now goes in the contact sheet's caption and is repeated in the final report. Clients cut text written just before a tool call down to a one-line summary, so a separate list message was lost. Nothing about placing goes in the caption. The sheet file is named `selection-and-alternatives.html`.
- The contact sheet now shows the first id in each group large under "Selected", with the others in a row under "Alternatives". It shows images only, with no ids or descriptions under them; those go in the caption. Wording is "Selected" and "Alternatives" throughout, not "pick" or "#1". The caption says the images are in the contact sheet below, and is kept short: one intro line, a bold heading per spot with a Selected bullet and an Alternatives bullet (ids in backticks, a few words each, no parentheses), then a bold "View Selection and Alternatives" line directly above the card so the card is easy to find.
- A "Skill update available" note now means: run `update --check`, summarise what changed, and ask the user before continuing.

1.3.0 (2026-10-21)

- The kit can now be customers-only. If a download is refused (HTTP 401), the script says "The Explainer Kit is now for customers. See sketchplanations.com/kit." instead of a bare `HTTP 401`. While the catalogue says access is required, searching and browsing still work and each run prints the same note.
- The site can now require a minimum skill version. Below it, the script stops with "This version of the skill … is no longer supported" and says to run `update`; `update` itself always works. This and later versions can be forced to update this way.
- Customers can set `EXPLAINER_KIT_TOKEN` (or save it in `~/.config/explainer-kit/token`). The script sends it only to the host the catalogue comes from.

1.2.2 (2026-10-21)

- Showing an illustration in context (a mockup around a button or page layout) now says to build one self-contained HTML file with base64-embedded images. A file sent on its own can't load sibling PNGs, so relative `<img>` paths showed empty boxes.

1.2.1 (2026-10-16)

- Whenever the skill places an illustration, its reply must now say which one it chose and why, describe the other good fits in words, show them on a contact sheet (or links), and offer to swap. Only real alternatives are listed: if there is one sensible match or none, it says so rather than padding. Only named asset ids or "just pick" / "don't ask" skip this.
- The report step says to admit it and show the alternatives if something was placed without them.

1.2.0 (2026-10-16)

- New `sheet` command. `node scripts/kit.mjs sheet --group <title> <id…> --out <file.html>` builds one self-contained HTML page of small labelled thumbnails, so candidates can be shown in chat at a sensible size.
- When presenting a pick and alternatives, the skill now describes each one in words (what is drawn, not its id) and shows it with a contact sheet. If it can't send files, it gives links. It no longer embeds remote Markdown images, which many clients show as a "Show Image" link box.

1.1.0 (2026-10-16)

- New `update` command. `node scripts/kit.mjs update --check` compares the installed version with the latest one published at `https://sketchplanations.com/kit/skill/latest.json`. `update` downloads the zip, checks its sha256 and replaces the installed folder.
- Every run now prints a one-line note when the catalogue reports a newer skill version.
- The latest zip, manifest and install steps are published at `https://sketchplanations.com/kit/skill`.

1.0.1 (2026-10-13)

- When the catalogue or a download fails in a way that looks like a blocked network (DNS errors, refused or reset connections, proxy 403/407), the script now says to ask the user to allow `sketchplanations.com` in the environment's network settings. `references/troubleshooting.md` says the same.

1.0.0 (2026-10-13)

- First version. It finds illustrations by keyword and by meaning (reading the category index), chooses between candidates, downloads the full and half PNGs, and places them in web pages, Markdown, slides and docs.
- It reads catalogue schema v1 from `https://sketchplanations.com/kit/catalog/v1/`.

This skill is experimental. I’ve found it really useful for getting agents to use the kit in my own projects, and I’d love to hear how it works for you. Send feedback to jono.hey@gmail.com.