oil-motion: an Agent skill that turns AI-generated video into scroll- and pointer-driven web animation

The problem oil-motion targets: AI video that arrives unusable

A generated video clip is not an animation system. It has dead frames at the head and tail, near-duplicate frames in the middle, flicker where the model changed its mind about a logo, and a resolution chosen for the model rather than for the box it will occupy on the page. Wiring that file to a scroll position gives you sticky, jittery, out-of-sync motion. oil-motion exists to sit between the generator and the browser and fix that gap.

The README frames it as an "Agent general interactive animation Skill": you describe what the animation should express, what assets you have, and what input it should follow, and the Agent handles generation, inspection, compression and the front-end wiring. The intended audience is therefore narrow and specific. It is for people building product explainers, character interactions, operation demos and section transitions who want the motion to respond to scrolling, dragging, pointer position, touch or device orientation, but who do not want to hand-author frame-by-frame animation or manage a video pipeline themselves. If you are comfortable writing your own requestAnimationFrame scrubber over an MP4, this project is not aimed at you.

Key frames first, then interpolation, then a scrubbable asset

The mechanism the README describes has three stages, and the first one is the interesting design decision. Before any video is generated, the Agent confirms the key frames: the states that must stay accurate, such as a product intact, its parts exploded, and the final disassembly. These are generated and inspected for identity, structure, logo, composition and style consistency. The stated reason is that generating the whole clip in one pass lets the model drift on structure, proportions or the end pose. Pinning the endpoints first gives the interpolation a defined start and finish.

Only then does the video model fill in between those frames. Limb rotation, product deformation, material changes and occlusion happen here, because the README argues those are not convincing when faked with front-end translation or scaling. Everything else is deliberately kept out of the model: displacement, scaling, cropping, playback speed, follow damping and maximum rotation speed are handled by code, which the README says is more stable and easier to tune later.

The third stage converts the result into a controllable web asset. Frames are reviewed individually, head and tail pauses are trimmed, near-duplicates removed, flicker and structural changes flagged, and the asset is compressed against the size it will actually occupy on the page. At runtime the browser does not generate anything; it seeks or plays within an already prepared sequence. That is what makes the response to input immediate and repeatable.

One structural detail worth noting: the README separates input source from playback mode. Scroll, mouse and state changes are inputs, not playback decisions. An input value can map continuously to progress, trigger a normal-playback transition, or let the animation run on its own clock. Conflating those two is a common source of animation that feels wrong at the edges.

Choosing between baked MP4, Alpha WebP atlases and green-screen keying

The README gives a table of asset forms and the conditions that select them, and the Agent is expected to pick one primary form rather than implement two. For scene narrative, camera movement, ambient light and ground contact, the choice is a baked-scene all-keyframe MP4, because background and subject are generated in the same video, continuity is best and there is no keying risk. For transparent reuse that is small, looping, two-dimensional or frequently jumped between, an Alpha WebP atlas is used, with keying done at build time so random access stays stable. For transparent reuse that is large, long-timeline or one-dimensional scrolling, a green-screen all-keyframe MP4 with real-time WebGL keying is preferred, for higher compression without a large atlas consuming memory.

That third row is the one that deserves scrutiny. Real-time chroma keying in WebGL moves cost from download to the GPU and introduces edge quality as a runtime variable. The README's own quality checklist includes checking that transparent edges are clean and that interior white areas and thin lines were not keyed away, which suggests this is a known failure surface rather than a solved problem. If your subject has white details against a green screen, budget time for that check.

The README also states that the Agent runs a budget script first and adopts the most suitable primary form directly, without handing the choice to the user. That is a real trade-off: you get a consistent pipeline, and you give up the ability to say "just give me the MP4."

Install and first run: what the commands actually do

There is no npm package to import and no Python library to call. Installation means registering the skill with an Agent host. The README's primary instruction is to tell the Agent to install the skill from the repository URL; the GitHub installation section also gives a CLI form:

npx skills add oil-oil/oil-motion

After that, the README says the host must reload the skill. There is no version pin in the README, so if you need reproducibility you will have to pin the commit yourself.

The first real use is a prompt, not a function call. The README's quick-start examples are all natural language. This one asks for a two-image product animation driven by scroll, with a heavier asset on desktop and a lighter one on mobile:

使用 $oil-motion，把这两张产品图制作成随页面滚动逐步展开的动画。
桌面端的展示区域较大，需要保持清晰；移动端使用较轻的资源。

If you have assets but no motion concept, the README suggests asking for three directions first, each describing what it expresses, how it follows scroll, and what it costs to implement, then confirming before any key frames or video are generated. For pointer-following characters, the README's example specifies the requirement directly: respond promptly, limit rotation speed, and do not flicker or twitch on fast reversals.

