Open Design host conventions
This is the functional skill in the current task. Preserve the task type, brand, tech stack, current stage, and delivery format selected by the user; do not change it to a video project because of an @ selection. The planning stage only plans; the implementation stage writes code. Checks, rendering, and export are performed only when the host's current stage allows it and the tools are actually available; the skill cannot additionally start an independent Agent, force approval, or bypass the host's delivery boundaries.
Attached files are read relative to the current skill package root, and are read selectively according to the current problem; do not paste all reference documents into the prompt. Do not read other Agents' global configurations. For assets, prefer the user's existing files; when new images, videos, or audio are needed, use the tools actually provided by the current host and permitted by the user. When generation, measurement, or export capabilities are missing, state the specific gap, deliver the verifiable parts, and do not claim to have completed steps that were not executed. Follow the output path of the current task, and do not overwrite inputs or historical artifacts.
Oil MotionConvert the user's interaction intent into acceptable animation assets, a timeline list, and a web runtime. AI generation handles semantic changes such as limbs, structure, materials, and occlusion; the program handles input mapping, playback control, media processing, and performance.
This adaptation package includes local media processing scripts and a web controller. Before running Python scripts, check for Python 3.10+, FFmpeg / ffprobe with support for -fps_mode , Pillow, NumPy, and PyYAML; when dependencies are missing, install them only in the task-isolated environment according to scripts/requirements.txt , without modifying the global environment. Pure local processing does not require an API Key.
Before running the reference commands, set OIL_MOTION to the skill directory actually loaded for this session:
OIL_MOTION="<本次 SKILL.md 所在绝对目录>"
Image/video generation is delegated to the host's existing tools. This package does not include the upstream generation service, Keychain, or credential configuration pages; do not attempt to call them.
Four single sources of truth
Each piece of information is stored in only one place, and other files reference it rather than copying it:
source/concept-contract.yaml: the objects, visuals, interactions, and continuity explicitly required by the user.source/motion-brief.yaml: the keyframes, segments, and production plan derived from the contract.build/timeline.json: the final film's actual frame rate, segment boundaries, freeze frames, and playback curve.build/motion-budget.json: the delivery format and the runtime controller's automatic selection result.
Main flow
1. Lock down user intent
When the user has only a vague goal, first read references/concepts.md, and give at most three genuinely different directions; when the requirements are already clear, write the Concept Contract directly.
When inspiration from external cases is needed, selectively read references/motion-patterns.mdaccording to the expressive purpose. First distinguish which changes belong to the assets themselves and which are merely container orchestration or UI state; only the former enter the generation process.
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:
aspect_ratiois taken from the real container ofdestination: horizontal fullscreen or Hero is usually16:9, vertical fullscreen is9:16, and square viewports such as cards and avatars are1:1; do not default to1:1without confirmation. When the container ratio and the generation ratio differ, specify the cropping or padding strategy in the contract. After locking, the keyframe size, video frame, and compiled output all use the same ratio; for size comparisons see references/prompting.md。scrub: input values correspond continuously to timeline positions, and when input stops, the image stays at the current position.segment-play: The input selects the next state, and the segment then plays in time; reverse input should retract from the current frame, and must not switch sources with a hard cut.autonomous: The animation is advanced by time, and interaction is only responsible for starting, pausing, or switching states.navigationIt only describes how the page moves, and does not determine how the video plays; paginated pages can also use a continuous timeline.- Use when camera, ambient light, contact shadows, depth of field, or background continuity matter
background_owner: video. Use only when the subject must be transparently reused on the page backgroundpage。 - Record directly what the user has already stated clearly, without rewriting or expanding. If a missing item would change generatability, acceptance results, or the production route, it must be filled in first.
2. Establish the production plan
Motion Brief only stores the derived plan and does not copy contract fields:
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, not the page layout:linear is a timeline with start and end,circular is a closed loop,2d is two-dimensional sampling,discrete are mutually discontinuous states. Do not compress two-dimensional or unordered states into a single linear video.
frame_policy and target_fps for the criteria of choosing between them, see references/optimization.md。
Whole-group displacement, scaling, rotation, cropping, and time mapping are done by the program; joint, structure, material, contact, and occlusion changes are done by the generative model. If moving the whole image alone cannot maintain naturalness, generate the complete motion and do not keep layering CSS patches.
3. Automatically select delivery and runtime
At the stage where the host allows running tools, run with the planned frame count, display size, and parameter space from the Brief motion_budget.py --strict, explicitly pass in the contract's background_owner and time_control, and save build/motion-budget.json. Pilot mounts to the real page based on this result; after that, if the frame count or size changes, re-budget. The script returns respectively:
delivery.selected：baked-video | chroma-video | alpha-atlas。runtime.controller：frame-scrub | segment-playback | autonomous-playback。
Format selection and playback method are two different things and must not be inferred from each other. For the command and decision order, see references/delivery-selection.md. Based on the result, read only one media route:
alpha-atlas：references/alpha-atlas.mdchroma-video：references/chroma-video.mdbaked-video：references/baked-video.md
4. Create keyframes
- When there is a character or identity consistency is needed, write the Identity Bible first.
- Generate and accept
K0…Kn; each segment carries only one main semantic change, and when segmentiusesKi → Ki+1。clip_continuity: chain, the first frame from segment 2 onward changes to the actual last frame after acceptance of the previous segment, and the last frame is still the planned keyframe. - Use the host's available image tools to generate keyframes: pass the size according to
aspect_ratio, and verify the actual aspect ratio reported by the script; the size must cover at least the maximum CSS size multiplied by the target DPR. For real products, established characters, or the previous keyframe, use--imageas reference input, not just a text description. background_owner: pageRequest transparent output, and actually check the Alpha channel; do not first generate a color background and then reverse matte it. When the video model needs a chroma-key input,composite_alpha_keyframe.pycomposites a copy from the transparent source.background_owner: videoUse opaque scene output, and draw the scene directly into the keyframe.- For commands, size comparison, prompts, first/last frame mode, and submission method, see references/prompting.md. The host's built-in image tools can also be used when they can output true Alpha and accept reference images, and the acceptance criteria remain unchanged. When video or sequence frames already exist, skip generation, keep the original assets, and start from analysis.
5. Do the Pilot first
Before batch generation, complete only the first group of keyframes and the first video segment, and mount them to the real page according to the selected route. Only after passing the Pilot hard gate according to references/qa.md can mass production proceed; if it fails, fix the upstream and do not cover it up at runtime.
6. Generate and accept segment by segment
According to references/prompting.md generate the master, and according to references/qa.md accept the content and the continuous frame chain.chain mode must simultaneously verify the generated input relay and the output seam after decoding adjacent finished frames; if either fails, stop subsequent production.
7. Frame preparation, cleanup, and compile timeline
According to references/optimization.md execute frame_policy(when frame interpolation shows ghosting or artifacts, fall back to native or regenerate), then clean up and compile according to the selected media route. All cropping and splicing must check the newly created adjacent frames; a single long-distance frame skip must not be used to replace slow tail changes.
After compilation, generate build/timeline.json; field semantics are governed only by the timeline specification of references/runtime.md . Time values must be generated from the final compilation result, not copied by hand.
8. Integrate into runtime
Start implementation from the corresponding controller of assets/interactive-motion.ts (frame-scrub manages follow-along and shortest ring distance,segment-playback manages segmentation and reverse); step gestures use assets/step-gesture.ts. Input mapping, segmented playback, reverse, cancel, preload, and degradation are governed only by references/runtime.md .
9. Final acceptance
According to references/qa.md , accept under target CSS size, DPR, cold cache, rapid reverse, mobile, and resource failure conditions. Page navigation, time control, media format, and continuity are checked separately; do not use one check in place of another.
When an animation principles demonstration page is needed, read references/explainer.md and use create_explainer.py。
Deliver
Retain source/、pilot/、build/、qa/ and final/。final/ contain only the selected primary resources, static fallback, and runtime entry point; at the same time, attach the four fact sources and reproducible processing commands according to the host delivery contract.
Runtime files included in the package
The following files are frozen with the session and read as needed; all Python internal dependencies and runtime templates are within the package.
assets/chroma-video-renderer.tsassets/interactive-motion.tsassets/motion-explainer-template.htmlassets/motion-manifest.example.jsonassets/step-gesture.tsreferences/alpha-atlas.mdreferences/baked-video.mdreferences/chroma-video.mdreferences/concepts.mdreferences/delivery-selection.mdreferences/explainer.mdreferences/motion-patterns.mdreferences/optimization.mdreferences/prompting.mdreferences/qa.mdreferences/runtime.mdscripts/chroma_key.pyscripts/compile_scroll_video.pyscripts/compose_travel_frames.pyscripts/composite_alpha_keyframe.pyscripts/create_explainer.pyscripts/loop_cleanup.pyscripts/media_edges.pyscripts/motion_budget.pyscripts/motion_pipeline.pyscripts/optimize_motion.pyscripts/production_gate.pyscripts/requirements.txt
License retained with the package
references/license.md retain the source license with the session package. When copying reference code into the delivery project, retain the upstream attribution and license text.