Open Design Host Contract

This is the functional skill for the current task. Preserve the task type, brand, technology stack, current stage, and delivery format selected by the user; do not switch to a video project merely because of an @ selection. In the planning phase, only plan; write code only during implementation. Perform inspection, rendering, and export only when permitted by the host's current stage and the tools are actually available; the skill must not launch an additional standalone Agent, force approval, or bypass host delivery boundaries.

Read ancillary files relative to the current skill package root, selecting them according to the current question, and do not paste all reference documents into the prompt. Do not read other Agents' global configurations. Prefer assets the user already has; when new images, videos, or audio are needed, use tools actually provided by the current host and allowed by the user. If generation, measurement, or export capabilities are missing, explain the specific gaps, deliver the verifiable portion, and do not claim that unexecuted steps were completed. Follow the current task's output path, and do not overwrite inputs or historical artifacts.

Oil Motion

Convert the user's interaction intent into acceptance-ready animation assets, a timeline manifest, and a web runtime. AI generation handles semantic changes involving limbs, structure, materials, occlusion, and similar elements; the program handles input mapping, playback control, media processing, and performance.

This adapter package contains local media-processing scripts and a web controller. Before running Python scripts, verify Python 3.10+, FFmpeg / ffprobe support for

-fps_mode

, Pillow, NumPy, and PyYAML. If dependencies are missing, install them only in an isolated task environment according to

scripts/requirements.txt

; do not modify the global environment. Fully local processing requires no API Key.

Before running the reference commands, set

OIL_MOTION

to the actual skill directory loaded for the current run:

bash

OIL_MOTION="<本次 SKILL.md 所在绝对目录>"

Delegate image and video generation to the host's existing tools. This package does not include the upstream generation service, Keychain, or credential configuration pages; do not attempt to invoke them.

Four Single Sources of Truth

Store each piece of information in exactly one place; other files reference it rather than duplicating it:

```
source/concept-contract.yaml
```
: The objects, visuals, interactions, and continuity explicitly requested by the user.
```
source/motion-brief.yaml
```
: The keyframes, segments, and production plan derived from the contract.
```
build/timeline.json
```
: The final piece's actual frame rate, segment boundaries, hold frames, and playback curves.
```
build/motion-budget.json
```
: The automatically selected delivery format and runtime controller.

Main Workflow

1. Lock in User Intent

If the user has only a vague goal, first read references/concepts.md and propose at most three genuinely different directions; if the requirements are already clear, write the Concept Contract directly.

When external examples are needed for inspiration, read references/motion-patterns.md according to the intended expression. First distinguish which changes belong to the asset itself and which are merely container choreography or UI state; only the former enter the generation workflow.

yaml

subject_count: <number>
subjects:
  - identity: <可验证的身份或外观锚点>
style: <用户原词>
motion_intent: <动作及视觉结果>
background_owner: video | page
scene: <背景属于视频时的场景、镜头和光线要求>
driver: scroll | pointer | drag | touch | orientation | audio | data | state | time
input_semantics: continuous | step | event
time_control: scrub | segment-play | autonomous
navigation: continuous | paged | none
clip_continuity: chain | independent
continuity: [<必须保持不变或连续的内容>]
aspect_ratio: 16:9 | 9:16 | 1:1 | 21:9 | custom
destination: <页面位置、最大显示尺寸和目标设备>

Decision rules:

Derive
```
aspect_ratio
```
from the actual container in
```
destination
```
: landscape fullscreen or Hero views are usually
```
16:9
```
, portrait fullscreen is
```
9:16
```
, and square views such as cards or avatars are
```
1:1
```
. Do not default to
```
1:1
```
without confirmation. If the container ratio differs from the generation ratio, specify the cropping or padding strategy in the contract. Once locked, keyframe dimensions, video framing, and compiled output all use the same ratio. See references/prompting.md for dimension comparisons.
```
scrub
```
: The input value continuously corresponds to the timeline position, and the frame remains at the current position when input stops.
```
segment-play
```
: The input selects the next state, after which the segment plays over time; reverse input should rewind from the current frame rather than hard-cutting to a different source.
```
autonomous
```
: The animation advances with time, while interactions only start, pause, or switch states.
```
navigation
```
describes only how the page moves, not how the video plays; a paginated page may still use a continuous timeline.
Use
```
background_owner: video
```
when the camera, environmental lighting, contact shadows, depth of field, or background continuity is important. Use
```
page
```
only when the subject must be transparent and reusable over a page background.
Record what the user has explicitly stated as-is, without rewriting or expanding it. If missing information would affect generatability, acceptance results, or the production route, it must be completed first.