Before the first generation that touches an external service, the Agent walks you through configuring an API key. The README states the key is entered on a local configuration page and stored in the system credential store, with ordinary config holding only a reference. It requires the keyring dependency from scripts/requirements.txt, and states that when the backend is unavailable it does not fall back to saving plaintext. The configuration page needs Node.js 22.18+ and a working system credential service; the README says existing credentials in the runtime environment can be reused and that keys should not be pasted into chat. Full entry points for install, status check, opening the page and running with credentials are in references/api-key-setup.md.

The Pilot gate and the hash check that can stop a build

The most concrete control in the README is the Pilot step. Before mass production, the Agent completes a first-screen Pilot: one pair of key frames, one short video, mounted into a real page for acceptance. Only after that passes is an approval file written, carrying an artifact hash. Later segments that lack an approval file, or whose first and last frame SHA-256 values do not match, cause the generation script to block before it goes online.

This is a genuinely useful constraint. It means an accidental asset swap cannot silently produce a segment that no longer joins to its neighbours, and it means generation spend is gated on a human having looked at a real page rather than a contact sheet. The cost is friction: replacing a key frame invalidates the approval and you redo the Pilot. The README does not document a way to waive the check, and it does not document rollback of an approval file. If your workflow involves iterating on artwork after the first approval, plan for that re-approval loop.

The README is also explicit about the boundary of automation. Program-side processing can handle slight drift, colour differences, duplicate frames and encoding problems, but it cannot fix a wrong motion design. When the subject's structure, limb relationships or motion direction are wrong, the key frames or the generated video have to be redone. That is a design-stage failure, not a processing-stage one, and no amount of compression tuning will rescue it.

Where oil-motion is the wrong tool

If your animation is entirely transform work (a card that slides, a chart that grows, a parallax layer), oil-motion adds a video generation dependency, an API key, a credential store and a Pilot approval loop to solve a problem that CSS transitions and an IntersectionObserver already solve. The README's own division of labour supports this: displacement, scaling, cropping, playback speed, damping and rotation limits are handled by code, not by the model. Only the parts that need genuine frame-to-frame change (limb rotation, deformation, material change, occlusion) justify the pipeline.

A second wrong fit is a team that wants to own the runtime. The README says the Agent delivers interaction code, a preview page showing the full picture, the current frame and the interaction input, and configuration files for assets, interaction range and loading. Those are deliverables, not a supported public API. There is no documented interface contract for the generated code, and the README points anyone modifying generation parameters, asset processing or runtime logic at SKILL.md and references/ rather than at an API reference. If you need a stable library boundary, this is the wrong shape.

A third: environments without a system credential service. The README states plainly that the keyring backend being unavailable does not degrade to plaintext storage, and that the configuration page needs Node.js 22.18+ plus a working credential service. On a locked-down CI box or a minimal container, that is a hard stop before you generate anything. Pure local processing needs no key, but anything calling a generation service does.

How it compares with GSAP ScrollTrigger and Lottie

The closest conventional alternative is GSAP with ScrollTrigger. The difference is the source of the frames. ScrollTrigger animates properties of elements you already have: it interpolates transforms, opacity, clip paths and timeline positions, and it is deterministic, debuggable and small. oil-motion instead produces the frames themselves with a video model and then maps input to a position within that prepared sequence. That buys you motion a property tween cannot express, such as a product physically disassembling with correct occlusion, at the cost of a generation service, a key, a review pass and a compressed asset whose quality you have to verify at the size it will actually render. If your motion is expressible as properties, ScrollTrigger is the better answer and oil-motion is overhead.

The other comparison is Lottie. Lottie plays vector keyframe animation from a JSON file authored in a design tool, and it scales cleanly and stays small. oil-motion's assets are raster sequences (MP4 or WebP atlas), so they carry photographic and material detail that vector shapes cannot, but they do not scale losslessly and they consume more bytes. The README's compression step is explicitly tied to the rendered display size, which is the tell: this pipeline assumes a raster asset whose quality is a function of the box it lands in. Choose Lottie when the artwork is vector and resolution-independent; choose oil-motion when the motion has to come from generated video.

Neither comparison is a criticism of oil-motion. It occupies a different slot: it is a production pipeline with an Agent as the operator, not a runtime library with a documented API.

Editorial conclusion

Adopt oil-motion if you already work through an Agent that can run shell commands and you need scroll-scrubbed or pointer-following motion that a video model has to produce, because the value here is the pipeline (key frames, frame review, resource budget, hash-gated approval) rather than a runtime library. Do not adopt it if you want a JavaScript package you can npm install and reason about on your own, if you have no API key for a generation service, or if your animation is pure transform work that CSS and a scroll listener already handle. Before committing, verify three things: that your Agent host can execute the bundled scripts, that your machine has Python, FFmpeg and a working system credential service for scripts/requirements.txt (the README states there is no plaintext fallback), and that the first Pilot approval file and its SHA-256 frame hashes survive your own asset replacement, since a mismatch blocks generation before any network call.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. oil-oil/oil-motion on GitHub
4. README