motion-video-production

한국어 · English

음악과 목소리를 담은 15~90초 mp4를 만드는 Agent Skills 형식의 제작 스킬이에요. 모션 그래픽, 홍보 영상, 캐릭터 영상을 만들어요. 단계별 게이트, 레퍼런스 분석기, 렌더 엔진 두 개(Remotion, HyperFrames)가 들어 있어요.

Codex, Claude Code와 다른 스킬 지원 런타임에서 같은 스킬 폴더를 써요.

빠른 시작으로 만드는 5초 타이포그래피 데모예요. carry는 컷이 바뀔 때 화면 요소가 하나라도 이어지는 컷 전환의 비율이에요. 완성 mp4에는 음악만 있고 목소리는 없어요. 위 GIF에는 소리가 없어요. 캐릭터와 목소리를 넣는 흐름은 첫 요청에서 시작해요.

바로 가기 · 빠른 시작 · 설치 · 들어 있는 것 · 레퍼런스 분석 · 사용 흐름 · 하네스 · 캐릭터 일관성 7가지 · 자주 겪는 함정 · 참고 문서 · 필요한 도구 · 알려진 한계 · 검증 범위

빠른 시작

스킬을 설치한 뒤(방법은 설치) 엔진을 작업 폴더로 복사해 데모 하나를 렌더해요. Node.js 24 이상과 ffmpeg가 필요해요. 스킬 폴더 안에서 npm ci를 실행하지 않아요. MacBook Air M3에서 아래 명령 전체는 약 28초 걸렸어요(엔진 의존성 설치 포함, 브라우저는 캐시 사용).

SKILL_ROOT="$PWD/.agents/skills/motion-video-production"   # 실제 설치 경로
# 찾기: ls -d .agents/skills/motion-video-production .claude/skills/motion-video-production ~/.agents/skills/motion-video-production ~/.claude/skills/motion-video-production 2>/dev/null
# 개인 설치면 "$HOME/.agents/skills/motion-video-production" 또는 "$HOME/.claude/skills/motion-video-production"
# engine/이 이미 있으면 mkdir에서 멈춰요. 지우거나 다른 이름을 써요(있는 폴더에 cp -R 하면 engine/remotion으로 중첩돼요)
mkdir engine && cp -R "$SKILL_ROOT/engines/remotion/." engine && cd engine && npm ci
# 컷 전환의 carry를 검사해요
node pipeline/probe.mjs productions/carry-demo              # carry 1.00 PASS
node pipeline/render.mjs carry-demo --stills 1.5 3.0        # renders/carry-demo/contact.png
node pipeline/render.mjs carry-demo                         # renders/carry-demo/picture.mp4
node pipeline/score.mjs productions/carry-demo              # 절차적 스코어
# <영상> <fps> <초> <음악> <대사, -는 없음> <출력>
bash "$SKILL_ROOT/scripts/mix-mux.sh" renders/carry-demo/picture.mp4 60 5 productions/carry-demo/audio/score.wav - out/final.mp4
bash "$SKILL_ROOT/scripts/verify.sh" out/final.mp4

렌더 브라우저는 CHROME_PATH나 캐시된 Playwright 헤드리스 셸을 써요. 둘 다 없으면 npx remotion browser ensure가 내려받아요(내려받기 전에 에이전트가 먼저 물어요).

설치

스킬을 쓸 프로젝트 폴더에서 실행해요. Node.js와 npx가 필요하고, 쓸 런타임을 골라 설치해요.

npx skills add unclejobs-ai/motion-video-skill --skill motion-video-production

Codex만 지정하려면 아래처럼 실행해요. 개인 범위로 설치하려면 --global을 더해요.

npx skills add unclejobs-ai/motion-video-skill --skill motion-video-production --agent codex

Vercel skills CLI가 Codex, Claude Code, Gemini CLI, Cursor, GitHub Copilot, OpenCode, Amp, Antigravity, Windsurf 등의 설치 위치를 처리해요. 엔진은 스킬 폴더 안에 있어서 함께 설치돼요. 설치 호환성과 전체 영상 제작 검증은 달라요. 런타임별 설치·호출과 검증 범위를 참고해요.

Codex는 프로젝트 .agents/skills/와 개인 ~/.agents/skills/에서 스킬을 읽어요. 아래는 개인 설치 예시예요.

git clone https://github.com/unclejobs-ai/motion-video-skill.git
mkdir -p ~/.agents/skills
cp -r motion-video-skill/skills/motion-video-production ~/.agents/skills/

Claude Code는 프로젝트 .claude/skills/와 개인 ~/.claude/skills/에서 스킬을 읽어요.

git clone https://github.com/unclejobs-ai/motion-video-skill.git
mkdir -p ~/.claude/skills
cp -r motion-video-skill/skills/motion-video-production ~/.claude/skills/

