Skip to content
Back to search

machine

SkillWorks with Claude CodeGitHub

Turn one line ("a turbofan jet engine", "a mechanical watch", "an LVAD heart pump") into a photoreal, physics based, interactive 3D simulation of that machine in a single HTML file, plus a 20 to 30 second film to post it. Real proportions in metres, real materials (PBR metals, paints, polymers, glass), studio lighting with soft shadows, moving parts driven by a small solver that computes real numbers (thrust, torque, rpm, flow, pressure, efficiency), and modes to explode it, cut it open with clean section caps, x-ray it, slow it down, label it and break it. Use this whenever someone asks to build, simulate, visualise, explain or "show how X works" for any machine, engine, mechanism, device, instrument or piece of hardware, wants an interactive 3D model or a cutaway, or wants a video of a machine for a post, even if they never say "simulation" or "three.js".

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/airsuphq--machine-skill/badge.svg)](/listings/airsuphq--machine-skill)

HTML

<a href="/listings/airsuphq--machine-skill"><img src="/api/listings/airsuphq--machine-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 159 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: machine
  3. description: Turn one line ("a turbofan jet engine", "a mechanical watch", "an LVAD heart pump") into a photoreal, physics based, interactive 3D simulation of that machine in a single HTML file, plus a 20 to 30 second film to post it. Real proportions in metres, real materials (PBR metals, paints, polymers, glass), studio lighting with soft shadows, moving parts driven by a small solver that computes real numbers (thrust, torque, rpm, flow, pressure, efficiency), and modes to explode it, cut it open with clean section caps, x-ray it, slow it down, label it and break it. Use this whenever someone asks to build, simulate, visualise, explain or "show how X works" for any machine, engine, mechanism, device, instrument or piece of hardware, wants an interactive 3D model or a cutaway, or wants a video of a machine for a post, even if they never say "simulation" or "three.js".
  4. ---
  5. # Machine Skill
  6. You build a machine the way a product studio photographs one and an engineer explains one: the real thing at its real size, in real materials, on a clean studio set, running on real equations. One line in, one HTML file out, and a film in one command.
  7. The output is always:
  8. 1. `<name>.html`: a single self contained page (three.js 0.170 from jsDelivr, the kit inlined). It opens from disk, from any static host, or inside an iframe.
  9. 2. A film: `node scripts/record.mjs <name>.html out/<name>.mp4 --music freepd:<Category>/<Name>`.
  10. Open `examples/` first. Every example was made from the one line at the top of its page. `examples/turbofan.html` is the reference: read it end to end before you write anything.
  11. ## The bar
  12. Before you start, picture the frame a viewer sees after three seconds. It must already look like a studio product photograph of the real machine: correct silhouette and proportions, metal that reads as metal, a soft shadow on a paper floor, nothing floating, nothing clipping, nothing placeholder. Then it moves, and every number on screen is computed.
  13. A result is not done while any of these is true:
  14. - a part a mechanic would expect is missing (no fuel nozzles in a combustor, no escapement in a watch, no valves in an engine)
  15. - something floats, intersects, or has a visible seam or gap at a joint
  16. - a material looks like plastic when it should be metal, or everything is one grey
  17. - a number on screen is typed in rather than computed by the solver
  18. - the cutaway shows hollow shells instead of solid section faces
  19. - the first frame of the film is not beautiful
  20. ## Workflow
  21. ### 1. Research the real machine (5 minutes, no code)
  22. Write down, in a comment block at the top of the machine script, from what you know (and the web if you have it):
  23. - **The real dimensions** in metres of the 5 to 10 parts that define the silhouette (a turbofan: fan diameter 2.85 m, length 4.9 m, nacelle max diameter 3.44 m).
  24. - **The parts list** in assembly order, each with its material. Aim for 15 to 40 named parts; repeated parts (blades, teeth, bolts, coils) count individually.
  25. - **The physics** that makes it work, as 3 to 6 equations you will actually compute, with real constants and the operating point (a turbofan: Brayton cycle, take-off at N1 100 %, OPR 42, T4 1,750 K, about 330 kN).
  26. - **The one number** a viewer cares about: the hero (thrust, torque, beats per hour, flow, power). It gets a huge serif readout and a thin bar.
  27. - **The input** a viewer wants to drive: one slider (throttle, wind speed, rpm, pump speed, grind size).
  28. - **The break**: the failure an engineer worries about, and what the solver says happens (fan blade off and the imbalance load, valve float above the redline, a stalled pump, overpressure). This must be a computed consequence, not an animation.
  29. ### 2. Build the page from the template
  30. Copy `kit/template.html` to `<name>.html`. It has the import map (pinned three@0.170.0), the fonts, a marked block where the kit goes, and the four sections you fill in:
  31. ```js
  32. const { THREE, Lab, MAT, GEO, heatGlow, clamp, lerp, approach, fmt } = window.LabKit
  33. const lab = new Lab({ prompt, no, title, sub, size, view, cut }) // 1. the lab
  34. // 2. the parts lab.mesh(GEO..., MAT..., { name, pos, explode, xray, count })
  35. // 3. the solver lab.hero(...); lab.slider(...); lab.onTick((dt, lab) => { ... lab.setHero(...) })
  36. // 4. break, explain, film lab.breakIt(...); lab.how(...); lab.autoFilm(...); lab.start()
  37. ```
  38. Right after copying, run `node <skill dir>/scripts/inline.mjs <name>.html`: it pastes the kit into the marked block so the page is one self contained file wherever it lives (the template's `src="../kit/lab-kit.js"` only resolves inside this repo). Then write your machine in the second script block.
  39. ### 3. Geometry: real solids at real size
  40. Work in metres in the machine's own frame, Y up, the floor at y = 0 unless you set `ground`. Set `size` to the longest real dimension; the kit scales the display so every machine sits the same on the set, and the scale bar shows real size.
  41. - **Round parts** (shafts, discs, casings, nozzles, cones, spinners, pistons, bezels): `GEO.lathe([[r, y], ...])` with a CLOSED profile. Walls: `GEO.shell(profile, thickness)`, tubes: `GEO.tube(rOut, rIn, h)`, chamfered discs: `GEO.disc(r, h)`. Corners stay crisp and curves shade smooth automatically.
  42. - **Blades and vanes**: `GEO.rotor({ count, axis, r0, r1, chord, thick, camber, twist, pitch, sweep })` builds real cambered, twisted airfoils (NACA thickness) as closed solids and rings them. Use `[root, tip]` arrays for chord, thick and camber.
  43. - **Gears**: `GEO.gear({ teeth, module, width, bore, helix, spokes, rim })`. Mesh two gears at centre distance `(z1 + z2) * module / 2` and turn them at the inverse tooth ratio, offset by half a tooth.
  44. - **Pipes, hoses, wires**: `GEO.pipe(points, r)` (closed, capped). Route them along the structure from port to port, never through a part.
  45. - **Fasteners**: `GEO.bolts(n, R, size, h)` on every flange. Springs: `GEO.spring(R, wire, turns, len)`. Boxes: `GEO.rbox(w, h, d, r)` (always rounded, never sharp). Plates with holes: `GEO.extrude(shape, depth)`.
  46. - **Masses and inertias** come from the geometry: `GEO.volume(geo)` gives volume and centroid, multiply by the real density.
  47. Rules that keep it clean:
  48. - **Every part is a closed solid** (lathe profiles closed, shells with thickness, pipes capped). That is what lets the cutaway draw solid section faces. Open surfaces show as hollow when cut.
  49. - **Nothing intersects visibly and nothing floats.** Every part touches what holds it (a flange sits on a face, a shaft runs in a bearing, a post reaches the floor). Check joints in close ups.
  50. - **Detail where the eye goes**: bolt circles on flanges, chamfers, a lip, a label plate, fuel lines, a harness. Big flat areas get a seam, a panel line or a texture finish.
  51. - **Give the machine a base**: a stand, cradle, plinth, bench or mount with feet on the floor. Machines rarely float in real life.
  52. - **Budget**: up to about 700k triangles and 200 meshes. Merge repeated static parts with `GEO.merge` / `GEO.ring`; keep moving groups separate.
  53. ### 4. Materials: never one grey
  54. Use `MAT.*` presets; they carry measured reflectances so steel, titanium, aluminium, brass and copper look different side by side. Every preset takes overrides (`color`, `roughness`, `clearcoat`, any MeshPhysicalMaterial field) and a `finish` (micro roughness texture: `turned` rings on lathe parts, `brushed` streaks, `cast` blotches, `smudge`, `knurl`).
  55. | Use | Preset |
  56. |---|---|
  57. | shafts, discs, machined parts | `MAT.steel`, `MAT.stainless`, `MAT.chrome` |
  58. | housings, castings | `MAT.aluminium`, `MAT.castIron`, `MAT.steelDark` |
  59. | blades, aerospace | `MAT.titanium`, `MAT.inconel` (+ `heatGlow`) |
  60. | fittings, wiring | `MAT.brass`, `MAT.copper`, `MAT.gold` |
  61. | painted bodies | `MAT.paint({ color })`, `MAT.satin`, `MAT.anodised({ color })` |
  62. | polymers | `MAT.plastic`, `MAT.rubber`, `MAT.carbon` |
  63. | windows, crystals | `MAT.glass`, `MAT.sapphire`, `MAT.ruby`, `MAT.enamel` |
  64. | light, flame, hot gas | `MAT.glow`, `heatGlow(material, kelvin)` |
  65. Pick a palette like an industrial designer: mostly metals and one or two painted colours, one accent at most. Hot parts glow from the solver's temperature (`material.userData.heat.value = T`).
  66. ### 5. The solver: real numbers or nothing
  67. Write a small pure function from the input and state to every number you show, with real units and real constants. Integrate dynamics with `approach` (first order lag: spool up, thermal mass) or `rk4` (springs, escapements, pendulums). Then drive the motion from it: an rpm from the solver turns the shaft, a flow from the solver moves the particles, a temperature heats the metal.
  68. - One hero: `lab.hero({ label, unit, max })` then `lab.setHero(value, { state, sub, bad })` each tick. `state` is two or three words (spooling up, take-off, choked flow). `sub` is one line with 2 or 3 more numbers.
  69. - One slider: `lab.slider({ id, label, min, max, value, unit, ends })`. A second only if the machine truly needs it.
  70. - Labels hang on static parts at points on the section planes: `lab.label(obj, 'HP turbine', { at: [x, y, z], value: () => '12,979 rpm' })`.
  71. - `lab.how(words, equations)` fills "How it is computed": the model in plain words and the equations as written in the code. Say what is simplified.
  72. - If a motion is too fast to see (a 2,700 rpm fan), show it slowed and say so in `how` ("spin shown 1:60"). Never slow the numbers.
  73. - Sanity check the operating point against the public figure you wrote down in step 1. If you are off by more than about 20 %, fix the model, not the number.
  74. ### 6. Flow, heat and effects
  75. - `lab.flow({ paths, count, length, color, parent })`: streaks that ride along paths you build from the real flowpath (air through a duct, blood through a pump, water through a puck). Set `.speed` from the solver and `.opacity` from `lab.state.cut` so they show inside the cutaway. Colour by a computed quantity (temperature, pressure).
  76. - `lab.plume({ radius, length, dir, color: 'rocket' | 'jet', shocks })`: an exhaust with Mach diamonds; set `.power` from the solver.
  77. - `lab.sparks.emit(worldPos, n, speed)` and `lab.shed(mesh, v, w)` for breaks: sparks fall with gravity and bounce; a shed part becomes a rigid body that lands on the floor.
  78. ### 7. Modes (the kit does them; you set them up)
  79. - **Explode**: each `lab.add`/`lab.mesh` takes `explode: [dx, dy, dz]` in the parent's frame (metres). Move parts along their assembly axis, outer shells furthest, and keep the core in place. Nothing should cross anything on the way out.
  80. - **Cutaway**: `cut: { a, b, center, reach }` on the Lab. `a` and `b` are the directions of the removed region: `a = [0,0,1], b = [0,1,0]` removes the quarter toward the viewer and up (best for things with an axis); `b = a` removes a half. Section faces are drawn automatically for every closed solid, with a faint hatch.
  81. - **X-ray**: `xray: 'shell'` on outer casings turns them to glass with fine edges, so the core shows while it runs.
  82. - **Slow motion, labels, pause** come for free (keys S, L, Space). The interactive parts are mouse orbit, the slider and the buttons.
  83. - **Break it**: `lab.breakIt({ label, run(lab), reset(lab) })`. `run` changes the solver state (a blade released, a valve stuck, a seal blown) and the solver computes the consequence. Show it in the hero (`bad: true`) and with sparks, debris or shake.
  84. ### 8. Look at it like a critic (required)
  85. Render and READ every image you make. Use the scripts:
  86. ```sh
  87. node scripts/shot.mjs <name>.html out/review.png # the first look
  88. node scripts/shot.mjs <name>.html out/cut.png --js "lab.toggle('cut', true); lab.toggle('labels', true)"
  89. node scripts/shot.mjs <name>.html out/near.png --js "lab.setView({ az: 70, el: 8, dist: 0.8, target: [x, y, z] })"
  90. node scripts/shot.mjs <name>.html out/film --film 1,4,8,12,17,22,26 # film stills
  91. ```
  92. Do at least four review rounds. In each: whole view, cutaway with labels, exploded, two close ups of joints, and the film stills. Compare against real product photography of the machine in your memory: proportions, part count, materials, how light falls on it. List what is wrong, fix it, render again. Stop only when the list is empty. The shot script prints fps, part count and triangles; keep interactive frame rates above 30.
  93. ### 9. The film
  94. `lab.autoFilm({ runBeat, runSub, breakBeat, breakSub, sliderTo })` writes the standard 28 second story from your machine, in numbered beats with the editorial captions:
  95. 1. One sentence is the whole brief (the prompt bar types itself).
  96. 2. Claude builds the machine (parts fly in by assembly order while the counter climbs: "84 of 3,597 parts").
  97. 3. It runs (a cursor drags the slider; the hero number climbs from the solver).
  98. 4. Cut it open (section caps, labels with live values).
  99. 5. Take it apart (explode).
  100. 6. Break it (the cursor clicks the break button; the solver decides what fails).
  101. It loops: the last camera key returns to the first. For a custom film use `lab.film('name', { len, assemble, shots, events })`: shots are camera keys `{ t, az, el, dist, target, fov }`, events are `{ t, beat: ['07', 'Bold sentence.', 'Grey sentence.'], set: { cut: 1 }, slider: { id, to, dur }, cursor: { to: 'slider:id:0.8' | 'button:break' | [x, y], click: true }, do(lab) {} }`.
  102. Record (needs Node 18+, Playwright with Chromium, ffmpeg):
  103. ```sh
  104. node scripts/record.mjs <name>.html out/<name>.mp4 --music freepd:Classical/Easy_Lemon
  105. node scripts/record.mjs <name>.html out/<name>-portrait.mp4 --w 1080 --h 1350
  106. ```
  107. The page runs in film mode (`?film=1`): its clock only moves when the recorder steps it, so every frame is complete and the film is identical every take. The recorder guards every screenshot against the magenta frames a stalled headless GPU can return, and scans the finished film; it exits non zero if any frame is pink. Music from FreePD is CC0; credit the track anyway.
  108. ## Writing on screen
  109. The page is editorial, not a dashboard: a prompt bar, a serif title with an italic subtitle, one huge number with italic units and a thin bar, one line of supporting numbers, one slider. Write like a good caption: short, concrete, no hype, real units with a space (`338 kN`, `1,750 K`, `4.2 L/min`), thousands separated. Beat captions are a bold sentence and a grey sentence.
  110. ## What to say when you hand it over
  111. Give the path of the HTML file, the film command, the operating point the solver reaches against the public figure, and anything you simplified. Offer the next machine.
README.md · README · 204 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">Machine Skill</h1>
  2. <p align="center"><b>Describe any machine in one line. Claude builds the real thing, running on real physics.</b><br>A photoreal, interactive 3D simulation in one HTML file, plus the film to post it. An open source skill for Claude Code.</p>
  3. <p align="center">
  4. <a href="https://code.claude.com/docs/en/skills"><img src="https://img.shields.io/badge/Claude_Code-skill-141414?style=flat-square&logo=claude&logoColor=white" alt="Claude Code skill"></a>
  5. <a href="https://agentskills.io"><img src="https://img.shields.io/badge/Agent_Skills-compatible-141414?style=flat-square" alt="Agent Skills compatible"></a>
  6. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-141414?style=flat-square" alt="MIT license"></a>
  7. <a href="#requirements"><img src="https://img.shields.io/badge/three.js-0.170-141414?style=flat-square&logo=threedotjs&logoColor=white" alt="three.js 0.170"></a>
  8. <a href="#requirements"><img src="https://img.shields.io/badge/build_step-none-141414?style=flat-square" alt="No build step"></a>
  9. </p>
  10. <p align="center">
  11. <a href="https://airsup.ai/lab/skill"><img src="https://img.shields.io/badge/Live_gallery-airsup.ai%2Flab%2Fskill-141414?style=for-the-badge" alt="Live gallery"></a>
  12. &nbsp;
  13. <a href="#install"><img src="https://img.shields.io/badge/Install-npx_skills_add-e9e7e1?style=for-the-badge&labelColor=141414&logo=npm&logoColor=white" alt="Install"></a>
  14. </p>
  15. <p align="center">
  16. <a href="https://airsup.ai/lab/skill"><img src=".github/assets/hero.webp" width="880" alt="The launch film: one typed line becomes a turbofan that assembles part by part, opens up to about 340 kN of computed thrust, is cut open and throws a fan blade, then a rocket engine fires and burns through its throat."></a>
  17. </p>
  18. <p align="center"><sub>Every frame above is three.js in a browser, recorded with this repo's own <code>scripts/record.mjs</code>. Every number on screen is computed.</sub></p>
  19. ---
  20. ```text
  21. /machine a turbofan jet engine, the kind that pushes a widebody off the runway
  22. ```
  23. 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.
  24. Then one command turns it into a film for your feed.
  25. ## Quick start
  26. ```sh
  27. npx skills add AirsupHQ/machine-skill -g -a claude-code
  28. ```
  29. Then in Claude Code:
  30. ```text
  31. /machine a mechanical watch movement, the escapement ticking
  32. ```
  33. You get `watch.html`: open it, drag, cut, explode, break. To film it:
  34. ```sh
  35. node ~/.claude/skills/machine/scripts/record.mjs watch.html out/watch.mp4 --music freepd:Classical/Easy_Lemon
  36. ```
  37. ## Gallery
  38. Each machine was made from the single line under it. Click one to run it live.
  39. <table>
  40. <tr>
  41. <td width="50%"><a href="https://airsup.ai/lab/skill/turbofan"><img src=".github/assets/turbofan.jpg" alt="A high bypass turbofan on a ground run stand, cut open with red section faces and live labels"></a></td>
  42. <td width="50%"><a href="https://airsup.ai/lab/skill/rocket-engine"><img src=".github/assets/rocket-engine.jpg" alt="A full flow methalox rocket engine firing on a horizontal test stand"></a></td>
  43. </tr>
  44. <tr>
  45. <td><sub><b>Turbofan</b> · <i>a turbofan jet engine, the kind that pushes a widebody off the runway</i><br>Brayton cycle: about 340 kN at take-off, 83 % of it from the bypass. 3,597 parts. Break: throw a fan blade, and the solver computes the load the case must hold.</sub></td>
  46. <td><sub><b>Rocket engine</b> · <i>a Raptor style full flow rocket engine on a test stand</i><br>Chamber and nozzle solution: 2,462 kN and Isp 321 s at 330 bar, sea level, Mach 4.06 at the exit. Break: cut the regen cooling and the copper throat melts.</sub></td>
  47. </tr>
  48. <tr>
  49. <td width="50%"><a href="https://airsup.ai/lab/skill/refinery-pump"><img src=".github/assets/refinery-pump.jpg" alt="An API 610 overhung process pump with its motor and seal pot, cut open with red section faces and live labels"></a></td>
  50. <td width="50%"><a href="https://airsup.ai/lab/skill/compressor"><img src=".github/assets/compressor.jpg" alt="An API 617 barrel compressor cut open to show six impellers, diaphragms and return channels"></a></td>
  51. </tr>
  52. <tr>
  53. <td><sub><b>Process pump</b> · <i>a refinery process pump, API 610 style, cut open for plant training</i><br>Pump curve with the affinity laws, BEP, NPSH available against required, seal face leakage. Hover any part for what it does and what the operator checks. Break: drop the tower level and it cavitates.</sub></td>
  54. <td><sub><b>Compressor</b> · <i>a multistage centrifugal compressor for a refinery, cut open</i><br>Six stages on one map: polytropic head, stage pressure ratios, surge line, anti-surge control, a lumped surge model. Break: trip the downstream unit with the anti-surge valve stuck and it surges.</sub></td>
  55. </tr>
  56. </table>
  57. The pages are in [`examples/`](examples): each is one HTML file you can open from disk. More machines are coming; see [V2-IDEAS.md](V2-IDEAS.md), and send yours as a pull request.
  58. ## What you get
  59. | | |
  60. |---|---|
  61. | **The real machine** | Real proportions in metres, 15 to 40 named parts and thousands of solid pieces (blades, teeth, bolts), lathe turned solids, cambered and twisted airfoils, involute gears, routed pipes. A scale bar shows real size. |
  62. | **Real materials** | Physically based steel, titanium, Inconel, copper, brass, aluminium, paints, polymers, glass and sapphire, with measured reflectances, micro finishes (turned, brushed, cast), clearcoats and heat glow from the solver's temperatures. |
  63. | **A studio** | A softbox environment with black flags, a soft key shadow, contact shadow, ambient occlusion, bloom, a paper seamless or a night set. It looks like a product photograph before it moves. |
  64. | **Real physics** | A small solver per machine (Brayton cycle, rocket chamber and nozzle, slider crank and BMEP, torsional oscillator, Cp(lambda, beta), pump curves, Kienzle, Darcy) drives every motion and every number. "How it is computed" shows the equations. |
  65. | **Modes** | Explode, cutaway with solid section faces, x-ray, slow motion, live labels, pause, and a computed "break it". |
  66. | **A film** | `?film=1` gives a deterministic clock. One command records a 28 s film in numbered beats: you type one line, Claude builds it part by part, it runs, it opens, it comes apart, it breaks. Music bed included, magenta frame guard and pink scan built in. |
  67. ## Install
  68. Machine Skill is a standard [Agent Skill](https://code.claude.com/docs/en/skills): a folder with a `SKILL.md` at its root. This repository is that folder.
  69. | | Command | Installs to |
  70. |---|---|---|
  71. | **skills CLI**, for you | `npx skills add AirsupHQ/machine-skill -g -a claude-code` | `~/.claude/skills/machine` |
  72. | **skills CLI**, one project | `npx skills add AirsupHQ/machine-skill` | `.claude/skills/machine` |
  73. | **git**, for you | `git clone https://github.com/AirsupHQ/machine-skill.git ~/.claude/skills/machine` | `~/.claude/skills/machine` |
  74. | **git**, one project | `git clone https://github.com/AirsupHQ/machine-skill.git .claude/skills/machine` | `.claude/skills/machine` |
  75. Claude Code picks up new skills in a running session; if the `skills` folder did not exist when the session started, run `/reload-skills`.
  76. <details>
  77. <summary><b>Other agent hosts</b></summary>
  78. <br>
  79. - **Claude.ai and the Claude desktop app**: zip this folder and upload it under Settings, Capabilities, Skills. The pages run in any browser; recording needs a machine with Node and ffmpeg.
  80. - **Claude Agent SDK / API with skills**: mount the folder as a skill directory; SKILL.md is self contained.
  81. - **Codex, Cursor, other agents that read Agent Skills**: point them at `SKILL.md`. Everything else is plain files.
  82. - **No agent at all**: copy `kit/template.html`, fill the four sections by hand.
  83. </details>
  84. ## Usage
  85. 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.
  86. ```text
  87. /machine a hydroelectric Francis turbine
  88. /machine a Swiss lever escapement, slowed down so I can see the impulse
  89. /machine the gearbox of a 5 MW wind turbine, cut open
  90. /machine a steam locomotive's valve gear, and give me a 30 second video for X
  91. ```
  92. Three habits get the best machines:
  93. 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.
  94. 2. **Say what should move and what should break.** "Rev it until the valves float" tells the solver what to compute.
  95. 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.
  96. ## Record a film
  97. ```sh
  98. node scripts/record.mjs examples/turbofan.html out/turbofan.mp4 --music freepd:Classical/Easy_Lemon
  99. node scripts/record.mjs examples/turbofan.html out/turbofan-feed.mp4 --w 1080 --h 1350
  100. node scripts/record.mjs examples/turbofan.html out/stills --stills 3,9,14,19
  101. node scripts/pinkscan.mjs out/*.mp4
  102. ```
  103. 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:<Category>/<Name>` (CC0 tracks from [FreePD](https://freepd.com) 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.
  104. The launch film at the top was directed in a browser page, [`film/launch.html`](film/launch.html), that embeds a live machine page and steps it frame by frame.
  105. ## How it works
  106. - **[`SKILL.md`](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.
  107. - **[`kit/lab-kit.js`](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.
  108. - **[`references/solvers.md`](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.
  109. - **[`scripts/`](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).
  110. <details>
  111. <summary><b>The cutaway, in one paragraph</b></summary>
  112. <br>
  113. Every part is a closed solid with a double sided material clipped by two planes (a half or a quarter section). Where the planes open a solid, the camera sees that solid's back faces; the material's shader recognises them by casting the view ray against both planes, and draws them as the section face instead: plane normal, plane depth (written to the depth buffer so it occludes correctly), a freshly machined colour of the same material and a faint hatch. No cap geometry, any cut position, so the cut can sweep in live.
  114. </details>
  115. <details>
  116. <summary><b>Repository layout</b></summary>
  117. <br>
  118. ```text
  119. machine-skill/
  120. ├── SKILL.md what Claude reads
  121. ├── kit/
  122. │ ├── lab-kit.js the runtime (inlined into every page)
  123. │ └── template.html the page Claude starts from
  124. ├── references/solvers.md physics recipes with real constants
  125. ├── scripts/ shot, record, pinkscan, inline (+ lib: server, browser, guard, png)
  126. ├── examples/ the example machines, one HTML file each, and their posters
  127. ├── film/launch.html the launch film director page
  128. └── evals/evals.json prompts and what a good answer contains
  129. ```
  130. </details>
  131. ## Requirements
  132. | | Needed for | Notes |
  133. |---|---|---|
  134. | **Claude Code** (or any Agent Skills host) | building machines | |
  135. | **A browser with WebGL 2** | running the pages | Desktop Chrome, Safari, Firefox, Edge. Phones work with a lighter load. |
  136. | **Node 18+, Playwright, ffmpeg** | screenshots and films | `npm i -D playwright && npx playwright install chromium`; ffmpeg from your package manager. |
  137. ## Limits
  138. - **It builds machines.** Mechanisms, engines, instruments, devices. People, landscapes and maps come out weaker.
  139. - **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.
  140. - **Real parts, not a CAD export.** Geometry is procedural three.js; it is accurate in proportion and part count, not to manufacturing tolerance.
  141. - **Heavy pages want a real GPU.** About 600k triangles with shadows, AO and bloom runs at 60 fps on a recent laptop.
  142. ## Siblings and credits
  143. - **[Factory skill](https://airsup.ai/lab/factory-skill)**: the same idea for whole factories. Describe a line in one sentence and Claude builds it as a live discrete event simulation.
  144. - **[Anatomy](https://github.com/wheresryan22/anatomy)** by Ryan (@wheresryan22) showed how good a one line machine skill can be. Its numbered beat film inspired ours.
  145. - **[airsup.ai/lab](https://airsup.ai/lab)** is where these machines come from: more than 50 simulations built with Claude Opus 5.5.
  146. - three.js (MIT), Instrument Serif, Inter and JetBrains Mono (OFL), music from FreePD (CC0).
  147. ## License
  148. [MIT](LICENSE) © 2026 Airsup · [airsup.ai/lab](https://airsup.ai/lab)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.