# OpenMotion: recreate and make motion videos with your agent (nexu-io/openmotion) — skill card for AI agents

> AgentGid skill card. Checked on 2026-11-13 against commit 7b4badb (version 0.6.3).
> Every fact comes from the pack's own files at that commit. Numbers marked "as reported" are the author's.
> Human page: https://agentgid.com/skills/nexu-io/openmotion/

> Note: the pack has changed since this check; re-read its files before relying on details.

## Explain it to a non-programmer
Your AI assistant becomes a video maker. Give it a reference video or an idea, and it builds an editable motion-graphics video. The video opens in a local editor (Studio) where you can change it by hand, and you get an MP4 when you ask. It comes with a local app, five main skills and three optional ones.

## Who it is for
- You saw a motion video (a product launch, a brand film) and want one like it for your own product
- You want an original explainer, product demo or brand film made from your topic and product material
- You have an editable video template and want your text, logo and colours put into it
- You use Codex, Claude Code, DeepSeek Harness or WorkBuddy, or another assistant that can connect a local MCP server
- Not for: You need live action, talking heads or AI footage recreated: the recreation workflow covers motion graphics only
- Not for: You want only a quick ready video file: the default result is a project open in the editor, and an MP4 only when you ask
- Not for: You cannot run Node.js and a local app on your computer: the skills need the OpenMotion app to do the work

## What it is
- Kind: knowledge, scripts
- License: Apache-2.0
- Repository: https://github.com/nexu-io/openmotion

## What it does
- Five main skills split the work: recreate a reference video, make an original film, fill an editable template, turn a video into a reusable template, and make scoped edits, previews and exports
- The assistant reads your workspace first (README, brand files, logos, screenshots) and uses it as the film's content
- Videos are HTML, CSS and JavaScript scenes; the same project opens in Studio and renders to MP4
- The assistant works through eleven local MCP tools: find templates, create and read projects, edit with a revision check, import media, preview, export, restore versions
- A recreation is exported and measured against the reference frame by frame with a bundled script before delivery
- Motion.md: a Markdown file that records a video's shot order, timing, transitions and replaceable assets
- Never cuts: Facts: the skills tell the assistant not to invent prices, claims or other missing facts, and to say plainly where a result falls short

## Skills
| Skill | Call | Changes code? | In plain words |
|---|---|---|---|
| openmotion-recreate | plain language ("Make one like this" plus a link or a video file) | yes | Rebuilds a reference video as your own editable film, with your copy, brand and assets |
| openmotion-director | plain language ("Make a motion video about ...") | yes | Plans and makes an original motion video on your topic, or reviews one you already have |
| openmotion-template-to-video | plain language (pick a template, then ask to make a video from it) | yes | Makes a video from an editable template, unchanged or with your text, brand and assets |
| openmotion-video-to-template | plain language ("Turn this video into a reusable template") | yes | Rebuilds a reference video as a template you can fill again and again |
| openmotion-production | plain language (edit, preview or export an existing project) | yes | Does the routine work on a project you already have: change text, colours or timing, swap music, preview, fix, export |
| openmotion-brandkit | plain language (optional library skill) | no | Writes a BRANDKIT.md and, if asked, a MOTION_DESIGN.md from your brand material |
| openmotion-design-remix | plain language (optional library skill) | yes | Puts your words into one of six ready motion pieces, keeping their timing and movement |
| openmotion-presenter-story | plain language (optional library skill) | yes | Recipes for videos where a person talks to camera, with captions, screen recordings and motion around them |
| motion-director, motion-production, motion-recreate, motion-template-to-video, motion-video-to-template, reference-video, openmotion-reference-video, brandkit, motion-design-remix, presenter-story | old names only | unclear | Compatibility entries for old names; they point to the main skills |

