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 asSKILL_ROOT.~/.claude/skillsWe do not assume a specific installation path such as this. Allreferences/,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 aspython3 "$SKILL_ROOT/harness/gate.py" <단계> "$PROJECT_ROOT". Run auxiliary scripts in the output folder asbash "$SKILL_ROOT/scripts/<파일>.sh" .... - Python 3, ffmpeg, and ffprobe are required.
.shscripts require Bash (macOS/Linux or WSL on Windows). The engine requires Node.js 24 or later. For reference analysis, installscripts/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 withcp -R "$SKILL_ROOT/engines/<엔진>" "$PROJECT_ROOT/engine"and then runnpm 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. Incharacter.txtother than Korean, write the#RRGGBBcolor 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.
- 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) - Length and aspect ratio: 1590 seconds (default 3090초), 16:9.
- Available tools and subscription status: which of image generation, video generation, music, and voice tools can be used.
- Prohibitions: elements not to include in the video (e.g., logos, real people, legible text).
- Reference video: whether there is a video to follow "in this style." If so, do step 0 first.
- 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.
- 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)
- 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)
- The appearance lock text is pasted verbatim from the file. Rewriting it by hand changes it. Write down the clothing color. (G03)
- Cut lengths are set in multiples of beats, not seconds, and the start frame is rounded only once from the cumulative time. (G11, G12)
- Measure the dialogue length first, then set the cut length. If the dialogue is longer than the cut, the mouth gets cut off. (G13)
- 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) - When reading the frame count, using
ffprobe -of csv=p=0makes it read like30,, which can block a normal video. Use-of default=nw=1:nk=1. (G27) - 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, andedit.json의clip:<이름>@<시작초>use the same names. - The gate leaves a report in
qa/gate-<단계>.txt. When reporting, quote the lines from this file'sBLOCK,WARNverbatim. - 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 arenokey: <클립 이름>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,refthe 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 withgate.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 intemplates/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.txtfile. 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, defaultqa/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 bygate.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 purescene(t). Screen andtrack.tsread the samescene(t). Before rendering, measure carry withnode 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 withnode productions/wordcut/plan.mjs "$PROJECT_ROOT/ref/analysis.json" <초>, and measure in pixels whethernode 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 withtemplates/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 withgate.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 thecutsthat the gate reads, add the optional trackstext(subtitles) andaudio(voice/music:file,t,in,d,gaindB,fadeIn,fadeOut, the music'sduck). The format is intimeline/README.md. Write the voice item'sid는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 withapply.mjsand continue. - The result is produced with
node "$SKILL_ROOT/timeline/build.mjs" "$PROJECT_ROOT"(same as the editor's Build button) to createout/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) andout/captions.srtis also used. If libass is missing or--no-burn, it is included only as a subtitle track. Thengate.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.
- Read the references (step 0 if any) and write the shot list in 4 lines or fewer. One line = frame range, screen, reference borrowed.
- Choose 3–6 keywords that determine the image prompt and the ending. One of them becomes the wordcut word.
- Generate the ending image. Match the aspect ratio to the video and leave the word slot empty.
- Create the cut with wordcut. If you put the ending image in
data.ts의closing, the last beat stops on that image. - 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 inreferences/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.