2. Establish the Production Plan

The Motion Brief stores only the derived plan and does not duplicate contract fields:

yaml

concept_contract: source/concept-contract.yaml
identity_bible: source/identity-bible.md | null
parameter_space: linear | circular | 2d | discrete
media_access: sequential | random
gesture_policy:
  unit: continuous | one-gesture-one-step
  inertia: coalesce | preserve
  while_active: retarget | queue | ignore
  boundary: clamp | loop
  programmatic_navigation: ignore | observe
storyboard: <有序视觉阶段>
keyframes: <K0…Kn>
clip_chain: <每段使用的相邻关键帧>
rest_state: <初始及失去输入时的状态>
loop: open | closed | none
anchor: fixed-body | center | bottom | free
scene_continuity: <仅背景属于视频时填写>
frame_policy: native | interpolate
target_fps: <由源素材和运行时需求决定>
quality_target: <分辨率、DPR 和文件预算>
pixel_dimensions: <宽x高，由合同的 aspect_ratio 与 DPR 派生>
reduced_motion: <静态替代状态>

parameter_space

describes the asset timeline rather than the page layout:

linear

is a timeline with a start and end,

circular

is a closed loop,

2d

is two-dimensional sampling, and

discrete

consists of mutually discontinuous states. Do not flatten a two-dimensional or unordered state into a single linear video.

See references/optimization.md for the trade-offs between

frame_policy

and

target_fps

Whole-group translation, scaling, rotation, cropping, and time mapping are handled programmatically; changes involving joints, structure, materials, contact, and occlusion are handled by the generation model. If moving the entire image cannot look natural, generate the full action instead of continuing to layer on CSS patches.

3. Automatically Select the Delivery and Runtime

During the stage in which the host permits tools to run, use the planned frame count, display dimensions, and parameter space from the Brief to run

motion_budget.py --strict

. Explicitly pass the contract's

background_owner

and

time_control

, then save

build/motion-budget.json

. Mount the Pilot to a real page according to this result; rerun the budget whenever the frame count or dimensions change. The script returns the following separately:

delivery.selected

baked-video | chroma-video | alpha-atlas

runtime.controller

frame-scrub | segment-playback | autonomous-playback

Delivery format and playback mode are separate concerns and must not be inferred from one another. See references/delivery-selection.md for commands and decision order. Based on the result, read only one media route:

```
alpha-atlas
```
: references/alpha-atlas.md
```
chroma-video
```
: references/chroma-video.md
```
baked-video
```
: references/baked-video.md

4. Produce the Keyframes

If characters are involved or identity consistency is required, write the Identity Bible first.
Generate and accept
```
K0…Kn
```
. Each segment should carry only one primary semantic change, and segment
```
i
```
uses
```
Ki → Ki+1
```
. When
```
clip_continuity: chain
```
, use the actual accepted final frame of the previous segment as the first frame from the second segment onward; the final frame remains the planned keyframe.
Generate keyframes with the image tools available in the host: pass dimensions according to
```
aspect_ratio
```
and verify the actual aspect ratio reported by the script; the dimensions must cover at least the maximum CSS dimensions multiplied by the target DPR. For real products, established characters, or previous keyframes, use
```
--image
```
as a reference input rather than relying only on a textual description.
When
```
background_owner: page
```
, request transparent output and actually inspect the Alpha channel; do not generate a solid-color background and then reverse-key it. If a video model requires chroma-key input, use
```
composite_alpha_keyframe.py
```
to composite a copy from the transparent source. When
```
background_owner: video
```
, use an opaque scene output and draw the scene directly into the keyframe.
See references/prompting.md for commands, dimension comparisons, prompts, first-and-last-frame modes, and submission methods. The host's built-in image tools may also be used if they can output genuine Alpha and accept reference images; the acceptance standards remain unchanged. If an existing video or sequence of frames is available, skip generation, preserve the original assets, and begin with analysis.