### openmotion-recreate
- Asks for: A reference video: a link or a local file
- Asks for: Your product material in the workspace (README, logos, screenshots, brand colours and fonts)
- Asks for: What should change, if you know: wording, brand, images, pacing, duration
- Gives: An editable OpenMotion project, open in the editor
- Gives: The reference's soundtrack kept and re-timed, unless you ask for silence
- Gives: A short reply: what changed, which assumptions it made, any limit you would notice
- Say: "Use OpenMotion to recreate this video for our product: <link>"

### openmotion-director
- Asks for: Your topic, audience and the one message
- Asks for: Product facts and material
- Asks for: Format: where it will be published
- Gives: A creative plan and action script, if you ask for the concept only
- Gives: A short test clip of the riskiest part before the full film
- Gives: The full editable project, open in the editor
- Say: "Use OpenMotion to make a 30-second product demo video from our README"

### openmotion-template-to-video
- Asks for: A template: from the library, a project folder or a ZIP
- Asks for: Your replacement text, logo and images
- Gives: The template open in the editor, unchanged or edited
- Gives: Checks recorded in the copy's TEMPLATE.md
- Gives: An MP4 only if you ask for a video file
- Say: "Use OpenMotion template <name> with our logo and this headline"

### openmotion-video-to-template
- Asks for: A reference video: a link or a file
- Gives: A template folder or ZIP with local assets
- Gives: A preview and a cover
- Gives: TEMPLATE.md: what can be changed and where it still differs from the original
- Say: "Use OpenMotion to turn this video into a reusable template"

### openmotion-brandkit
- Asks for: Your brief, brand guide, logo files, product screenshots, reference links
- Gives: BRANDKIT.md: brand facts, approved wording, logo rules, colours and type, assets with sources, what may change
- Gives: MOTION_DESIGN.md when a reusable motion language is needed
- Gives: A list of assets, sources and open choices
- Say: "Use openmotion-brandkit to prepare a Brandkit from our brand folder"

## Know before installing
- It is a whole local app, not only text files. The skills need the OpenMotion app (MCP server, Studio, renderer); installing the skills alone does not install it.
- Usage data is sent to the makers' PostHog project by default. Turn it off in Studio (Privacy settings → Share usage data) or with OPENMOTION_TELEMETRY=0 or DO_NOT_TRACK=1.
- A background service keeps running after you close the launcher.
- Generating new media (images, video, music, voice) is billed to your own provider accounts; using your own footage needs no media API.
- Keep your projects and keys outside the checkout; MOTION_DATA_DIR sets where projects live.
- Reference videos from other brands are only for study: the templates and remix pieces keep some upstream artwork, and third-party media keep their own licenses.

## Install (official commands)
- Any local agent (from source): `Read https://github.com/nexu-io/openmotion/blob/main/install.md and follow the instructions to install and connect OpenMotion in the current agent.` — A prompt you paste into your agent. It clones main, runs npm ci, builds Studio, starts the app and connects MCP. Read install.md first.
- From source (terminal): `git clone --depth 1 https://github.com/nexu-io/openmotion.git` && `cd openmotion` && `npm ci` && `npm run build:studio` && `npm start` — Open the studioUrl or previewUrl it prints, then Template library.
- Codex (plugin, from the checkout): `bash scripts/install-motion.command` — Run from a normal terminal. Registers a local marketplace (openmotion-local) and the openmotion plugin, which loads skills/ and .mcp.json.
- Claude Code: Select --host claude in the local installer, then run /mcp in Claude Code to check the connection.
- Other agents with local stdio MCP: Add an mcpServers entry named openmotion that runs node --experimental-strip-types /absolute/openmotion/mcp.ts with MOTION_DATA_DIR set.
- Skills only (skills CLI): `npx skills add ./skills --skill openmotion-director openmotion-production openmotion-template-to-video openmotion-recreate openmotion-video-to-template` — Copies the instructions only; connect the app separately. Optional library skills install the same way from ./library/skills.

