A diorama here is a tiny staged scene on a slab: a locked three-quarter camera, a flat cut-out against white paper, a 64 colour palette with ordered dither and an inked contour, and toy-scale people with real joint animation. The subject changes (pool, night market, bank job, arena battle); the slab, the cast and the presentation stay.

Everything is deterministic. The scene is a pure function of t, so any frame can be frozen, screenshotted and compared. A screenshot is evidence, not a lucky capture.

SKILL.md is the whole playbook: it carries a research-first workflow, the look and animation bars, the pipeline, the recipes, the QA harness and the pitfalls, in one self-contained file. Everything else here is copy-in code that supports it.

Pikachu vs Charizard is the fight at the top of this page: Leon throws a ball, Charizard bursts out of it and the ball comes back to his hand, four attacks trade across the arena with their own wind-up and hit reactions, Pikachu takes a knockdown, and the red recall beam only appears once Charizard is beaten.

Dust Kings follows one night's billing: cars on the arena floor, the billboard running through LIVE, NEW RECORD and THANK YOU, and a fire that gets away from them.

Pool is a slow afternoon: one swimmer working laps with a wake trailing behind, one standing waist-deep by the ladder, one folding into a dive beside the board, a lifebuoy and a ball left floating, a lifeguard pacing the far edge, and a sunbather who does not move from the towel.

Bank job runs in daylight: a sedan noses into the curb, a group in dark clothes climbs the bank steps and the windows go red behind them, the sedan pulls away, two cruisers arrive and officers fan out across the street, then the street empties again.

Paste this into an agent that can run shell commands. It asks where to put the folder, downloads the whole repository (playbook, templates, QA harness and every worked example), reads them, and reports what it learned before it builds anything. SKILL.md carries skill frontmatter (name, description, version), so an agent with a skills directory can load it by name later.

Install the Diorama playbook here, then use it to build scenes.

Repo: https://github.com/sloemo01/diorama

1. Ask me where the folder should go before downloading anything,
   and wait for my answer. Propose ~/skills/diorama as the default.
   Do not pick a path silently.
2. Download the whole repository, not just SKILL.md:
     git clone https://github.com/sloemo01/diorama.git "<target>"
   Without git:
     curl -L -o diorama.tar.gz \
       https://github.com/sloemo01/diorama/archive/main.tar.gz
     tar xzf diorama.tar.gz && mv diorama-main "<target>"
3. Prove the install before describing it: SKILL.md, README.md,
   templates/, verify/ and LICENSE at the root, and print the
   commit hash (git -C "<target>" rev-parse --short HEAD) or the
   archive date. If you have no shell or no network, say so and
   stop. If the download failed or a file is missing, say so and
   stop. Never describe this playbook from memory.
4. If you have a skills directory or plugin folder, install it
   there so you can load it by name in later sessions; otherwise
   treat "<target>" as the folder.
5. Read before you build: all of SKILL.md, then
   templates/DESIGN.md, templates/SOURCES.md, templates/CREDITS.md,
   templates/qa/README.md, the header comment of every file in
   templates/, and the worked examples under verify/. SKILL.md is
   the source of truth; the README is only a summary.
6. Report back in this order: install path and commit, the Look
   Contract in one paragraph, the Pipeline as ordered steps, the
   QA scripts and what each one checks, and three rules from
   SKILL.md with the section each came from.
7. Then ask me what the first diorama should be. Do not ask me to
   fill the design sheet. When I give you a subject, research it
   first (frames, assets, motion), fill DESIGN.md from the
   defaults, copy the modules you need into my project instead of
   editing the installed copy, build through the Pipeline, and run
   the QA scripts before you show me anything. Give me the paths
   of the frames you kept and what each one proves.

If two parts of SKILL.md contradict each other, list them before
you build. A successful clone is not an install: 5 and 6 are it.

Needs git, or curl and tar for the fallback. The QA scripts need Node with three, esbuild and playwright-core. The media/ previews are about 20 MB and can be deleted after the clone.