한 프로젝트에서만 쓰려면 그 프로젝트의 런타임별 스킬 폴더에 같은 폴더를 복사해요. 한 런타임에 같은 이름을 여러 경로로 중복 설치하지 않아요.

첫 요청

설치한 뒤 런타임의 스킬 목록에서 motion-video-production을 확인해요. 보이지 않으면 런타임을 새로 시작해요. Codex에서는 $motion-video-production, Claude Code와 Cursor에서는 /motion-video-production으로 부르거나 아래처럼 요청해요.

이 레퍼런스 영상 느낌으로 20초짜리 홍보 영상을 만들고 싶어.

에이전트가 먼저 6가지(공개 방식, 길이와 화면비, 쓸 수 있는 도구, 금지 요소, 레퍼런스 영상, 엔진)를 묻고 단계 순서대로 진행해요. 생성 도구가 없으면 프롬프트를 건네고, 사용자가 만든 파일을 받아 이어가요.

들어 있는 것

엔진은 바꿔 끼울 수 있어요. carry와 wordcut이 필요하면 Remotion, 재료가 웹페이지라면 HyperFrames가 맞아요. 비교는 references/engines.md에 있어요.

레퍼런스 분석

"이 영상처럼"이 가리키는 건 보통 질감보다 움직임과 편집이에요. 0단계에서 레퍼런스를 OpenCV로 분해해 컷과 홀드, 광학 흐름, 블러, 심도, 그레인, 질감을 숫자로 남겨요. 계획은 그 숫자를 인용해요. 렌더한 뒤에는 같은 분석으로 결과를 재고, gate.py ref가 지표마다 목표와 차이를 적고 범위를 벗어나면 막아요.

엔진 폴더가 아니라 프로젝트 폴더에서 실행해요. SKILL_ROOT는 빠른 시작과 같게 정해요.

SKILL_ROOT="$PWD/.agents/skills/motion-video-production"   # 실제 설치 경로
PROJECT_ROOT="$PWD"   # reference.mp4와 ref/를 둘 산출물 폴더
python3 -m venv .venv && . .venv/bin/activate && python3 -m pip install -r "$SKILL_ROOT/scripts/requirements-ref.txt"
mkdir -p ref qa && cp -n "$SKILL_ROOT/templates/ANALYSIS.md" ref/ANALYSIS.md   # 빈칸(<...>)은 분석을 보고 채워요
python3 -I "$SKILL_ROOT/scripts/ref-analyze.py" reference.mp4 -o ref/analysis.json --targets ref/targets.json
python3 "$SKILL_ROOT/harness/gate.py" ref "$PROJECT_ROOT"

움직임은 1/30초당 값으로 재서 fps가 달라도 비교돼요. 레퍼런스 파일은 커밋하지 않고 숫자만 남겨요. 지표 설명과 실제 예시는 references/reference-analysis.md에 있어요.

사용 흐름

1. 스킬이 단계 산출물을 만들어요 (ref/, STORY.md, character.txt, key/, clip/, voices.json, edit.json).
2. 설치된 SKILL.md의 부모 폴더를 SKILL_ROOT, 산출물 폴더를 PROJECT_ROOT로 정하고, 단계가 끝나면 python3 "$SKILL_ROOT/harness/gate.py" <단계> "$PROJECT_ROOT"를 실행해요.
3. 종료 코드 0이면 다음 단계로 가요. 1(BLOCK)이면 qa/gate-<단계>.txt의 BLOCK 줄을 읽고 고친 뒤 같은 게이트를 다시 실행해요.
4. 눈으로 봐야 하는 검사는 스크립트가 판정하지 못해요. 프레임을 보고 남긴 기록(qa/clips-review.md, qa/review.md)이 있어야 통과해요.

시작 화면이 같아도 1초 뒤에 인물이 달라질 수 있어요(G01). gate clips가 클립마다 qa/strip-<클립>.png를 만들어요.

gate.py clips 실행 예시예요. 눈 검수 기록이 없어서 BLOCK(종료 코드 1)이 나오고, 기록을 남기면 PASS(종료 코드 0)가 돼요.

하네스

게이트는 엔진 내부가 아니라 산출물 파일과 완성된 mp4만 읽어요. 그래서 어느 엔진으로 만들었든 같은 기준이에요.

SSIM 같은 유사도 값은 인물의 움직임과 변형을 구분하지 못해요(gotchas.md G02). 게이트는 시작 화면 일치만 숫자로 판정하고, 뒤쪽 프레임은 사람이 프레임 스트립을 보고 기록하게 해요.

저장소 폴더에서 bash skills/motion-video-production/harness/selftest.sh를 실행해요. 설치된 사본은 bash "$SKILL_ROOT/harness/selftest.sh"로 점검해요. 종료 코드 0이면 이 컴퓨터에서 검사 사례가 기대대로 동작해요.