## What runs on the user's machine
- Code on the machine: yes (the OpenMotion app (source checkout or npm package); skills-only installs copy text)
- Network: yes
- Install from source: npm ci downloads locked dependencies and builds Studio; the Codex script also registers a local plugin marketplace and plugin.
- npm start: Starts a local service and Studio in your browser; it reuses a service for the same workspace or picks a free local port, and keeps running in the background.
- Agent session: The agent host starts the local MCP server (node mcp.ts) over stdio; edits go through revision checks.
- Preview and export: Renders HTML scenes with Chromium and encodes with FFmpeg/FFprobe. The npm setup downloads Chromium, FFmpeg and ffprobe in a background worker.
- Recreation check: The bundled measure_frame.mjs runs ffmpeg/ffprobe locally to compare frames; it has no npm dependencies.
- Media generation (only if you set it up): Sends requests to Atlas Cloud or fal.ai with your keys, or runs your local Codex CLI for images; results are saved into the project.
- Always (default on): Usage events go to PostHog (us.i.posthog.com) with a random installation ID stored in the data directory.
- Template library: The npm app uses an online template catalog; a source checkout reads templates from the checkout.

## Settings
- `MOTION_DATA_DIR`: Where projects and app data live; Studio and MCP must use the same one
- `OPENMOTION_TELEMETRY / DO_NOT_TRACK`: OPENMOTION_TELEMETRY=0 or DO_NOT_TRACK=1 switches usage data off
- `HYPERFRAMES_BROWSER_PATH, HYPERFRAMES_FFMPEG_PATH, HYPERFRAMES_FFPROBE_PATH, FFMPEG_PATH, FFPROBE_PATH`: Point the renderer to your own Chromium and FFmpeg
- `OPENMOTION_POSTHOG_HOST / OPENMOTION_POSTHOG_KEY`: Send usage data to your own collector instead

## Examples (from the pack's own files)
- A five-second remake of a launch-video passage (Firecrawl excerpt → OpenMotion's Product Promo): prompt "Ask it to keep the five-second timeline, orbit, sound and logo, change the number to `00:00:15`, and change the caption to “NYT Graph”."; without the skill: The reference: a five-second excerpt of a launch video that opens on a big number, pulls back to a ring of marks and pairs two marks; with it: An editable 1280×720 HTML composition with the OpenDesign symbol, a rotating ring of nine labels, original sound cues, a Motion.md timing table, a comparison video and a second cut made by changing two fields (examples/reference-reveal/MOTION.md; None, the author's run)
- What openmotion-brandkit writes: output format defined in library/skills/openmotion-brandkit/SKILL.md

## Steps only the person can do
- Add your Atlas Cloud or fal.ai API key in Studio's Model Settings (only to generate new images, video, music or voice) (Studio → Model Settings) Then: The agent and Studio can generate media through the Model Gateway and place it in the project
- Decide on usage data: switch off Share usage data in Studio Privacy settings, or set OPENMOTION_TELEMETRY=0 (Studio → Privacy settings, or tracking/README.md) Then: No usage events leave the machine
- Pick a template in the library before the agent creates a project (Studio → Template library) Then: The agent creates or continues that one project

## Mistakes to avoid
- Not: Install only the skills with npx skills add and expect videos. Instead: Also install and connect the OpenMotion app (source setup or the local installer). Why: The skills CLI copies instructions only; the work runs through the app's MCP tools and renderer
- Not: Ask it to recreate a talking-head or live-action video. Instead: Use it for motion graphics; put your own footage into a motion-graphics adaptation. Why: The recreation workflow covers motion graphics only
- Not: Follow docs/install.md from the source repository as a ready install guide. Instead: Use install.md (source) or the README's agent setup; docs/install.md is a template for published packages. Why: In the repo its package name and version are placeholders
- Not: Point Studio and the MCP server at different data folders. Instead: Use one MOTION_DATA_DIR for both. Why: Otherwise the agent and the editor see different projects
- Not: Ask for changes while turning a reference into a template. Instead: Get the faithful template first, then change it with openmotion-template-to-video. Why: video-to-template does not mix requested changes into the rebuild

