Stop shipping AI slop video: a hands-on guide to motionmaxxing

The motionmaxxing hero frame: the word motionmaxxing with measurement overlays — blue guide lines, a 0 px marker, and a softLand ease annotation on a dark glitchy ground — Your keyframes get a face rating: the motionmaxxing hero frame, made with the skill’s own runtime. Artwork: motionmaxxing project (Apache-2.0).

Every AI-generated video has the same tells: a brand label tucked in a corner, a headline held on the left, a card floating on a flat colour, and a fade between every beat. motionmaxxing (Tejashmakwana/motionmaxxing) is an agent skill that exists to kill those defaults — past 300 GitHub stars, Apache-2.0 — built not from opinions but from frame-by-frame measurement of 53 professional motion moments. It turns Claude Code, or any agent that reads a SKILL.md folder, into a motion designer with opinions, and then it checks its own work with scripts instead of telling you it came out well. This tutorial installs it, renders your first piece, and shows how its quality gates catch the slop.

What you’ll need

Node 22+, Python 3, FFmpeg, and Google Chrome — the four hard requirements. Nothing else is installed system-wide.
An AI coding assistant — Claude Code is the documented path; any agent that reads a SKILL.md folder works, with shell access so the scripts can run.
Optional: an ElevenLabs key (ELEVENLABS_API_KEY) — only if you want voice-over, sound effects, and music. Plenty of films are better silent.
Optional: the Codex CLI with image generation — used for generating surface plates (backgrounds and textures), never for text, logos, UI, or people.

1. Install the skill

The README’s own install lines. For Claude Code:

git clone https://github.com/Tejashmakwana/motionmaxxing ~/.claude/skills/motionmaxxing
bash ~/.claude/skills/motionmaxxing/install.sh        # checks the requirements; installs nothing system-wide

Checked out elsewhere: ./install.sh links it into your skills folder. Flags: --dir PATH for another skills folder, --copy to copy instead of symlink, --force to replace an existing install. Other agents: point the agent at the folder — the skill is just a SKILL.md plus scripts — and give it shell access.

2. Check your machine

Before anything renders, ask the toolbox what you actually have:

bash ~/.claude/skills/motionmaxxing/scripts/providers.sh   # JSON: chrome, ffmpeg, key, codex, disk. Never installs anything.

The output is JSON: whether Chrome and ffmpeg are reachable, whether an ElevenLabs key is set, whether the Codex CLI can generate images, and how much disk you have. No Chrome, no render — the skill renders frame by frame through headless Chrome and stitches with ffmpeg. This is the step that fails silently later if you skip it now.

3. Render your first film

In Claude Code, run /motionmaxxing or ask in plain language. The skill triggers on any request to make, plan, storyboard, fix, or critique a motion graphic. Three ways in, straight from the README:

From a URL — the skill captures the site’s brand first (brand.mjs: brand.json, BRAND.md, board.png, logo, fonts, screens):

/motionmaxxing make a 20s launch film for https://example.com. I want to see the idea and the storyboard before you build.

A single moment — the cheapest way to see the craft:

/motionmaxxing a 6 second kinetic-type sting for our brand: the one line "Ship it" with real 3D on the mark. Silent is fine.

Rate and repair — bring your own slop:

/motionmaxxing here is draft.mp4 and its index.html. Rate it slop, mid or maxxed, run the gates, tell me what fails, and fix it.

Every run follows the same 10-step protocol: toolbox and taste → brand → one true thing → the idea → world and time (STORYBOARD.md) → hardest beat first → look honestly → sound to picture → deliver. The agent shows you the idea and the storyboard before it builds. When a gate fails, it fixes in a fixed order — a failing gate is fixed, not argued.

4. Read the gates

This is the part most “video skills” skip: scripted quality checks with numbers. A gate that fails gets fixed; two gates have no script, and the agent has to say so.

The page-chrome lint doing its job: every default the skill forbids, caught by geometry. Artwork: motionmaxxing project (Apache-2.0).

Gate	Pass condition	Computed by
G0 render exists	Decodes, is not blank, the picture moves, the length matches the plan, audio present when planned	`look.py`
G1 proof readable	UI text at least 0.04 H; fragment at least 0.55 W or cropped by the frame; lit, in a world	by eye on the contact sheet
G2 no empty frame	No run of more than 3 consecutive flat frames	`look.py`
G3 end card short	End hold at most 1.4 s; the final shot at most 25% of the film	`look.py`
G4 one hero per frame	Two panels only if one has twice the area of the other, or the camera moves between them	by eye on the contact sheet
G5 no page chrome	No corner labels, counters, timecodes, header/footer bars, kicker over a headline, left headline beside right-side media, progress bars, letter-typed headlines, or vibe-coded UI cards	`lint.mjs`

