# Skill

> Create high-quality, validated 3D scenes and technical visualizations by authoring declarative JSON files that are automatically audited, compiled, and rendered into browser-ready constructs.

- Skill: `rtmandreyev/skill` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx get-skill add rtmandreyev/skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rtmandreyev/skill/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rtmandreyev (https://skillmd.com/u/rtmandreyev)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/rtmandreyev/skill

---


# {{TITLE}}

You author a **scene** (declarative JSON); the bundled tools validate it, audit it, compile
it and render it. You never write graphics code. Work the loop below until the construct is
*genuinely good* — accurate and beautiful, honest about what is known, alive without being
noisy: something you would put in a launch video — or until the mode's limits are
reached, whichever comes first. Then deliver the best version so far.

Tools (Python 3.10+, standard library only; a Chromium-family browser for captures;
ffmpeg optional for video). `TOOLS` below is `{{SKILL_DIR}}/runtime/cli.py`, where
`{{SKILL_DIR}}` is the folder that contains this SKILL.md:

```sh
python3 TOOLS new <object|architecture|machine|organism|cd|book> --output scene.json
python3 TOOLS check scene.json                     # validate + compile + audit (--json: paths and fix hints)
python3 TOOLS build scene.json --out out/          # out/construct.html (open in any browser)
python3 TOOLS review scene.json --out out/         # + out/review/*.png contact sheets
python3 TOOLS video scene.json --out out/hologram.mp4 --seconds 16
```

For a CD, a book, a guitar, a synth, a bottle, a can, a glass or a car there is a **simple path**:
`python3 TOOLS params --list`, then `params <archetype> --variant <v> --output p.json`, fill
in the facts (leave sizes at their standard unless the user gave them), and `check`/`review`
it like a scene; a builder draws it in the house style. Use the full loop below for anything
else, or when the result needs more than the archetype offers. `prompts/` holds the same
rules for other models and hosts (`system.md`, `params.md`, `scene.md`, `repair.md`,
`vision-review.md`); `construct author --mode fast --vision` runs the whole bounded loop
with any OpenAI-compatible model.

Work in a folder of your own. Never install software or change settings to make this run;
if no browser is available, say so and deliver the HTML without captures.

## The loop

0. **Choose the mode, announce it, and decide on research.** Four modes
   ([effort](references/effort.md)); the user can just say one:
   - **fast:** one pass with self-review, no rounds loop: ≤10 minutes and 2 reviews (≤30 and
     4 for a richer subject). Generic subjects, simple objects, quick asks. Cents with a
     DeepSeek-class model (tested: DeepSeek V4.1 Flash).
   - **masterpiece:** judged rounds ([rounds](references/rounds.md)): a defect ledger, at most
     4 items a round, one critic who compares each version with the best so far; it stops
     after 2 rounds without a win, at every criterion 3, at 12 rounds or at 2 hours of active
     work. A named subject whose likeness matters. Frontier-model token cost.
   - **timeboxed:** masterpiece in 2 hours in all: the same rounds and stop rules, but the
     2-hour ceiling counts the critic's time with yours, so a slow critic means fewer rounds,
     not a longer wait. **Only when the user asks for it** (by name, or for masterpiece
     within two hours).
   - **unbounded:** the same rounds with only the stop rules: no round cap, no time ceiling.
     The critic finds a win almost every round, so it can run many rounds and hours at a high
     token cost; the per-round report lets the user stop it at any time. **Only when the user
     asks for it by name.**

   The old names still work (quick, standard and showcase are fast). **If the user names no
   mode, choose one and announce it before any work:** the mode, why, the rough time and
   cost, and how to switch ("say fast for a single 10-minute pass"). Fast for a generic
   subject, a simple mechanical object or a quick ask; masterpiece for a specific named
   subject whose likeness matters (a car model, a landmark, a named building); never
   timeboxed or unbounded. If you are a smaller or cheaper model and the subject is a hard named one, say
   so and recommend GPT-6.1 Sol or Claude Opus 5.5 (or a model of that class) for masterpiece, with fast as the option on
   this model. The limits are ceilings, not targets. A
   generic subject ("a desk lamp") needs no research; a concrete, named one (a brand and
   model, a named building or peak, a species) is researched whenever you are unsure of its
   identity-defining shape or specs; "research: on/off" in the request overrides both. See
   [effort](references/effort.md).

   **Watch the clock, and draft early.** Research takes at most 40% of the tier's time and
   ends in a first draft: by 40% a complete scene that passes `check` is saved in your
   folder. Never hold the only copy in context, and never plan one big write at the end:
   improve the saved scene in place, `check` it and save it after every round, so a valid
   scene is always on disk. At 80% (in Hermes, the run budget's wrap-up notice) stop adding:
   make the saved scene valid, `build` it and deliver it with `authoring.next`.
1. **Research, then facts.** For a researched subject, first look up the exact thing — the
   official or maker's pages, manuals, specs, plans, reference photos — then look at the
   references with vision (any model that can see: Claude, GPT, Gemini, DeepSeek) and
   measure silhouette and proportions, within the tier's research counts. Only then author.
   For a named subject, write the **identity checklist** now: the features that make it
   itself (a Countach: low wedge, NACA ducts, periscope roof channel, trapezoid arches,
   scissor doors), in `authoring.identity`, each later listed with the parts that build it.
   Write down what is actually known and where it came from: the user's
   words, supplied measurements, documents they gave you, the sources you read. Every fact gets a certainty:
   `verified` (cites a source), `user_supplied`, `inferred` (your reasoning: typical sizes,
   proportions) or `decorative` (chosen for presentation). Do not invent precision; a
   generic reconstruction says so (`subject.accuracy: "generic"`), and a new design, with
   nothing real to reconstruct, is `"original"`. What the user asked for, or a document says
   the thing must do, is a fact with `"requirement": true` and its source; name its key in the
   `basis` of each part that realises it (the part stays `inferred`). Each value is
   documented (`verified`, citing its source), traced (`traced`, citing the orthographic
   drawing; from a perspective photo `inferred`) or invented (`inferred` with a note, or
   `decorative`). A part whose size and shape are known differently says each:
   `{"size": "verified", "shape": "traced"}`, its verified dimension facts in `basis`. Without a
   cited source nothing is `verified`. See [provenance](references/provenance.md).
2. **Recognition before geometry.** Name the silhouette, the primary masses and the **two
   or three identity features** that make the thing itself (a lighthouse: tapering banded
   tower, gallery, glazed lantern; a record player: platter with record, S-shaped tonearm).
   Decide proportions from facts. Plan stages bottom-up. See
   [composition](references/composition.md).
3. **Write the scene.** Start from `new <category>` or an example in
   `{{SKILL_DIR}}/examples/`. Build masses first, then structure, identity, detail. Use
   the right shape for each part (lathe for turned forms, extrude for plans and gables, tube
   for limbs and arms, repeats for colonnades and railings, mirror for symmetry). Give
   every part a role, a certainty and a stage. Text (titles, spines, labels) comes from
   facts through `labels`, images through named artwork slots; never choose colours, the
   renderer owns them. See [vocabulary](references/vocabulary.md). **Draw with craft**
   ([craft](references/craft.md)): a line-weight hierarchy, dark depth-writing fills under
   a faint contour wire (never a main surface with `line: "none"`), a sub-volume per
   feature, density where the identity lives and true detail everywhere (one clear object at
   hero scale, something true in every region up close), and a critic round answered by a
   refine pass; the shipped examples show all five.
   When the thing's identity is a shape you cannot know from text (a guitar body, a car,
   a building's elevation), measure it from a reference image: see
   [tracing](references/tracing.md). Never invent an outline and call it verified. A named
   car or hull: trace side, top and front and loft through them (`loft-from-traces`); a
   named car or landmark: measure the likeness with `compare` before calling it finished.
   Buildings: the architecture kit (`tower`, `roof`, `dormer`, `facade`, `battlements`,
   `buttress`; [composition](references/composition.md)) and a measured site
   (`terrain --into`). A real
   place, peak or route comes from elevation data, and Earth from coastline data
   (`globe`): see [terrain](references/terrain.md).
4. **Animate with intent.** Choose an assembly style; `articulations` for what opens once
   (a lid, a board, a disc lifted out); part motion only where the object keeps moving (a
   platter spins, a tentacle sways, a beam turns); idle events that suit the subject; and a
   camera tour to the identity feature. See [animation](references/animation.md).
5. **Check until the audit is clean.** `check` must report `audit: PASS`. Fix every
   error (floating or unsupported parts, overclaimed certainty, accuracy that is not backed);
   read every warning and either fix it or be ready to explain it. Where one part rests on
   another, work out both heights and make them meet: a cylinder's base is at its `at` (on
   its side, its underside is `at.y - radius`), a centred box's underside half its height
   below.
6. **Review as an art director, and iterate.** Run `review`, then open and actually inspect
   `review/hero.png`, `sheet-views.png`, `sheet-assembly.png`, `sheet-motion.png`,
   `sheet-life.png`, `sheet-provenance.png` and each `view-<id>.png`. Score them against the
   [art-direction rubric](references/review.md): silhouette, proportions against the
   references, identity features, depth and layering, composition and hero framing, the
   assembly's story, motion, detail density, honesty. Improve the weakest point, `check`,
   `review` again. Your own review records `"outcome": "self-reviewed"`; only an
   **independent critic** (a fresh context comparing renders with the references:
   `critique`, see [review](references/review.md)) can record "good"
   or "outstanding". Use it for a richer fast run, in the rounds modes, and whenever the
   subject is named. In masterpiece or unbounded mode run the rounds with `python3 TOOLS
   rounds start scene.json --mode masterpiece` (or `timeboxed`, `unbounded`) ([rounds](references/rounds.md)):
   tag each edit with its ledger id, give each round's packet the request in the user's words
   (`rounds packet --request "..." --reference ...`; without it the critic gets none), one
   critic per round, keep a version only when it beats
   the best, and after every round report in chat the critic's top requests, what changed
   (ledger ids), won or lost, and the minutes.
   **Count the rounds in the scene:** before each review, add one to
   `authoring.review_rounds` and save; `check` warns `tier-rounds` past the tier's cap
   (quick 0, standard 2, showcase 4), and that is the end of reviewing. Stop when every criterion is good and you would show it as it is, or when
   the tier's review rounds or time run out. A host may add a fresh-eyes critic (an
   independent reviewer over the contact sheets). Geometric validity (the audit) and art
   direction (your eyes) are separate gates. If you cannot see images, still fix every
   `detached`, `thin-support`, `tips` and `thin` warning, and record `"outcome": "unreviewed"`.
7. **Deliver.** Record how it was made in the scene's `authoring` block (`tier`,
   `research`, the `sources` used, `review_rounds`, `outcome`: good, limit or unreviewed,
   and `next`: the most valuable improvements still open). Hand over `scene.json`,
   `out/construct.html` (and `out/geometry.json`, the video if made) with a short note: what
   is evidence, what is inferred or designed, which artwork is authentic and which is
   generated decoration, what you reviewed, and — if a limit stopped you — what the next
   improvement would be. Never call a generic reconstruction exact, and never present
   generated art as a real cover.

## A construct that assembles across a track (film mode)

Only when the user asks for a film or video of a construct assembling to music, or hands you a
track for it ("make a construct of X that assembles across this track"). Otherwise ignore this.

1. **Author the construct as usual**, with the loop above. Keep its own assembly short (at most 20 s);
   the film sets the long one.
2. **Measure the track:** `python3 TOOLS audio track.wav --out audio.json` (add `--voice vocals.wav`
   if there is a vocal stem). Note the track's length in seconds.
3. **Render the film:** `python3 TOOLS video scene.json --out film.mp4 --assembly <length - 1.25>
   --audio audio.json --sound track.wav --camera steady --size 1920x1080 --fps 24` (1.25 s is the
   ceremony opening; use the full length for another assembly style). `--camera steady` keeps the
   whole construct in view; use `tour` when the scene's own camera flights should play. Leave
   `--reactivity` at its default unless the user asks for a calmer (0.5) or stronger (1.5) film.
   It takes about an hour for four minutes of film; say so before you start.