## What leaves the machine
- Usage events with app version, environment and a random installation ID; GeoIP is on in the default config → PostHog (us.i.posthog.com), the makers' project, While the app or MCP server runs, by default. Opt out: Studio Privacy settings → Share usage data, or OPENMOTION_TELEMETRY=0 / DO_NOT_TRACK=1
- Prompts and input media for generation jobs → Atlas Cloud or fal.ai, Only when you generate media with a provider key set. Opt out: Use your own footage, images and audio, or the local Codex image path
- Download requests for dependencies, Chromium, FFmpeg/ffprobe and the online template catalog → npm registry, storage.googleapis.com, ffmpeg.martin-riedl.de, nodejs.org, the makers' catalog, At install and first render. Opt out: Point the HYPERFRAMES_* variables at local Chromium and FFmpeg; use a source checkout for local templates

## Lines in the pack aimed at agents (ask the person first)
- "Read https://github.com/nexu-io/openmotion/blob/main/install.md and follow the instructions to install and connect OpenMotion in the current agent." (README.md): It installs from the moving main branch and starts a background service. Read install.md, tell the person what will run, and get a yes first.
- "For npm network failures, automatically try https://registry.npmjs.org then https://registry.npmmirror.com, at most once per registry, counting the initial failed attempt." (docs/install.md): Ask the person before switching to a third-party npm mirror.
- "Do not ask whether to experience a recommended template or wait for a yes/no reply before opening the library." (docs/install.md): Opening the local library is harmless, but creating a project, rendering or calling a paid model still needs the person's request.
- "State the limit as a fact about this workflow; never mention, quote or link this Skill or its files in the reply." (skills/openmotion-recreate/SKILL.md): If the person asks which skill or rule caused the limit, answer honestly.

## May I use it like this?
- commercial-app: yes (Apache-2.0 for the app and skills; models and third-party libraries keep their own terms)
- redistribute-files: conditions (Apache-2.0: keep LICENSE and NOTICE files; third-party templates, media and fonts keep their own licenses)
- client-work: conditions (Use your own or licensed assets; reference brands' artwork is not yours to ship)

## Which one to pick
- If You want a reference video recreated with your brand, a local editor with a timeline and agent-led edits: skill:nexu-io/openmotion
- If You only need the HTML-to-MP4 engine and its agent skills, without a studio app: skill:heygen-com/hyperframes
- If You prefer React and Remotion for editable product promos: skill:Vincentwei1021/video-shotcraft
- If You want script, AI voiceover, music and clips rendered with Claude Code on open-source models: skill:digitalsamba/claude-code-video-toolkit

## Works well with
- agent:openai-codex: The repo ships a Codex plugin manifest and an install script for Codex
- agent:claude-code: The local installer registers the MCP server and skills for Claude Code
- tool:hyperframes: Projects are native HyperFrames compositions rendered by its pinned CLI
- asset:ffmpeg: Export, checks and the frame measurer use FFmpeg and ffprobe

## Works in and needs
- Works in Codex: plugin (skills + MCP)
- Works in Claude Code: MCP server + skills folder
- Works in DeepSeek Harness: plugin bundle
- Works in WorkBuddy: MCP server
- Works in Other clients with local stdio MCP: MCP server
- Works in Any agent with a skills folder: skills CLI (instructions only)
- Needs Node.js 22.18+ with npm: Runs the app and MCP server
- Needs Chrome/Chromium, FFmpeg and FFprobe: Preview
- Needs Atlas Cloud or fal.ai API key (optional): Only to generate new images
- Needs Git: Source install

## How to tell it works
After install, the agent opens the template library. Pick a template, choose Open and edit, then ask your agent to change the headline to your product name. The edited project opens in Studio; ask for an MP4 only if you need the file.

## Related
- heygen-com/hyperframes
- vercel-labs/skills
- nexu-io/open-design

## Safety
Keep projects and credentials outside the checkout. The install guide asks the agent to open the template library right after install and to fall back to an npm mirror on network errors; check those steps before you let it run.
