Learnscape

A Claude Code skill for building isometric explorable explainers — a place that runs a mechanism, so a complex system can be learned by watching something travel through it.

The vehicle carries real state. Each stop performs one real step of a real simulation. The vehicle stops for as long as the write-up for that stop takes to read, then speeds up once there is nothing new to read. Everything is one dependency-free static site: HTML, canvas 2D, plain JavaScript, no build step.

This repo packages the technique behind TokenTown (a transformer laid out as a city) and EngineWorks (an F1 power unit as a factory line) so it can be pointed at any subject.

Install

As a personal skill — available in every project:

git clone [email protected]:LaurentiuGabriel/learnscape.git
cp -r learnscape/skills/isometric-explainer ~/.claude/skills/

As a project skill — available in one repo, and committable with it:

mkdir -p .claude/skills
cp -r /path/to/learnscape/skills/isometric-explainer .claude/skills/

As a plugin — this repo is also a Claude Code plugin, so from the directory that contains your clone:

/plugin marketplace add ./learnscape
/plugin install learnscape@learnscape

Both manifests pass claude plugin validate --strict, but the end-to-end plugin install is untested; the copy methods above are the verified path.

Then ask for what you want built:

Build me an isometric explainer for how a Raft consensus round works.

Claude loads the skill automatically when a request looks like this, or you can invoke it directly with /isometric-explainer.

What you get

skills/isometric-explainer/
  SKILL.md                      the five rules, the layout, how to verify
  references/
    build-order.md              seven phases, in order — start here
    fidelity.md                 the honesty ledger: computed / scaled / assumed / faked
    pacing.md                   reading stops, fast-forward, the tour-done switch
    isometric-drawing.md        projection, sort order, occlusion, faces, labels
    narration.md                how to write the district copy
    checklist.md                walk this before calling it done
  scripts/
    smoke.mjs                   headless check: console errors + every station + a screenshot
  assets/template/              PacketPost — a complete, working explainer

The template is not a scaffold. It is PacketPost, a finished small explainer of what a web request costs: eight stations, a real latency model with TCP slow start and congestion-window doubling, and a branch in the road for a CDN cache hit. Copy it, open it, watch one full trip, then replace the subject.

The idea

An animation of a complex process is normally either too fast to learn from or too slow to watch. These explainers dodge that by making the same run slow the first time and fast afterwards: the first pass is a guided tour paced by reading speed, and once every station has been explained the run speeds up into something watchable. The reader never has to pause to keep up, and never sits through an explanation twice.

The other half is honesty. Every project built this way publishes a fidelity ledger that sorts each number into genuinely computed, scaled down, assumed, or deliberately faked. A visual explainer that does not say which of its numbers are real is a plausible-looking picture, not a teaching tool.

Verified

The template runs clean: node --check on all seven JS files, and the shipped smoke test in headless Chromium at both dpr 1 and dpr 2 — zero console errors, all eight stations firing, the full three-request run completing, and screenshots reviewed for occlusion and label collisions.

The smoke test needs Playwright (npm i -D playwright && npx playwright install chromium). Without it, open index.html directly.

Credits

The technique is drawn from TokenTown and EngineWorks, which in turn owe the city-shaped-system idea to PGSimCity. Rule 1 — that the simulation must be real, and must run and be testable with the renderer removed — comes from ChipBuilder, whose logic-simulation core has no dependency on its graphics layer at all. All code, copy and art in this repo are original.

MIT licensed.