{{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:
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
Choose the mode, announce it, and decide on research. Four modes (effort); 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): 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.
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
checkis 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,checkit 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,buildit and deliver it withauthoring.next.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) ordecorative(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": trueand its source; name its key in thebasisof each part that realises it (the part staysinferred). Each value is documented (verified, citing its source), traced (traced, citing the orthographic drawing; from a perspective photoinferred) or invented (inferredwith a note, ordecorative). A part whose size and shape are known differently says each:{"size": "verified", "shape": "traced"}, its verified dimension facts inbasis. Without a cited source nothing isverified. See provenance.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.
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 throughlabels, images through named artwork slots; never choose colours, the renderer owns them. See vocabulary. Draw with craft (craft): a line-weight hierarchy, dark depth-writing fills under a faint contour wire (never a main surface withline: "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. 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 withcomparebefore calling it finished. Buildings: the architecture kit (tower,roof,dormer,facade,battlements,buttress; composition) and a measured site (terrain --into). A real place, peak or route comes from elevation data, and Earth from coastline data (globe): see terrain.Animate with intent. Choose an assembly style;
articulationsfor 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.Check until the audit is clean.
checkmust reportaudit: 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 itsat(on its side, its underside isat.y - radius), a centred box's underside half its height below.Review as an art director, and iterate. Run
review, then open and actually inspectreview/hero.png,sheet-views.png,sheet-assembly.png,sheet-motion.png,sheet-life.png,sheet-provenance.pngand eachview-<id>.png. Score them against the art-direction rubric: 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,reviewagain. Your own review records"outcome": "self-reviewed"; only an independent critic (a fresh context comparing renders with the references:critique, see review) 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 withpython3 TOOLS rounds start scene.json --mode masterpiece(ortimeboxed,unbounded) (rounds): 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 toauthoring.review_roundsand save;checkwarnstier-roundspast 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 everydetached,thin-support,tipsandthinwarning, and record"outcome": "unreviewed".Deliver. Record how it was made in the scene's
authoringblock (tier,research, thesourcesused,review_rounds,outcome: good, limit or unreviewed, andnext: the most valuable improvements still open). Hand overscene.json,out/construct.html(andout/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.
- Author the construct as usual, with the loop above. Keep its own assembly short (at most 20 s); the film sets the long one.
- Measure the track:
python3 TOOLS audio track.wav --out audio.json(add--voice vocals.wavif there is a vocal stem). Note the track's length in seconds. - 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 steadykeeps the whole construct in view; usetourwhen the scene's own camera flights should play. Leave--reactivityat 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. - 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.mdin 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.
- Record. If the user works in NetLogo 7, the Construct extension is simplest (
extensions [construct],construct:start,construct:record, thenconstruct:drawin the Command Center:hosts/netlogo/README.md). Otherwisepython3 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 nosetup/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. 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 sqrtwhen most change comes early. The scene carries its legend, how-to-read lines and a replay of the run with its counts.- Build and review it as usual, and credit the model as its Info tab asks.
- 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 holdscredit(your exact model name),title,summary,looks(a data part's label, look or note, by id), its ownparts,factsandannotations(sourceart, or none;inferredwith a note when computed from the run, elsedecorative),presentation(views, framing),animation,reading({"how": [...]}, the panel's lines in your words) andlegend(falsewhen your annotations replace it). Compute every milestone (half adopted, the last burn, a peak) with a short script overrun.jsonl, never by eye; keep every data part visible; review before and after each change and keep only what reads better. The scene'sdata_lockfact makescheckrefuse 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--artbetween rounds): the critic of a run checks every label and milestone against the recording and judges how well a student could read it. - 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.jsonand build it. - 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). - 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 960x540first).
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 theopenanimation, periodic motion asidle, each vertex's build phase as_PHASE). For OBJ:--out model.obj(an.mtlbeside it;--frame z-upfor Z-up tools).- For a game engine:
--merge --wire seams(static parts merged per material, the design lines as dark seams);--wire tubeskeeps all the line art as thin geometry instead;--pose openrests the model open;--materials map.jsoncolours 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 gluedmakes what stays put one body and each door, lid or tailgate one more on its own hinge (hosts/godot/construct_joints.gdmakes them Godot joints);--piecesalone, pieces that break apart and settle;--colliders, a collision box per part. - A
no-surfaceaudit 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.mdin 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.jsonwith{"merge": [["side-west-*"]]}. - Seats: every part sits on its host's face; nothing thinner than the printer makes.
kit --criticprints 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.