5. Build a Pilot First

Before batch generation, complete only the first keyframe set and first video segment, and mount them to a real page according to the selected route. Production at scale may begin only after the Pilot passes the hard gate in references/qa.md; if it fails, fix the upstream source rather than masking the problem in the runtime.

6. Generate and Accept Each Segment

Generate the master according to references/prompting.md, and accept its content and continuity frame chain according to references/qa.md. In

chain

mode, verify both the generation-input handoff and the output seam after decoding adjacent finished segments; stop subsequent production if either fails.

7. Prepare Frames, Clean the Media, and Compile the Timeline

Apply

frame_policy

according to references/optimization.md; if interpolation introduces ghosting or artifacts, fall back to

native

or regenerate the material. Then clean and compile according to the selected media route. Inspect newly created adjacent frames for every crop and concatenation; do not replace a slow change near the end with a single long-distance frame skip.

After compilation, generate

build/timeline.json

. The semantics of its fields are defined exclusively by the timeline specification in references/runtime.md. Time values must be generated from the final compilation result and must not be transcribed manually.

8. Integrate the Runtime

Begin implementation with the corresponding controller in assets/interactive-motion.ts:

frame-scrub

manages tracking and the shortest circular distance, while

segment-playback

manages segmentation and reversal. Use assets/step-gesture.ts for stepwise gestures. Input mapping, segmented playback, reversal, cancellation, preloading, and fallback behavior must follow references/runtime.md exclusively.

9. Final Acceptance

Perform acceptance under the target CSS dimensions and DPR, with a cold cache, rapid reversal, mobile conditions, and resource-loading failures, according to references/qa.md. Check page navigation, time control, media format, and continuity separately; do not use one check as a substitute for another.

When an animation-principles explainer page is needed, read references/explainer.md and use

create_explainer.py

Delivery

Retain

source/

pilot/

build/

qa/

, and

final/

final/

should contain only the selected primary asset, static fallback, and runtime entry point. In accordance with the host delivery contract, also include the four sources of truth and reproducible processing commands.

Bundled Runtime Files

The following files are frozen with the session and should be read as needed; all internal Python dependencies and runtime templates are included in the package.

```
assets/chroma-video-renderer.ts
```
```
assets/interactive-motion.ts
```
```
assets/motion-explainer-template.html
```
```
assets/motion-manifest.example.json
```
```
assets/step-gesture.ts
```
```
references/alpha-atlas.md
```
```
references/baked-video.md
```
```
references/chroma-video.md
```
```
references/concepts.md
```
```
references/delivery-selection.md
```
```
references/explainer.md
```
```
references/motion-patterns.md
```
```
references/optimization.md
```
```
references/prompting.md
```
```
references/qa.md
```
```
references/runtime.md
```
```
scripts/chroma_key.py
```
```
scripts/compile_scroll_video.py
```
```
scripts/compose_travel_frames.py
```
```
scripts/composite_alpha_keyframe.py
```
```
scripts/create_explainer.py
```
```
scripts/loop_cleanup.py
```
```
scripts/media_edges.py
```
```
scripts/motion_budget.py
```
```
scripts/motion_pipeline.py
```
```
scripts/optimize_motion.py
```
```
scripts/production_gate.py
```
```
scripts/requirements.txt
```

License Preserved with the Package

references/license.md

preserves the source license as part of the session package. When copying reference code into a delivery project, retain upstream attribution and the license text.

oil-motion

NPX Install

Tags

SKILL.md Content (Chinese)