G5 is the signature move: page chrome — a brand name in a corner, a “02 / SPEAK” counter, a timecode — was the strongest signal in the skill’s slop autopsy that nobody had decided anything. The lint catches it by geometry and typography. G2 is the mewing rule for your frames: in the measured 3–7 s pro moments, something moves on about 99% of frames, and more than 3 flat frames in a row fails.

5. Steal the measurements

Most “motion design skills” are a list of opinions. This one started with a measurement: 53 frame-accurate pro moments decoded by 6 parallel AI analyst agents (reviewed by a human) into about 150 designer rules, each written as WHEN / DO / BECAUSE with evidence. About 4,300 distinct moves were seeked frame by frame — that gave 12 measured eases, named and reusable in the runtime (M.ease.softLand, snapSettle, accelExit, …):

The 12 measured eases of motionmaxxing plotted from 0 to 1, each with its typical length in frames, its share of measured moves and when professionals use it — The 12 measured eases: each curve decoded frame by frame from professional motion moments, with when the pros actually use it. Artwork: motionmaxxing project (Apache-2.0).

The numbers worth stealing, even if you never install the skill:

The median move is 10 frames (0.33 s). Entries run 11–12 f, opacity 6 f, blur 7–8 f. If your keyframes are longer, you are animating in slow motion.
Landings decelerate, leavings accelerate. 58% of landings are ease-out; 37% of leavings are ease-in. The same object on the wrong curve reads as floaty or thrown — the README calls this single rule most of the difference between “animated” and “directed.”
Elements arrive by moving, not by fading. The corpus has 3,392 transform entries against 584 opacity fades. Pros cut on motion, not on rest: 96% of moments use hard cuts, about 20 per moment.
Nothing grows from zero. Things arrive decelerating from larger than life — logos crash in from about 3.5x — or move in from the edge. Overshoot is rare (under 9% of moves) and late: a slow lean past the mark, not a fast spring.
The ending gets smaller. A resolved end hold of 0.6–1.4 s. Anything longer is overstaying, and G3 fails it.

The runtime is honest engineering too: runtime/motion.js is one plain <script> on top of vendored GSAP with no build step, and every frame is a pure function of time — seek-safe, so jumping to any frame equals playing to it (Motion.selfTest proves it, canvas pixels included).

What you built

A skill installed in your agent’s skills folder, a machine check you can re-run any time, and a repeatable protocol: brief → brand → idea → storyboard → hardest beat first → scripted gates → sound → deliverables. A finished run leaves you four files: film/final.mp4 (the film), film/index.html (the editable source — plain HTML plus the Motion runtime, reproducible frame by frame), film/STORYBOARD.md (the plan and the beat table), and film/NOTE.md (the honest account: what is real and what is illustrative or generated, the G0–G5 numbers, what you would still improve). The skill’s own rule: the agent never certifies the film as good.

Honest limitations

Early release. The badge says it plainly: it works end to end on the author’s machine and has been used on a handful of real briefs, but it has not had a wide test. The full limits live in docs/KNOWN-LIMITS.md.
The lint is a lead, not a verdict. It cannot see text inside a canvas or an image, and G1 and G4 are judged by eye on the contact sheet.
Music is the weakest automation. ElevenLabs music does not always hit tempo or length; the sound-effect normaliser can corrupt very short clips; and WebGL renders run at about 7–11 fps.
Small rough edges. look.py treats show and hide events as cuts; fetch_logo.mjs can return a header ribbon instead of the mark.
The headline evidence is thin. The author’s blind A/B rounds went 9 of 10 for the with-skill film — but it was one rater. The README itself says to read it as a signal, not a benchmark.
Watch the vendored licenses. The skill is Apache-2.0, but bundled third-party components keep their own licenses: GSAP 3.12.5 under the GreenSock Standard License (which is not open source), Three.js r186 and opentype.js under MIT, Inter under SIL OFL 1.1. See NOTICE before shipping commercially.
Your agent is the bottleneck. The skill supplies the protocol, the measurements, and the gates — the taste and the error recovery still come from the coding assistant you plug in.