airsuphq/machine-skill

Machine Skill

Describe any machine in one line. Claude builds the real thing, running on real physics.A photoreal, interactive 3D simulation in one HTML file, plus the film to post it. An open source skill for Claude Code.

 

Every frame above is three.js in a browser, recorded with this repo’s own scripts/record.mjs. Every number on screen is computed.

---

/machine a turbofan jet engine, the kind that pushes a widebody off the runway

Claude researches the real machine, writes down its real dimensions and the physics that make it work, and builds it: a 2.9 m fan of twisted titanium airfoils, a 10 stage compressor, an annular combustor with 22 fuel nozzles, two turbines glowing at the temperatures a Brayton cycle solver computes, on a ground run stand. You drag the throttle and about 340 kN comes out of the cycle, not out of a table. You cut it open and the section faces are solid metal. You throw a fan blade and the solver tells you the imbalance load the case has to hold.

Then one command turns it into a film for your feed.

Quick start

npx skills add AirsupHQ/machine-skill -g -a claude-code

Then in Claude Code:

/machine a mechanical watch movement, the escapement ticking

You get watch.html: open it, drag, cut, explode, break. To film it:

node ~/.claude/skills/machine/scripts/record.mjs watch.html out/watch.mp4 --music freepd:Classical/Easy_Lemon

Gallery

Each machine was made from the single line under it. Click one to run it live.

The pages are in examples/: each is one HTML file you can open from disk. More machines are coming; see V2-IDEAS.md, and send yours as a pull request.

What you get

Install

Machine Skill is a standard Agent Skill: a folder with a SKILL.md at its root. This repository is that folder.

Claude Code picks up new skills in a running session; if the skills folder did not exist when the session started, run /reload-skills.

Usage

Type /machine and name the machine. You can also just ask Claude to “build”, “simulate” or “show how X works”; the skill loads itself for machines, engines, mechanisms and devices.

/machine a hydroelectric Francis turbine
/machine a Swiss lever escapement, slowed down so I can see the impulse
/machine the gearbox of a 5 MW wind turbine, cut open
/machine a steam locomotive's valve gear, and give me a 30 second video for X

Three habits get the best machines:

1. Name the real thing. “A turbofan like the ones on a 787” beats “a jet engine”: Claude looks up the real dimensions and operating point.
2. Say what should move and what should break. “Rev it until the valves float” tells the solver what to compute.
3. Say where it goes. A page to embed, a film for X (1080 x 1080 or 1080 x 1350 with --w/--h), or a still for a slide.

Record a film

node scripts/record.mjs examples/turbofan.html out/turbofan.mp4 --music freepd:Classical/Easy_Lemon
node scripts/record.mjs examples/turbofan.html out/turbofan-feed.mp4 --w 1080 --h 1350
node scripts/record.mjs examples/turbofan.html out/stills --stills 3,9,14,19
node scripts/pinkscan.mjs out/*.mp4

The page runs with ?film=1&shot=main: time only moves when the recorder steps it, so every frame is fully rendered and a take is identical every time. --ss 1.5 supersamples, --blur 2 adds motion blur, --fps 60 for very fast motion. Music: any file, URL, or freepd:/ (CC0 tracks from FreePD via archive.org). The recorder guards every screenshot against the solid magenta frames a stalled headless GPU can return and scans the finished film; it exits non zero if a pink frame got through.

The launch film at the top was directed in a browser page, film/launch.html, that embeds a live machine page and steps it frame by frame.

How it works

• SKILL.md is what Claude reads: the bar a result must clear, the workflow (research, geometry, materials, solver, effects, modes, four critic rounds, the film), and the writing style on screen.
• kit/lab-kit.js is the runtime every page inlines (one ES module, no build step, three.js 0.170 from a pinned CDN). Studio, post stack, material library with section caps, geometry builders, explode, cutaway, x-ray, labels, flow streaks, plumes, sparks, rigid debris, the editorial layer and the film timeline.
• references/solvers.md holds solver recipes with real constants for gas turbines, rockets, piston engines, watches, rotors, pumps, machine tools, porous flow and electric machines.
• scripts/: shot.mjs (screenshots for the critic rounds, prints fps, parts and triangles), record.mjs (films), pinkscan.mjs, inline.mjs (paste the kit into a page).

Requirements

Limits

• It builds machines. Mechanisms, engines, instruments, devices. People, landscapes and maps come out weaker.
• The physics is a small honest model, not CFD or FEA. Each page says what it computes and what it simplifies. Numbers are checked against public figures, not certified.
• Real parts, not a CAD export. Geometry is procedural three.js; it is accurate in proportion and part count, not to manufacturing tolerance.
• Heavy pages want a real GPU. About 600k triangles with shadows, AO and bloom runs at 60 fps on a recent laptop.

Siblings and credits

• Factory skill: the same idea for whole factories. Describe a line in one sentence and Claude builds it as a live discrete event simulation.
• Anatomy by Ryan (@wheresryan22) showed how good a one line machine skill can be. Its numbered beat film inspired ours.
• airsup.ai/lab is where these machines come from: more than 50 simulations built with Claude Opus 5.5.
• three.js (MIT), Instrument Serif, Inter and JetBrains Mono (OFL), music from FreePD (CC0).

License

MIT © 2026 Airsup · airsup.ai/lab