nexu-io/openmotion / skills/openmotion-production
openmotion-production
VerifiedExecute local edits, asset or audio replacements, previews, technical troubleshooting, exports, and delivery on an existing OpenMotion project under established creative decisions. Use openmotion-director for narrative, motion, or audiovisual redesign; openmotion-template-to-video for existing templates; openmotion-recreate for recreating a reference video; and openmotion-video-to-template for reusable templates. Repository development and documentation maintenance do not trigger video production.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.0 KB |
| agents/openai.yaml | config | 139 B |
| fonts/catalog.json | config | 139.4 KB |
| references/context.md | markdown | 15.1 KB |
| references/decisions.md | markdown | 8.7 KB |
| references/edit.md | markdown | 5.9 KB |
| references/fonts.md | markdown | 8.6 KB |
| references/intake.md | markdown | 7.1 KB |
| references/materials.md | markdown | 19.4 KB |
| references/native.md | markdown | 21.4 KB |
| references/portable-project.md | markdown | 5.8 KB |
| references/production.md | markdown | 12.9 KB |
| references/reference-video.md | markdown | 15.5 KB |
| references/review.md | markdown | 11.2 KB |
| references/sound.md | markdown | 12.3 KB |
| references/templates.md | markdown | 9.9 KB |
| references/typography.md | markdown | 10.1 KB |
| references/verification.md | markdown | 12.5 KB |
references/native.md
View on GitHub# Native Hyperframes authoring · phase one
Apply the engine boundary below before reading the pinned guide returned as `authoringGuide` by project details, or MCP resource `openmotion://engine/SKILL.md`. Relative engine Markdown references are available below `openmotion://engine/`. The host Agent writes the actual native video.
## Engine guidance boundary
Use the pinned Hyperframes guide and its references for HTML/composition structure, timeline and media attributes, seekable animation, supported CLI commands, lint and rendering constraints. This applies equally to direct filesystem reads and MCP engine resources; the upstream files are technical references, not an additional production Skill.
OpenMotion's selected Skill and shared rules own creative decisions, material sourcing, provider selection, authorization, project operations and delivery. Upstream supplier onboarding, account/sign-in requirements and Skill routes such as `/media-use`, `bgm` or HeyGen setup are references, not automatic workflow requirements or evidence of an available tool. Select providers and any external tools through the [shared material policy](materials.md#tool-selection-and-discovery), based on content need and matching available capabilities. Do not import its mandatory story/film workflow, fixed music-by-duration defaults or silence fallback based solely on an upstream provider being unavailable. Sound needs follow the user's brief and OpenMotion's sound decisions.
Read linked engine references only for the technical question at hand. Use a documented command only when the installed runtime exposes it; an upstream slash command or link does not establish a connected host capability. Preserve engine format and rendering requirements without adopting its vendor or creative routing.
## Project loop
1. New work uses `openmotion_create_project` with a stable requestId, projectType, title and requirements. A prompt/reference creates a carrier, not a finished film. Template creation requires a real copyable builtin ID; select it through the Studio gallery or a provided guide. Existing work reuses its projectId.
2. `openmotion_get_project({projectId})` reads the explicit project, entry HTML, directory, file inventory, requirements, revision and current version. Without projectId it lists five projects per page; follow nextCursor. Never infer another chat's active project.
3. Read text through `openmotion_get_project({projectId,file:{path,offset,length},expectedRevision})`. Offsets are UTF-8 byte boundaries; follow nextOffset. Media bytes stay out of MCP text responses.
4. `openmotion_import_assets({projectId,requestId,items:[{itemId,sourcePath}]})` imports real local image/video/audio attachments and TTF/OTF/TTC/WOFF/WOFF2 fonts in a batch. Font items may include an absolute licensePath that sits in the same directory as the font file; a licence elsewhere fails that item with `FONT_LICENSE_NOT_BESIDE_FONT`. The returned metadata and fontFaceCss use the real face, and the license is retained in the same version. Each file must be at most 500 MB (500000000 bytes); compare exact bytes, not rounded MB. Source paths must exist on the server machine. Check every result and use the returned asset path. Import does not place media on the timeline. Keep stable itemIds for retries; never overwrite historical resources. Successful imports can create a new content version: reread project details before saving with expectedRevision/expectedVersionId. This Tool does not accept SVG/PDF, arbitrary binary files or remote URLs. Only when acquiring/importing a catalog font, select and prepare it through the [font resource guide](fonts.md); ordinary media imports and wording edits with an existing usable face do not load the font catalog. Keep such files in an independent portable project using host capabilities; do not bypass managed-project guards by writing binary files directly. Inline SVG markup can be authored in native HTML.
5. `openmotion_edit_project({projectId,requestId,expectedRevision,expectedVersionId,files:[{path,content}]})` saves one batch of text files and optional requirements. Maximum 100 files / 8 MiB; metadata paths are reserved. All-or-none failure protection uses Studio's exclusive native history window and a recovery journal. Reread after a conflict; do not replay an old patch against unknown GUI changes.
6. Once the requested video artifact is complete, record that completion with `complete_generation` right away, as [final video delivery](production.md#final-video-delivery) specifies. For original creation, reference-video recreation and editable-template production, complete the editable preview handoff below once this turn's final video HTML and assets are complete and ready for preview. Existing-project content edits apply its continuing-edit rules once the final video is ready for preview, regardless of the selected Skill. Other scopes open Studio on request.
7. Inspect actual motion, timing, sound and affected joins. Local/Studio changes become native content snapshots; querying flushes saved history metadata without editing source. Return to step 2 after GUI edits.
## Pin source for independent deliverables
For already accepted content, complete any required native preflight/editor normalization first, then read the current revision, currentVersionId and file inventory with `openmotion_get_project`. Reuse an applicable current read; no save or asset import is required merely to pin an unchanged source.
Bind requested outputs to this same source identity. Immutable export, packaging and host presentation can proceed independently after normalization. A revision change or package hash mismatch invalidates the pending package: read the newer source and reconcile before continuing. Preserve any in-flight export and its original job identity; do not resubmit blindly. Reuse an existing export only with matching content/version, specification, dependency identity and actual file hash.
Presentation is read-only. Apply the handoff below, including stable paused zero-second playback and accurate display evidence. Retain queued/hidden/unavailable status and the exact usable URL after bounded recovery; a failed or unobserved panel does not block independent verified file delivery.
## Editable preview handoff
Independent delivery work follows [source pinning](#pin-source-for-independent-deliverables) before export or packaging. This handoff's visibility, playback-state and bounded-retry requirements remain; an unresolved panel is reported separately from delivered files rather than blocking independent export work.
The first output of original creation, reference-video recreation and editable-template production automatically includes an editable preview. Once the final requested video HTML and its supporting files/assets are complete and ready for preview, call `openmotion_open_preview({projectId})` for that same project, then visibly open its exact returned `previewUrl` in the host's built-in browser. No additional user request or confirmation is needed. Intermediate drafts and saves do not trigger this handoff. An explicitly requested draft/editor preview and unchanged template opening retain their scope; the final ready HTML preview need not wait for MP4 export. An empty carrier's `index.html` is not the requested output. Explicit user instructions to stay in the background take precedence.
First delivery must complete steps 1–5 under [Continuing edits](#continuing-edits) too: preparing the preview is only the first step. Hidden-tab playback, screenshots, `markDeliverable()` and a completed MP4 export do not prove editor delivery. Before finishing, either confirm the native panel is visible with the latest content, or state the specific display failure/deferred status and give the project URL. Do not silently replace the editor with files.
After verifying playback, pause the preview first, then seek to 0 seconds (`seek(0)`) through the host's supported preview controls. Keep playback paused at 0 seconds, including when the opening frame is blank; do not advance to find visible content. An explicit user request for another playback position or playing state takes precedence.
Before recording display confirmation or delivering the editor, verify the selected playback state. The default handoff requires a playhead at 0 seconds that remains stable while paused. Verify that the intended project and current content loaded; an authored blank opening frame is valid, but an unloaded preview is not. For an explicit playback request, verify the requested position or playing state instead. Include the observed time, playback state and visible content in the display evidence. This applies to first delivery, unchanged first-run templates and continued edits. If the controls, content or resulting playback state cannot be verified, report that limitation and keep display confirmation pending.
The Tool runs lint and selects an existing project in Studio; it does not create a project or open the host browser. Preserve the URL's embed/query/hash, verify that the intended project and current content loaded, and reuse its browser tab on continued work. If lint fails, fix the reported source problem before retrying. If preview or browser capability is unavailable, provide the project URL when available and state the concrete gap; report the page as opened only after observing it. Do not substitute the system `open` command, AppleScript or a separately launched visible browser for the host's browser. For an independent folder or ZIP, follow the [portable project import procedure](portable-project.md#import-a-native-zip-into-studio).
Preview preflight, export preflight and the OpenMotion command `node <runtimeRoot>/scripts/lint-project.mjs <runtimeRoot> <projectDirectory>` use the native linter with `host: "studio"`. Structural errors therefore fail before the editor is opened or rendering begins; ordinary warnings remain non-blocking. A direct upstream `hyperframes lint` still uses its own CLI warning policy and is not proof that Studio will accept a project.
### Continuing edits
Every content-editing turn saves the result silently during authoring, then requests its preview in the same host chat only once the final authored video is complete and ready to preview. Reuse the project and native tab. Default `presentation:"foreground"` preserves the user's current chat: show the right panel when this chat is active; otherwise queue it until the user returns. Before writing, confirm project ownership and the current source/version without opening the target just to show activity. Reuse an editor that the user already opened, but do not pull it into view for intermediate work. Apply this shared rule across production, director, template and recreation edits.
For first delivery and continued edits, after the final requested source batch complete these steps:
1. Take `projectId`, `revision` and `versionId` from the save's `previewHandoff`. Production saves with workId return a deferred handoff and no immediate host action. Once the final video is ready, explicitly call `openmotion_open_preview` with both expected identities. Other ready handoffs may supply that call as `nextAction`. A conflict means reread the current project and source, preserve intervening GUI changes, and prepare the preview with the newly read identities. Studio can add source handles on first open; do not overwrite that normalization with the old batch. Verify and acknowledge the current version returned by the successful open.
2. Request the same project's native preview on the right in the calling chat through the host's supported presentation call ([Codex](#codex-host-calls)). The host queues the action when its target chat is inactive. Reuse the actual native Tab ID when available; CUA wrapper `id` is not the host's `providerTabId`. Without an established native Tab ID use the exact returned `previewUrl`, preserving embed/query/hash. Rebind it from the current host inventory after presentation. If the matching native tab is absent, retry the same host presentation once, then report the gap; do not create a separate `visible:false` / `browser-use:` automation tab as a substitute. Hidden tabs remain valid for inspection only. Reuse an already queued same-project live preview while subsequent edits update that project; avoid duplicate tabs or a queue of frozen versions.
3. Read the host acknowledgment **and separately observe visibility**. `queued` is neither success nor failure evidence and does not establish that the calling chat is inactive. Rebind the actual native panel tab; a previous hidden automation tab can report false while a native tab is visible. After binding that tab, request panel visibility once through the host's supported capability, which requests the calling chat's panel, queues while that chat is inactive and does not navigate to it ([Codex](#codex-host-calls)). Do not substitute another host's unverified focus-changing API. Observe visibility as the host settles (bounded by the handoff's `settleTimeoutMs`); an immediate false can precede queued panel activation. Only if the host confirms the calling chat is inactive, leave it queued and finish with “saved; preview queued for when you return.” Otherwise a still-hidden or unobservable panel is a display failure to report, even when the host acknowledged `queued`. Navigation remains forbidden by default. A closed/collapsed panel is not a request to skip preview entirely.
4. When the user returns, the host consumes its queued action. If executing a follow-up observation, use the handoff's `onReturn` action to resolve the **latest** project version, rather than replaying an old version-bound open or acknowledging the queued version. Locate the newest changed content at the affected time in the live preview, then recheck host visibility after inspecting it. A hidden WebContents screenshot, DOM `visibilityState`, metadata, a source read, file-watcher notification and a successful open alone do not prove visible freshness. Reload that native tab once if stale; preserve saved content and report any remaining failure. The host queue, not a continuing model turn, owns opening when the user returns; without a new observation leave the receipt pending. In disposable tests, consume queued actions before closing their tabs/server so an old queued tab cannot reappear later.
5. Record `openmotion_open_preview({action:"record_display",projectId,requestId,presentation,display:{revision,versionId,previewUrl,visibility,hostStatus,hostTabId,contentVerified,evidence}})` with the observed current version and a stable requestId per observation. Optional `hostStatus` preserves the acknowledgment (`queued` can coexist with actual `visibility:"visible"`); optional `hostTabId` preserves the established native ID as a reuse hint, validated against the current inventory. A closed tab's stale ID is omitted in favor of the fresh URL. Use `visibility:"queued"` only for confirmed inactive-chat deferral, with that host evidence; use `hidden` or `unavailable` for failed/unknown presentation. Every unconfirmed observation stays pending; only a visible preview with the latest content actually inspected can be `confirmed`. Report deferred delivery or the concrete display failure, without claiming the user has seen it or polling indefinitely. If export or packaging follows, retain this unresolved status in the final reply.
Only an explicit request such as “show it now / 现在展示” permits `presentation:"now"` for this turn, carried through save/open/display calls. Its recovery may navigate once to the verified calling chat ([Codex](#codex-host-calls)) and present/recheck the native tab. Use the host chat identity, not the OpenMotion sessionId. This permission does not persist into later ordinary edits. An ordinary “finish editing” or hidden/queued state is not immediate-display authorization.
This receipt is **host-reported evidence**, not an independent server measurement of the outer panel or user acceptance. The server rejects stale content versions, including a restored version with the same revision hash. `openmotion_get_project.previewDisplay` is a historical observation; `isCurrentVersion` says whether its content identity still matches, while `liveVisibilityVerified` remains false. Reobserve visibility each turn.
An explicit user instruction to keep work in the background skips opening/focusing the editor. Carry that preference across turns until the user changes it; pass `presentation:"background"` on those saves. Default foreground production saves with workId return a deferred handoff until the final video is ready; other foreground saves return a pending handoff. Capability failures keep presentation pending; they do not undo the source save. A local implementation or source edit does not install/reload the host plugin.
### Codex host calls
- Presentation (step 2): call `open_in_codex` with `placement:"right"` in the calling chat; omit `threadId` unless the user asked for another chat.
- Visibility (step 3): in Codex IAB, after binding the native tab, call the browser's `visibility.set(true)` once and observe `visibility.get()`.
- Show-now recovery: take the verified calling-chat `threadId` from `open_in_codex` and call `navigate_to_codex_page({threadId})` once.
## Native composition contract
- Root: `data-composition-id`, `data-start="0"`, `data-duration`, `data-width`, `data-height`, and optional `data-fps`.
- Scene hosts: unique `id`, matching `data-composition-id`, `data-composition-src="compositions/scene.html"`, `data-start`, `data-duration`, and `data-track-index`. Scene files wrap markup, styles and scripts inside `<template>`.
- Clips use native timing in seconds. A scene's clock starts at zero. Media trim is `data-media-start`; track index controls the Studio lane, while CSS controls paint order.
- Give authored body elements stable, document-unique `data-hf-id` values, including composition roots, clips and nested artwork. Keep existing values across edits. The pinned Studio stamps missing element identities into HTML on opening, which changes its revision after a source save. Supplying the identities with the initial source preserves the saved version through that normalization. Scripts, styles and template wrappers need no identity.
- Use the local `assets/gsap.min.js` installed with the default project. Register a paused GSAP timeline under `window.__timelines[compositionId]`. Prefer `fromTo` for repeatable seeking. Do not use wall-clock timers or call `.play()` to drive render animation.
- Use `<video muted playsinline>` for silent footage, or `data-has-audio="true"` to retain sound. Use timed `<audio>` with `data-volume` for separate music or voiceover. Hyperframes handles mixing.
- Keep root duration long enough for all scenes, animations and media. Choose dimensions/fps for the user's deliverable; the old fixed 540×960/24fps limits do not apply.
When the selected entry keeps a reference video's pacing or structure, express it using native clips and source trims; import reference media locally when needed for analysis or authorized final use. A style-only reference in original creation does not require copying its pacing or importing it into the finished project. Implement editable motion as native compositions and use upstream catalog blocks where suitable. Do not promise semantic or pixel-perfect reconstruction without comparison evidence. The old heuristic cut detector and shot-form UI are no longer the active workflow.
For read-only source diagnostics such as lint/timeline/info, or upstream capabilities beyond the installed MCP tools, use host shell capabilities to run `node <hyperframesCli> <command> ...` in the returned project directory using an argument-safe shell invocation. Use official `docs`, `catalog`, `add`, `snapshot`, `check` and other native commands according to their help and the bundled guide. Author/save managed source through the public edit/import Tools; do not use CLI writes to bypass version guards. CLI writes on an independent project affect that directory only. Do not install global skills or replace the pinned runtime as an incidental step.
## Versions and export
`openmotion_list_versions({projectId})` returns five content versions per page, not five individual-file saves. A version includes source, styles, timing/effects and local resources. `openmotion_restore_version` requires target versionId and the current expectedRevision/expectedVersionId. Restoring v3 at v5 creates v6; v4/v5 remain. Missing historical resources cause an explicit error before source changes.
Only when the scope includes export/final delivery, use `openmotion_export_request({projectId,requestId,versionId,expectedRevision,audio})`. Use the currentVersionId from project details as versionId. The service freezes local files/media, lints, renders MP4 and verifies the real file with FFmpeg/ffprobe. Poll `openmotion_get_project({projectId,exportJobId:jobId})`; only completed with a passed verification is technical success. External URLs remain external dependencies. A later edit cannot change the frozen snapshot.
`openmotion_export_cancel({projectId,requestId,jobId})` returns cancelling until the owned process exits; cancelled is terminal. Completed jobs stay completed. Stopping a host conversation does not automatically cancel a background job.
Export and review follow the scope set by the [shared quality rule](context.md#共享质量按职责应用). Real review evidence can be recorded with action=record_review on preview/export tools; never invent evidence or treat declared user feedback as verified adoption. Keep documents/evidence outside the live project. Preserve native files, media and Studio manifests for editable handoff.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |