SuperAPI AI Directory

motion-video-production

Design & creation

View repository

Updated 11-09 16:17

About this skill

Motion graphics and video production skill (motion-video-production)

This skill provides the order and check criteria for creating motion graphics and videos (e.g., a 30–90 second video featuring a single character). By following this skill, you will obtain a reference analysis (ref/ANALYSIS.md, ref/targets.json), STORY.md, character sheet, keyframes, scene videos, music and voice, and a final mp4. The screen is produced with the engine included in the skill (Remotion or HyperFrames), and the completed mp4 is judged numerically.

Editing, camera, and texture terms (match cut, whip pan, push in, shallow depth of field, etc.) are organized in Korean and English in references/glossary.md.

All responses are given in the user's language (Korean by default). We do not log in or make payments on the user's behalf. At points requiring login, payment, or large downloads, we ask the user first.

Execution environment and paths

This skill is common guidance in the Agent Skills format. Codex, Claude Code, and other skill-supporting runtimes use the same folder. It does not include API connections or generation tool connections for any specific model. Voice automation is used only when there is a composio CLI account connected by the user.

  • From the actual path of this SKILL.mdthat the runtime reported, set the parent folder as SKILL_ROOT. ~/.claude/skills We do not assume a specific installation path such as this. All references/, templates/, harness/, scripts/, engines/below are relative to this folder.
  • Set the absolute path of the output folder as PROJECT_ROOT. Distinguish the two paths, and run scripts with absolute paths such as python3 "$SKILL_ROOT/harness/gate.py" <단계> "$PROJECT_ROOT". Run auxiliary scripts in the output folder as bash "$SKILL_ROOT/scripts/<파일>.sh" ....
  • Python 3, ffmpeg, and ffprobe are required. .sh scripts require Bash (macOS/Linux or WSL on Windows). The engine requires Node.js 24 or later. For reference analysis, install scripts/requirements-ref.txtOpenCV in a virtual environment.
  • Do not install the engine (engines/remotion, engines/hyperframes) inside the skill folder. The skill folder is a copy shared by multiple runtimes. Copy it with cp -R "$SKILL_ROOT/engines/<엔진>" "$PROJECT_ROOT/engine"and then run npm ciinside it.
  • At the start, check the file reading, terminal, image viewing, and generation tools actually provided. If there is no generation tool, provide prompts and save locations and continue by receiving files the user has created. Do not assume that a subscription alone allows API access or automatic generation.
  • Runtimes that cannot view images request the user's actual visual inspection results. Do not create inspection records for frames you have not seen on the user's behalf. If the inspection script cannot be run, relay the command and judge the result only after receiving the actual exit code and report.
  • STORY.mdKeep the Korean item names and table structure of the provided template, and fill in the content in the user's language. The gate reads these item names. In character.txtother than Korean, write the #RRGGBB color code together with the color name (recognizable in the current color check).

What to decide before starting

When starting work, ask the user the 6 items below all at once and STORY.md record them at the top.

  1. Release type: whether it is a private draft or a final version released commercially. (The release type determines the cost rules. references/cost-rules.md)
  2. Length and aspect ratio: 1590 seconds (default 3090초), 16:9.
  3. Available tools and subscription status: which of image generation, video generation, music, and voice tools can be used.
  4. Prohibitions: elements not to include in the video (e.g., logos, real people, legible text).
  5. Reference video: whether there is a video to follow "in this style." If so, do step 0 first.
  6. Engine: Remotion or HyperFrames. If it is hard to decide, recommend based on the "Engine selection" criteria below.

6 production steps

Each step has a deliverable, and the Harness gate below must finish with exit code 0 before moving to the next step. Before working, read the Gotchas (list of pitfalls) below first.

Step What to do Tools used (examples) Deliverable
0. Reference analysis Decompose the reference video with OpenCV and record editing rhythm, movement, blur, depth, grain, and texture as numbers, and have the plan cite those numbers scripts/ref-analyze.py ref/ANALYSIS.md, ref/targets.json
1. Story and scene planning Confirm the one-line plot, scene list (time, place, action, dialogue), and music sync points Current agent STORY.md, scene list
2. Character sheet A reference image that fixes front, side, expression, and costume on one sheet Image generation tool Character sheet PNG, appearance lock statement
3. Keyframes Generate one starting frame per scene Image generation tool Keyframe PNG
4. Video conversion Fix the keyframe as the starting frame and generate a 3-6 second clip Video generation tool mp4 per scene
5. Music and voice One music track, one character voice (fixed ID), dialogue audio Music and voice tools Music wav/mp3, dialogue wav
6. Assembly Place cuts to the beat grid, subtitles, titles, end card motion graphics, mix, mux Engine (Remotion or HyperFrames), ffmpeg Final mp4

Gotchas (read first)

These are 8 common pitfalls. All 29 (symptom, cause, prevention, harness check ID) are in references/gotchas.md.

  1. Even if a clip has the same starting frame, clothes, glasses, and hair change after 1-2 seconds. Do not pass it by looking only at 0 seconds; place 0, 1.0, 1.5, 2.0, and 3.0 seconds in a row and look at them. (G01)
  2. Numbers like SSIM cannot catch character deformation. Even a normal clip's value drops when it moves. Only the start-screen match is enforced by numbers; everything else is checked by eye. (G02)
  3. The appearance lock text is pasted verbatim from the file. Rewriting it by hand changes it. Write down the clothing color. (G03)
  4. Cut lengths are set in multiples of beats, not seconds, and the start frame is rounded only once from the cumulative time. (G11, G12)
  5. Measure the dialogue length first, then set the cut length. If the dialogue is longer than the cut, the mouth gets cut off. (G13)
  6. Piping (| tail) truncates the check output and the exit code disappears. Judgments are made from the harness's exit code and the report file. (G21)
  7. When reading the frame count, using ffprobe -of csv=p=0makes it read like 30,, which can block a normal video. Use -of default=nw=1:nk=1. (G27)
  8. A finished render is not grounds for passing. Count the frames and look at the contact sheet yourself. (G08, G28)

Harness (stage gates)

Each stage's deliverables are measured by harness/gate.pyand judged by exit code. Until the gate passes (exit code 0), do not move to the next stage and do not report completion.

python3 "$SKILL_ROOT/harness/gate.py" <단계> "$PROJECT_ROOT"
Production stage Gate Checks
0. Reference analysis ref Before planning: ANALYSIS.md blanks, targets.json format. After rendering: compare the render analysis against the target values for each metric (target, value, difference %, tolerance range)
1. Story and scene planning story STORY.md blanks, BPM, music sync point table (whether times are numbers), scene table
2. Character sheet character character.txt (one paragraph of plain text, color descriptions), sheet image
3. Keyframes keyframes Duplicate files, aspect ratio versus the clip
4. Video conversion clips Length, frame count, start-screen match, frame strip generation, visual review record and per-clip verdict
5. Music and voice audio One voice ID, dialogue files
6. Before assembly edit Beat grid (cut boundaries), cut connections, repeated cuts, dialogue length, src clips and used segments
6. After assembly final Frame count, resolution, fps, audio length, loudness, true peak, visual review record
  • The project folder rules are at the start of harness/gate.py . (STORY.md, character.txt, voices.json, edit.json, sheet/, key/, clip/, out/final.mp4, qa/) Clip names, keyframe names, and edit.json의 clip:<이름>@<시작초>use the same names.
  • The gate leaves a report in qa/gate-<단계>.txt. When reporting, quote the lines from this file's BLOCK, WARN verbatim.
  • Checks that require visual inspection demand a record file. Write the lines below only after the agent has actually viewed the frame strips and contact sheets or has received the user's actual review results.
    • qa/clips-review.md: REVIEWED: <이름> <YYYY-MM-DD> lines, and per clip <클립 이름>: ok|trim|redo|replace 줄. redo, replaceIf any remain, it does not pass. Clips without keyframes are nokey: <클립 이름> allowed as lines.
    • qa/review.md: REVIEWED: <이름> <YYYY-MM-DD> and the line where the main result is written. It must be written later than the final cut (out/final.mp4).
  • The threshold is changed via an environment variable. (GATE_REF_TOL_SCALE, GATE_SSIM_START, GATE_LUFS, GATE_LUFS_TOL, GATE_TP_MAX)
  • The gate does not care about the engine. ref와 finalonly captures the finished mp4. ref/ If the folder does not exist, ref the gate leaves one WARN line and skips.
  • If you fix a gate or add a new check, bash "$SKILL_ROOT/harness/selftest.sh"must exit with code 0. It is a self-test that verifies a case that should be blocked is actually blocked with a synthetic project, and new checks add a case that should be blocked along with them.

Step-by-step details

Step 0. Reference analysis

  • If the user provides a reference video, decompose it before planning. Do not commit the reference file or its frames to the repository; leave only the numbers.
  • python3 -I "$SKILL_ROOT/scripts/ref-analyze.py" <레퍼런스.mp4> -o "$PROJECT_ROOT/ref/analysis.json" --targets "$PROJECT_ROOT/ref/targets.json" (run with python3 of the virtual environment where OpenCV is installed)
  • templates/ANALYSIS.md를 ref/ANALYSIS.mdand fill in the numbers and what those numbers mean for this work. gate.py refmust pass before moving on to Step 1.
  • Plans after Step 1 (cut length, hold, transition, blur, texture) cite the numbers in ANALYSIS.md. After rendering, analyze the final cut with the same script, write it to qa/render-analysis.jsonand compare with gate.py ref.
  • The meaning of the metrics, how to measure them, what to fix when they differ, and actual examples are in references/reference-analysis.md.

Step 1. Story and scene planning

  • templates/STORY.mdand fill it in. For each scene, write the time of day, location, one character action, and one emotion.
  • Put only one action in one scene. Video generation models distort hands and props when a clip has multiple actions.
  • Check that the time of day and location connect logically. If a sunrise scene comes after a morning commute scene, time runs backward.
  • Decide the music sync points (drop, final hit) in seconds during planning and do not change them afterward.

Step 2. Character sheet

  • templates/CHARACTER_SHEET.mdto check the sheet. The templates for the sheet, keyframes, and clip prompts are in templates/PROMPTS.md.
  • Once the sheet is confirmed, save the appearance lock sentence(a sentence describing hair, glasses, outfit, and colors in one paragraph) to the character.txt file. From then on, paste the sentence from this file verbatim into every prompt.

Step 3. Keyframes

  • Include the same character sheet as a reference image in all keyframe generation, and attach the appearance lock sentence verbatim.
  • Place the generated image side by side with the sheet, compare face, hair, glasses, and outfit, and use only the ones that pass.
  • Image generation tools sometimes save the same image twice (G09), so filter duplicate files by hash (md5).

Step 4. Video conversion

  • Set the keyframe to the video's Start screenand include the character sheet as a reference image.
  • Keep clip length short at 3–6 seconds. The longer it is, the more faces melt or props disappear toward the end.
  • For generated clips, use bash "$SKILL_ROOT/scripts/clipsheet.sh" <클립.mp4>to create a frame sheet (every frame of the clip, default qa/sheets/) and check it visually, then cut out defective sections and use only the usable sections. (Recorded intemplates/SCENE_AUDIT.md)
  • When compositing only the character from a clip generated with a green background, use scripts/key-plate.sh.

Step 5. Music and voice

  • First fix the music BPM, then use the calculation of references/beat-grid.mdto align cut lengths in beat units.
  • For voice, pick one voice in the tool and use only that ID for all dialogue. After synthesizing the dialogue, use transcription (whisper) to check that it matches the script.
  • Do not use voice cloning models of celebrities, politicians, or copyrighted characters.

Engine selection

Choose one of two engines for building the screen. Both engines are included in the skill, and their versions are fixed. Detailed comparison and commands are in references/engines.md.

  • Remotion (engines/remotion/): Compute values for every frame with React. Only here is there a check that numerically measures before rendering whether something survives at each boundary (carry), and a wordcut template where a single word stays in one place and the scene takes it over. For-profit organizations with 4 or more employees require a Remotion Company License.
  • HyperFrames (engines/hyperframes/): Animate an ordinary HTML/CSS page with GSAP and render to mp4. Good when the material is a webpage or document, or when someone who knows HTML needs to fix it directly. It is Apache-2.0. Since there is no declared track, it cannot produce a carry score, and motion is captured in mp4 by gate.py ref.
  • If it is hard to decide, start with Remotion, and if the license terms do not fit, use HyperFrames.

Step 6. Assembly

  • Copy the engine folder to the working folder and install with npm ci(do not install inside the skill folder).
  • carry is the default boundary. carry is this skill's term for an element that survives across a boundary. At each beat boundary, an element that was on screen survives and moves or grows into the next beat. Scene replacement where nothing remains (hard cut, dissolve, wipe) is used only within a rush (montage) or when going to the end card. The vocabulary is in references/art-direction.md.
  • Remotion: Motion is written as a pure function of motions/, and per-work geometry is written as pure scene(t). Screen and track.tsread the same scene(t). Before rendering, measure carry with node pipeline/probe.mjs productions/<id>(FAIL below 0.5), look at stills (node pipeline/render.mjs <id> --stills 0.5 1.5 3.0) directly, then render the video (renders/<id>/). productions/carry-demo/is an example for every file).
  • The beat sheet is written together with templates/BEATSHEET.md로 timing.ts. Note the element that survives at every boundary.
  • A video in which a single word is passed through multiple scenes (a match cut, graphic match cut) is made by changing only productions/wordcut/의 data.tsWhen there is a reference, extract timing with node productions/wordcut/plan.mjs "$PROJECT_ROOT/ref/analysis.json" <초>, and measure in pixels whether node productions/wordcut/drift.mjskeeps the word in one place (exit code 1 if it exceeds 0.5px). The first frame is not a page but a medium shot. The word is centered, only the word line is in a sharp focus band (shallow depth of field), lens texture from frame 0 (RGB separation, grain, vignette), no page chrome, color only in highlights. node productions/wordcut/frame0.mjs --checkverifies this. Not only the first frame. In every scene only one word is sharp, and the lines above and below get blurrier the farther they are from the word line. Each scene changes angle (paper on a desk, phone in hand, straight on), zoom (close, closer, very close), depth of field, floor, light and grain, and no two neighboring scenes use the same angle + zoom + depth-of-field combination (timing.ts의 shots). node productions/wordcut/focus.mjs --checkmeasures the focus ratio of the landing frame in each scene and exits with code 1 if it is below 2.
  • For voice, first generate the dialogue, measure its length, and then set the timing (pipeline/vo.mjs, pipeline/vo-assemble.mjs, composio CLI. references/providers.md). Since credits are incurred, notify the user before generating.
  • Music starts with the default score of node pipeline/score.mjs productions/<id>, or is delegated to a worker with templates/MUSIC_BRIEF.md.
  • Mix and mux are done with bash "$SKILL_ROOT/scripts/mix-mux.sh" <picture.mp4> <fps> <초> <music.wav> <vo.wav|-> <out.mp4>. Mux only when the frame count matches, and lower the music when dialogue plays.
  • The final check is done with bash "$SKILL_ROOT/scripts/verify.sh" <mp4>(PRODUCTION=productions/<id>(also performs the carry check if given), and you look at the generated contact sheet yourself. If there is a reference, compare with gate.py ref.

Timeline editor (for when a person edits directly after assembly)

  • To let the user view and edit the created video as a timeline, run node "$SKILL_ROOT/timeline/serve.mjs" "$PROJECT_ROOT". Four tracks—video, text, voice, and music—appear in the browser. It uses only the Node standard library and ffmpeg (no installation).
  • The base file is the single file edit.json . To the cutsthat the gate reads, add the optional tracks text(subtitles) and audio(voice/music: file, t, in, d, gain dB, fadeIn, fadeOut, the music's duck). The format is in timeline/README.md. Write the voice item's id는 voices.jsonto be the same as the dialogue id.
  • Agents also edit with the same core: node "$SKILL_ROOT/timeline/apply.mjs" "$PROJECT_ROOT" ops.json(run without arguments to print the timeline and problem list). An open editor receives changes within 2 seconds. After the user edits in the editor, re-read with apply.mjsand continue.
  • The result is produced with node "$SKILL_ROOT/timeline/build.mjs" "$PROJECT_ROOT"(same as the editor's Build button) to create out/final.mp4. Cuts are trimmed frame by frame from the source, audio is mixed by applying position, gain and fades per item (music is lowered under voice), text is burned into the screen (requires libass. On macOS, brew install ffmpeg-full, found automatically by the build) and out/captions.srtis also used. If libass is missing or --no-burn, it is included only as a subtitle track. Then gate.py edit, gate.py finalruns.
  • On the first save, copy the original to edit.json을 qa/timeline/.

Brand intro video and homepage (recipe)

The request "I want to put a video introducing our shop on the homepage" is built in this order. Without a new engine, use the wordcut template and templates/homepage-intro.html. The detailed order and examples are in references/brand-intro.md.

  1. Read the references (step 0 if any) and write the shot list in 4 lines or fewer. One line = frame range, screen, reference borrowed.
  2. Choose 3–6 keywords that determine the image prompt and the ending. One of them becomes the wordcut word.
  3. Generate the ending image. Match the aspect ratio to the video and leave the word slot empty.
  4. Create the cut with wordcut. If you put the ending image in data.ts의 closing, the last beat stops on that image.
  5. One homepage page: the hero is a Three.js scene whose t=0 frame is the video's ending image. The 9:16 video appears only on phones as a short card and is hidden on desktop. The match cut connecting the end of the video from the YouTube opening to the site's first frame is made in video editing, not on the page. The starting point is templates/homepage-intro.html, and if reduced motion is set or WebGL is unavailable, show only the poster (last frame) and the regular page. Spacing, section layout, and external library rules are also in references/brand-intro.md.

7 character consistency rules

The character sheet, appearance lock statement, keyframe opening screen, voice lock (same voice ID), dialogue and lip-sync timing, music beat, and quality check must all work together for the face and voice to stay the same even when scenes change. Per-item problems and how to align them are in references/consistency-7.md.

Cost branching rules

Create drafts on the free plan, and regenerate only the music and voice of the final version for commercial release on a paid plan. Before a paid bulk generation, state the estimated credits and get approval. The full rules are in references/cost-rules.md, and the current terms are in references/licensing.md.

Review principles

  • Do not report as passed anything you have not seen with your own eyes. "The render finished" is not grounds for a pass.
  • Measure what can be measured: frame count, duration, loudness (LUFS), true peak, and whether the transcription matches. For stages with a harness, judge by the harness's exit code.
  • Do not report having listened to audio you have not actually listened to. Report that it was verified by transcription and loudness.
  • The results report includes measured values, what was fixed, remaining defects, and artifact locations.

For mistakes without a harness check, see references/pitfalls.md; for per-tool usage, see references/providers.md.

Scripts (all under scripts/ , run from the project folder)

File Purpose
ref-analyze.py Decompose a reference (or render) video with OpenCV into a single JSON (requirements-ref.txt)
dupcheck.py Repeated cut detection using the same keyframe
clipsheet.sh Frame sheet (all frames of a clip laid out in a 6x5 grid)
key-plate.sh Green background -> transparent PNG
mix-mux.sh Music/dialogue mix and frame-count gate mux
verify.sh Video measurement, repeated frames, edge colors, contact sheet, dictation, optional carry check
beat-grid.py BPM-based beat length and snap calculation
../harness/gate.py Determine pass/fail at each step via exit codes
../timeline/serve.mjs, apply.mjs, build.mjs Timeline editor, editing CLI for agents, edit.json → mp4 build

Scripts in the engine folder (pipeline/render.mjs, probe.mjs, score.mjs, vo.mjs, vo-assemble.mjs, productions/wordcut/*.mjs)는 references/engines.mdare organized in.