캐릭터 일관성 7가지

장면이 바뀌어도 얼굴과 목소리를 같게 지키는 기준 7가지예요. 어느 제작 단계에서 적용하는지는 아래 그림과 references/consistency-7.md에 있어요.

자주 겪는 함정

전체 29가지는 references/gotchas.md에 증상, 원인, 예방, 검사 ID로 정리돼 있어요. 엔진 쪽 함정은 references/pitfalls.md에 있어요. 자주 부딪히는 것:

• 컷 길이는 박의 배수로 정하고, 시작 프레임은 누적 시간에서 한 번만 반올림해요. (G11, G12)
• 대사 길이를 먼저 재고 컷 길이를 정해요. (G13)
• 검사 | tail처럼 자르면 종료 코드가 사라져요. (G21)
• 아무것도 살아남지 않는 매끄러운 장면 전환도 carry 0.00이에요. 요소 하나를 컷 전환 너머로 옮겨요.

참고 문서

설치된 스킬 폴더 안에 함께 들어 있어요. 에이전트가 단계마다 필요한 문서를 읽어요.

필요한 도구

무료 범위와 상업 이용 조건은 NOTICE.md와 references/licensing.md(출처 URL 포함)에 있어요. Remotion은 직원 4명 이상 영리 조직에 Company License가 필요하고, HyperFrames는 Apache-2.0이에요. 약관은 자주 바뀌니 작업 직전에 다시 확인해요.

알려진 한계

• carry 검사는 Remotion 전용이에요. 렌더 전에 선언한 상자(track.ts)를 읽기 때문이에요. HyperFrames 렌더는 verify.sh, gate.py final, gate.py ref로 mp4에서 재요. mp4에서 carry를 재는 방식은 아직 없어요.
• wordcut 데모는 조정 전 첫 렌더예요. 레퍼런스 목표와 비교하면 gate.py ref가 12개 지표 중 10개에서 막아요. 그레인, 선명도 비, 대비가 특히 멀어요. look-fit.mjs와 plan.mjs를 다시 돌려 맞추는 과정이 이 스킬의 사용법이에요.
• 마무리 이미지를 켜면 carry 점수가 0.00(FAIL)이에요. 세지는 경계가 이미지가 페이지를 덮는 경계 하나뿐이고, 이 경계는 아무것도 넘어가지 않는 경계로 세지기 때문이에요. 다른 경계는 선언한 컷이라 면제돼요. 이 경계를 carry로 바꿔야 FAIL을 벗어나요.
• GSAP 라이선스 조항 전문은 확인하지 못했어요. HyperFrames 데모가 쓰는 GSAP 3.14.2는 README에 상업 이용도 무료라고 적혀 있어요. 상업용 영상을 공개하기 전에 https://gsap.com/standard-license 를 확인해요.

저장소 구조

README.md, README.en.md     한국어·영문 README
NOTICE.md, LICENSE          외부 도구 안내, MIT
docs/                       README 이미지(그림 원본 SVG 포함), 런타임별 설치·검증 범위
skills/motion-video-production/        설치하는 스킬 폴더 (아래 전체가 함께 복사돼요)
  SKILL.md                  스킬 본문
  references/               레퍼런스 분석, 엔진, 아트 디렉션, 일관성, 박 격자, 도구 메모, gotchas, licensing
  harness/                  gate.py(단계별 판정), selftest.sh(하네스 자체 검증)
  scripts/                  ref-analyze.py, mix-mux.sh, verify.sh, key-plate.sh, clipsheet.sh 외
  templates/                ANALYSIS.md, STORY.md, BEATSHEET.md, MUSIC_BRIEF.md 외
  engines/remotion/         carry 데모, wordcut 템플릿, 렌더·목소리·스코어 파이프라인
  engines/hyperframes/      HTML/GSAP carry 데모

검증 범위

2026-10-25에 커밋한 트리를 그대로 꺼내 설치하고 확인했어요. 스킬 파일 76개가 모두 설치됐어요. 엔진 npm ci, 타입 검사, 테스트 13개, carry 검사, selftest가 통과했어요. 두 엔진의 렌더를 verify.sh와 gate.py ref로 쟀고, HyperFrames 렌더는 gate.py final을 통과했어요. 외부 생성, 목소리 크레딧, 오디오 청취, 다른 일곱 런타임 안에서의 호출은 확인하지 않았어요. 자세한 내용은 docs/runtimes.md에 있어요.

만든 곳

이 스킬은 SceneSteller를 만드는 팀이 영상 제작 과정에서 쌓은 점검 기준을 정리한 것이에요. 스토리에서 영상까지 브라우저에서 바로 만들어 보고 싶다면 SceneSteller를 써 보세요.

책임 범위

생성물의 권리와 책임은 NOTICE.md와 references/licensing.md에 있어요.