4. **Review the film** by sampling frames, for example
   `ffmpeg -i film.mp4 -vf fps=1/10 frame-%02d.png`, and look at them: the build should visibly
   move on with the music and end with the whole construct. Report what you made, its length,
   and the reactivity and camera you used. Details: `docs/FILM.md` in the Construct repository.

## A NetLogo model as a construct

Only when the user asks to visualise a NetLogo model or run. No scene authoring is needed: the
bridge computes the construct from a recorded run (details: `docs/NETLOGO.md`). Over MCP, the same
steps are `construct_netlogo_instrument` and `construct_netlogo_draw`.

1. Record. If the user works in NetLogo 7, the Construct extension is simplest (`extensions
   [construct]`, `construct:start`, `construct:record`, then `construct:draw` in the Command
   Center: `hosts/netlogo/README.md`). Otherwise `python3 TOOLS netlogo-instrument Model.nlogox
   --title "Model" --out run/` with what to record: `--turtles a,b`, `--reporters "count sheep;count
   wolves"`, `--patches pcolor:4`, `--no-turtles`, `--seed N`, `--ticks N`. Setup and go come from
   the model's own buttons when it has no `setup`/`go`; `--setup "setup 4"` when setup takes inputs
   (a refusal names the buttons). Tell the user to run it in NetLogo (setup, go), or headless with
   the command it prints, if NetLogo is installed.