1. Read SKILL.md: Research Before You Model, One Prompt, One Build, The Look Contract, The Detail Bar, The Animation Bar, Pipeline.
2. Research first. Step the real subject into frames and write its motion grammar down. Walk the sourcing ladder for every hero asset (already on disk, CC0, CC-BY, then hand-build) and record each search in refs/SOURCES.md. Imported assets get a row in CREDITS.md.
3. Copy templates/DESIGN.md into the project as DESIGN.md and fill it. Premise as a verb, cast, systems, five beats with timestamps, detail budget.
4. Copy the modules you need into src/core/ and src/scene/, then a config.js that holds the scene's numbers. verify/water/src/ is the reference layout.
5. Block out in grey at the locked camera before any production pass, then run the pipeline: palette, materials, detail, animation, effects, post.
6. Verify with templates/qa/ before calling it done, and check the research gate in Build And Ship (reference sheets, SOURCES.md, CREDITS.md, per-beat captures).

The playbook opens with four lookups, because a plausible silhouette that matches nothing is the most common way a commission fails:

• Shape. Pull the real thing on video, step it into contact sheets at 8 to 12 fps, read them, and write the grammar down before touching geometry.
• Assets. Check the user's disk, then the CC0 and CC-BY libraries (Quaternius, KayKit, Poly Pizza, Kenney, Sketchfab with the downloadable plus CC0 filter, Smithsonian, Poly Haven, ambientCG, Mixamo and the Quaternius animation library). A rigged download beats four hundred lines of primitives at close range. Licences that are NC, ND, ripped or unstated are a hard stop.
• Motion. Search the verb, not the noun. Count frames at a known fps, convert to seconds, and write wind-up / contact / follow-through / recover before animating.
• Proof. Freeze every beat and compare the capture against the reference frame for that beat.

templates/SOURCES.md and templates/CREDITS.md are the two artifacts that make that research visible in a project, and Build And Ship will not pass without them.

• One camera solve. The camera is fitted to the slab's bounding box once, at a fixed three-quarter azimuth, with a subjectScale margin. No orbit controls.
• Two passes, one look. The render is drawn into a small buffer, then gamma, grade, a 64 entry palette snap, ordered dither, an ink contour and a nearest neighbour upscale happen in that fixed order.
• Detail is a bar, not a mood. Every hero prop carries a real silhouette, chamfers, seams, hardware and a contact shadow; if it reads at a glance and still holds at 1:1, it passes.
• Animation is five layers. Idle, locomotion, secondary motion (clothes, hair, tails, capes), glance and weight shifts, then the scripted acting on top.
• Everything is a function of t. Actors, props, effects and camera are evaluated from the beat sheet each frame, so ?t=12.4 is exactly the same picture every time.

The templates/qa/ scripts drive Chromium through playwright-core against a page that exposes a debug handle:

window.__diorama = {
  THREE, scene, camera, renderer, post,
  freeze(t) { /* draw(t) synchronously */ },
  view(pos, tgt) { /* optional debug camera */ }
};
window.__dioramaReady = true;

freeze(t) has to draw synchronously. Without it a screenshot is a race, and a screenshot that may show a different frame than you asked for is not evidence.

frames.mjs is the one that pays for itself on a scene with more than two actors. It records one dense series per entity, isolates it, fits a camera to its swept bounds, and scores it: a flat energy line means the actor is not animating, an NDC jump means a state boundary is snapping instead of blending, and empty frames mean the window is wrong. Each entity gets a contact sheet and a verdict, so a dead actor cannot hide behind a moving neighbour.

The worked examples under verify/ show the loop end to end, including the defects the harness found and the numbers after the fix.

SKILL.md carries skill frontmatter (name, description, version), so a skill-capable coding agent can load it as-is. It is self-contained: no external reference documents, everything needed to build a diorama is in the file plus templates/.

If you just want to read it, start at Research Before You Model, then One Prompt, One Build and The Look Contract.

Long builds will eventually compact the agent's context, and compaction is lossy. SKILL.md has a Long builds and context section for that: state lives in DESIGN.md, SOURCES.md, CREDITS.md, report.json and the beat table rather than in the chat, and after a compact the agent re-runs frames.mjs and shoot.mjs instead of trusting its own summary of the last frame.

MIT. See LICENSE. three.js is MIT as well.