Oil Motion skill
A skill for Claude Code and Codex that turns AI video and frames into web animation driven by scroll, cursor, touch or device tilt
- 2,672 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Uses a paid ZenMux key kept in the system store and sends your images and prompts to an outside generation service
- Runs Python and TypeScript scripts, ffmpeg and a local key-entry page, and writes asset files and code into the project
- Every generation request costs money, so a batch without your approval of the pilot clip is ruled out by the skill's instructions
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/oil-motionDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Uses a paid ZenMux key kept in the system store and sends your images and prompts to an outside generation service
- Runs Python and TypeScript scripts, ffmpeg and a local key-entry page, and writes asset files and code into the project
- Every generation request costs money, so a batch without your approval of the pilot clip is ruled out by the skill's instructions
This is third-party code. Review the repository files before installing.
What it does
Oil Motion carries an animation from idea to a working page. First the agent records the intent in source/concept-contract.yaml: what should move, which gesture drives it (scroll, pointer, drag, touch, orientation, audio, data or state), who owns the background and which time mode applies: frame scrubbing, segment playback or autonomous playback. From the contract it derives the plan source/motion-brief.yaml, the timeline build/timeline.json and the budget build/motion-budget.json. Then the agent generates key frames and the video segments between them through ZenMux. Before mass generation it makes a pilot clip on the real page, and only after review is an approval file with an artifact hash saved. Scripts then clean the video: they trim pauses, drop repeated frames and compress for the actual display size. The motion_budget.py script picks one of three formats: video with a baked-in background, a transparent WebP atlas, or green-screen video that the browser keys out through WebGL. The skill also works with ready-made clips and sprites: it then starts with analysis and skips generation. The output is a page with code that maps a gesture to a timeline position, the asset files, a preview page that shows how it works and a configuration. For simple transitions, Lottie, SVG and CSS animations the skill is not needed.
Who it is for. For web developers and designers who need interactive scenes: a product that unfolds on scroll, a character that follows the cursor, a camera move between scenes.
Good fit when
- A product should unfold into an exploded view as the page scrolls, with the object itself changing, which CSS or SVG cannot do
- A character or pet should follow the cursor with its gaze without jerking on a quick reversal
- You need a through-scene: the camera moves from a city panorama into a chip across several stitched video clips
- You have a green-screen clip or a sprite sheet and need to turn it into an asset controlled by a gesture: cleaning, keying, compression
- A 360-degree product turntable controlled by dragging or by tilting a phone
Not a fit when
- You need interface transitions, button feedback or layout animation: they are simpler in CSS, JS, SVG, Lottie or real-time 3D
- You need to cut a standalone video or get a single illustration: those tasks are outside the skill
- You do not want to pay for generation in ZenMux: without ready-made video and frames you need a key and paid requests
- The machine has no Python 3.10, Pillow, ffmpeg and ffprobe, and you cannot install them
Example request
Use oil-motion: turn these two sneaker photos into an animation where the shoe breaks into parts as the page scrolls. Large on desktop, a lighter asset on mobileLimitations
- Generation needs a ZenMux key in the ZENMUX_API_KEY variable. By default the openai/gpt-image-2.5-flare model makes frames and the minimax/minimax-h3-max model makes video. Requests are paid: the author requires a pilot clip and user confirmation before a batch. A ready video and frames need no key.
- The deterministic part needs Python 3.10 or newer, Pillow, ffmpeg and ffprobe. The key-entry page needs Node.js 22.18 or newer.
- The key is kept in the system store: macOS Keychain, Windows Credential Manager or Linux Secret Service, which needs secret-tool, the session D-Bus and an unlocked service. The author ran native verification only on macOS.
- An old ~/.config/oil-motion/config.json with a plaintext key is read by the scripts but is neither migrated nor deleted by them.
- The project text and reference files are in Chinese, and only the main README has an English version.
- For 2D control (turning both horizontally and vertically) you need frames along both axes: a single back-and-forth video is not enough.
How to disable. Remove the skill from the agent's skills directory: deleting the oil-motion folder is enough. The key in the system store is removed by hand in Keychain, Credential Manager or Secret Service under the name oil-motion/zenmux/default. The project's source/ and build/ folders with assets are deleted separately.
FAQ
Do I need a key if I already have a green-screen clip or a sprite sheet?
No. The key is only for generating key frames and video. For ready materials the skill starts with analysis and works locally, with no requests to ZenMux.
Which asset format will the skill choose?
motion_budget.py makes the choice. Video with a baked-in background is used when camera, light and ground contact matter. A transparent WebP atlas suits small, circular and 2D scenes with random access. Green-screen video keyed out through WebGL is chosen for long one-dimensional scrolls where an atlas would take a lot of memory.
What is the pilot clip before a batch?
The agent makes a pair of key frames and a short video, mounts them on the real page and, once accepted, writes an approval file with an artifact hash. If the file is missing or the SHA-256 of the first and last frames does not match, the generation script stops before any network request.
How is the ZenMux key stored?
You enter the key yourself on a local link served by scripts/credential-ui, and it is saved in the system store. The generation scripts get it only through profile.ts run default --, so it does not appear in command arguments, files or output.
How do the time modes differ?
In scrub mode the gesture position maps to a frame: the gesture stops, the frame freezes. In segment-play mode the gesture picks the adjacent state and the segment plays over time, and a reverse gesture unwinds from the current frame. In autonomous mode time runs by itself and the gesture only starts, pauses or switches.
Discussion
No questions or reviews yet.
Related
SkillsA skill for building premium scroll-driven websites on a real design standard: typography, rhythm, depth, motion and in-browser verification
A skill that builds a landing page where scrolling flies a camera through a generated 3D world
A motion design skill for agents: timing, easing, choreography and Disney animation principles applied to UI
A skill for Claude Code and other agents that builds websites directed like films: art direction before code, local CLI asset generation and an anti-slop linter
Motion.dev Animations Skill
motion-dev-animations-skill
A Claude Code skill for Motion.dev, the successor of Framer Motion: 120 fps web animation, spring physics, scroll animation
Creative coding skills for Claude Code: motion, micro-interactions and visual systems for web, Android and Apple
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Oil Motion (this entry) | no | 2,672 | |
| Scroll Video Website Skill | no | 58 | turns an existing video into a site with frame-by-frame scroll |
| scroll-world | no | 10,396 | builds a landing page with a camera flight through a generated 3D world driven by scroll |
README in short
The repository's main page is in Chinese with an English version: the skill's purpose, a demo video, installation, scope, the list of animations it makes, a three-step principle (key frames, continuous motion, browser assets), a table of three asset forms, a quick start with three sample requests and a list of deliverables. The repository holds Python and TypeScript scripts, reference material for each stage, templates and a sample manifest, runtime assets and tests.
README badge
Original SKILL.md
--- name: oil-motion description: "把 AI 生成或已有的视频、序列帧变成随滚动、指针、拖动、触摸、设备方向、音频、数据或状态变化的网页动画：设计动作方向，生成关键帧与视频，整理成图集或视频，编译时间轴并接入运行时。用户需要角色转向、产品拆解、镜头穿越、一镜到底转场，或要清理、抠色、补帧、压缩绿幕视频与雪碧图时使用。不用于纯 CSS、JS、SVG、Lottie 或实时 3D 就能完成的界面过渡与微交互（交给普通前端实现），也不用于独立成片剪辑、单张配图或静态页面。" --- # Oil Motion 把用户的交互意图转换为可验收的动画素材、时间轴清单和网页运行时。AI 生成负责肢体、结构、材质、遮挡等语义变化；程序负责输入映射、播放控制、媒体处理和性能。 确定性流水线需要 Python 3.10+、Pillow、ffmpeg 和 ffprobe： ```bash OIL_MOTION="<当前 SKILL.md 所在的绝对目录>" python3 -m pip install -r "$OIL_MOTION/scripts/requirements.txt" ``` 关键帧与视频默认通过 ZenMux 生成，模型写在 `image_job.py` 与 `video_job.py` 中；只有模型无法完成目标或用户明确指定时才更换。已有视频或序列帧时从分析开始，不调用生成服务。 ## 首次配置 第一次调用生成服务前检查凭据；纯本地处理不需要 Key： ```bash node "$OIL_MOTION/scripts/credential-ui/src/profile.ts" status default node "$OIL_MOTION/scripts/credential-ui/src/profile.ts" setup default ``` 退出码 0 直接继续；2 表示缺失，此时运行 `setup` 并把返回的本机链接交给用户亲自填写。所有生成命令都通过 `profile.ts run default --` 执行。依赖安装、退出码含义和安全边界见 [references/api-key-setup.md](references/api-key-setup.md)。 ## 四个唯一事实源 每项信息只保存在一个位置，其他文件引用它，不复制： 1. `source/concept-contract.yaml`：用户明确要求的对象、视觉、交互和连续性。 2. `source/motion-brief.yaml`：由合同派生的关键帧、片段和生产计划。 3. `build/timeline.json`：成片的实际帧率、段落边界、停帧和播放曲线。 4. `build/motion-budget.json`：交付格式与运行时控制器的自动选择结果。 ## 主流程 ### 1. 锁定用户意图 用户只有模糊目标时，先读 [references/concepts.md](references/concepts.md)，给出最多三个真正不同的方向；要求已经明确时直接写 Concept Contract。 需要外部案例启发时，按表达目的选读 [references/motion-patterns.md](references/motion-patterns.md)。先分清哪些变化属于素材本身、哪些只是容器编排或 UI 状态，只有前者进入生成流程。