2. `python3 TOOLS netlogo run/run.jsonl --view <view> --out scene.json`: `space-time` (moving agents),
   `network-time --state var` (spreading on a network), `phase --x R1 --z R2` (two quantities in a
   cycle; `--smooth N`), `field` (spreading over patches). `--time sqrt` when most change comes early.
   The scene carries its legend, how-to-read lines and a replay of the run with its counts.
3. Build and review it as usual, and credit the model as its Info tab asks.
4. **Art direction (optional, when the user wants it to look good).** Never edit the data: write a
   layer, `art.json`, and redraw with `--art art.json`. It holds `credit` (your exact model name),
   `title`, `summary`, `looks` (a data part's label, look or note, by id), its own `parts`, `facts`
   and `annotations` (source `art`, or none; `inferred` with a note when computed from the run,
   else `decorative`), `presentation` (views, framing), `animation`, `reading` (`{"how": [...]}`,
   the panel's lines in your words) and `legend` (`false` when your annotations replace it).
   Compute every milestone (half adopted, the last burn, a peak) with a short script over
   `run.jsonl`, never by eye; keep every data part visible; review before and after each change
   and keep only what reads better. The scene's `data_lock` fact makes `check` refuse any change to
   the data. In masterpiece or unbounded mode, judge the layer with the rounds as for any construct
   (`rounds start scene.json`, redrawing with `--art` between rounds): the critic of a run checks
   every label and milestone against the recording and judges how well a student could read it.
5. **Two runs compared (when the user asks what a parameter changes):** record both, then `python3 TOOLS
   netlogo-compare a.jsonl b.jsonl --labels "vision 3,vision 6" --out scene.json` and build it.
6. **A 3D model of the run (optional, when asked):** add `--solid --glb run.glb` (each turtle a
   sphere where it rose, a cycle as a tube, a spread as a surface, in the run's own colours; the
   build replays the run in Blender).
7. **Films (optional, when asked).** A film of the run in Blender, every agent as moving light,
   silent, at 30 ticks a second: `python3 TOOLS netlogo-film run.jsonl --out film.mp4` (or
   `--blend`; it takes minutes at full size, so offer `--seconds 10 --size 960x540` first).

## A 3D model of a construct (export)

Only when the user asks for a 3D model, a file for Blender, Godot, Unity or Unreal, a glTF, GLB or
OBJ of the construct. Author and review the construct first, as above; then:

- `python3 TOOLS export scene.json --out model.glb` (glTF 2.0: every part a named object, its
  joints as the `open` animation, periodic motion as `idle`, each vertex's build phase as
  `_PHASE`). For OBJ: `--out model.obj` (an `.mtl` beside it; `--frame z-up` for Z-up tools).
- For a game engine: `--merge --wire seams` (static parts merged per material, the design lines as
  dark seams); `--wire tubes` keeps all the line art as thin geometry instead;
  `--pose open` rests the model open; `--materials map.json` colours and finishes parts by id or
  pattern (`{"materials": [{"parts": ["body", "door-*"], "color": "#2b4a6f", "finish": "paint"}]}`;
  finishes: paint, brushed, chrome, wood, rubber, plastic, glass, light), when the user wants a
  finished model. Keep the map beside the scene as `<scene>.materials.json`: colours are the
  user's choice, never facts in the scene.
- For physics: `--pieces glued` makes what stays put one body and each door, lid or tailgate one more on its
  own hinge (`hosts/godot/construct_joints.gd` makes them Godot joints); `--pieces` alone, pieces that break
  apart and settle; `--colliders`, a collision box per part.
- A `no-surface` audit warning names a main or structural part drawn only as lines: it would be
  missing from the model, so give it a solid shape (a tube, a box) when the export matters.
- Say what the model is: correctly sized named parts with working joints, built from simple
  shapes, without textures; good for blockouts, props and previews, not a finished hero asset.
  Details: `docs/EXPORT.md` in the Construct repository.

## A 3D print of a construct

Only when the user asks to 3D print it, or for an STL or 3MF. Author and review the construct
first; then `python3 TOOLS print scene.json --out model.3mf` (or `.stl`) writes one watertight
solid, Z up, on the bed, 100 mm on its longest side (`--size MM`, or `--scale 43` for 1:43 of the
real size). `--printers` says how large it prints on five printer classes and what is lost at that size;
`--printer desktop --fit` prints at the largest size that fits; `--exact` keeps the construct's own solids
(finer detail than voxels). Refine the solid first (`check --fit`, references/review.md). Report what it prints: the size and scale, and its notes (overhangs that need supports,
parts thickened to the wall, parts drawn only in lines and not printed: `--lines` prints them
raised). Exit status 1 means it is not watertight: say so, never hand it over as printable. The user
does not need a printer to check it: a slicer (PrusaSlicer, Bambu Studio, Cura) opens and slices it.
Details: `docs/PRINTING.md` in the Construct repository.

## A construct in FreeCAD or CAD (STEP)

Only when the user asks for FreeCAD, CAD or STEP, and FreeCAD is installed: `python3 TOOLS freecad
scene.json --out model.FCStd --step model.step` builds named solids with the joints as groups (each
with an `Open` placement), true CAD shapes where a part's parameters allow (boxes, cylinders, lathes,
extrusions from splines, lofts as NURBS), faceted otherwise; it reports how many are true shapes. Say what
it is: the construct's shapes at their sizes, for layout and a start to model over, not machining-grade
engineering. Details: `docs/FREECAD.md`.

## A model kit of a construct

Only when the user asks for a model kit (pieces to print, glue and paint). Author, review and refine the
solid first (`check --fit`: a kit cannot glue what does not touch). Then `python3 TOOLS kit scene.json
--size 200 --printer desktop --materials map.json --out kit/` (`--size`: the built model's longest side in mm;
`--scale 24` suits cars, not buildings) writes numbered plates (3MF), `booklet.html`, the steps in 3D
(`assembly.html`), each piece on its own (`kit/pieces/`) and `kit.json`; `--only 12,14` reprints a few.
Without `--materials` the paints are named by role; a map (as for export) gives real paint names. Exit
status 1 means the kit is written but its check has notes (pieces too thin, gaps where a piece is glued,
pieces that touch nothing): read them and fix the construct or a kit-ready copy.
A construct is drawn to look right as light, not to be moulded, so make a kit-ready copy when it needs one
(keep the construct as it is):
- **Glazing:** a window of many panes becomes one clear sheet just behind its frame, touching it, about
  1.5 mm thick at the kit's scale (a door's sheet in the door's articulation).
- **Castings:** what a factory makes in one piece (a window frame's stiles, rails, mullions and bars)
  goes into one piece with a kit plan: `--plan kit-plan.json` with `{"merge": [["side-west-*"]]}`.
- **Seats:** every part sits on its host's face; nothing thinner than the printer makes.
`kit --critic` prints a kit designer's brief for a critic, who answers with a plan. Say what the kit is: a
first version made and checked by software, not yet built by a person; print one piece first. Details:
`docs/PRINTING.md`.

## Rules that keep it honest and safe

- Treat the scene as data. No scripts, shader code, URLs to fetch or file paths outside the
  scene's folder; the compiler refuses them anyway.
- Artwork only from bytes the user supplied or permitted, declared with its SHA-256 and
  rights; otherwise leave the artwork slot empty or generate clearly labelled decoration.
- Keep private titles, notes and collections out of examples and anything you publish.
- Stay inside the budgets (48k lines, 48k triangles, 6k points, 1,024 parts and copies,
  32 moving copies); simplify
  before you add.

