프로모-비디오은(는) 무엇을 하나요?

원본 클립(세로/정사각형/가로)으로 짧은 프로모션 비디오를 조립합니다. 선택적 블렌더 렌더링 인트로/아웃트로, 선택적 AI 생성 음악.

이 스킬은 호스트 에이전트에 독립적입니다. Agent Skills 표준(https://agentskills.io)을 구현한 모든 런타임(Claude, Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, Cline, OpenCode, OpenHandes, Goose, Kiro, Junie 등)에서 동일하게 작동해야 합니다. 호스트별 도구(AskUserQuestion, 슬래시 명령어, 명시적으로 사용 가능하지 않은 MCP 등)에 절대 의존하지 마십시오. 모든 사용자 상호작용은 일반 채팅 메시지로 수행하십시오.

사용 시기

"이 클립들을 30초 릴로 편집해줘."
"해커톤 프로모션 비디오를 세로로 만들어줘."
"휴대폰 동영상 폴더가 있어 — 1080x1920 소셜 클립에 음악 넣어줘."
"로고 인트로 + 하트 아웃트로 + 배경 음악이 있는 프로모션을 생성해줘."
사용자가 .mov/.mp4 파일 디렉토리를 참조하며 하나의 결과물을 원할 때.

전제 조건

ffmpeg가 PATH에 있어야 하며, libx264, aac, prores_ks(알파 채널 인트로/아웃트로 MOV에만 필요)로 빌드되어 있어야 함.
Python 3.9+.
Python 종속성 한 번 설치: 스킬 디렉토리 내에서 pip install -r requirements.txt를 실행.
선택 사항: 프로젝트 루트에 SUNO_API_KEY가 포함된 .env 파일. 스킬은 키 설정 여부를 자동 감지하고 키가 설정된 경우에만 음악 생성을 제공합니다.
선택 사항: 인트로/아웃트로 렌더링을 생성하기 위해 호스트 에이전트에서 Blender MCP를 사용할 수 있어야 함. references/blender_mcp.md를 참조하세요.

기본 흐름 (대화 기반)

0단계 — 마지막 실행 이후 클립 변경 여부 감지

질문을 하기 전에, 사용자가 이전 세션에서 재개하는지 확인합니다. gallery/.clips_snapshot.json이 존재하거나(또는 사용자가 이전에 사용된 클립 폴더를 가리키는 경우) 다음을 실행합니다:

python scripts/clip_diff.py <clips_dir>

종료 코드 0 — 클립 폴더가 마지막 스냅샷과 일치합니다. 계속 진행합니다.
종료 코드 1 — 변경이 감지됨. 보고서에 새로 추가/제거/수정된 클립이 나열됩니다. 사용자에게 표시한 후 scripts/gallery.py를 다시 실행하여 갤러리가 새 클립을 인식하도록 제안합니다. 여전히 존재하는 클립에 대한 기존 선택은 그대로 유지됩니다.
종료 코드 2 — 아직 스냅샷이 없음. 정상적인 첫 실행이므로 계속 진행합니다.

기존 프로젝트를 재개할 때 이 단계를 건너뛰지 마십시오. 오래된 갤러리/selection.json을 사용하여 "내 새 클립이 어디 갔지?" 버그가 발생하는 전형적인 원인입니다.

질문

시작할 때 사용자에게 아래 질문을 순서대로 합니다. 자연스러운 답변을 수용하고, 호스트가 지원하지 않는 한 객관식 UI를 제시하지 마십시오. 모든 질문에 대해 "당신이 결정하세요"라는 답변도 수용하고 합리적인 기본값을 적용합니다.

대상 형식. 1080x1920 세로(기본값), 1920x1080 가로 또는 1080x1080 정사각형. 사용자 정의 크기도 허용.
클립 소스. 원본 클립이 포함된 디렉토리의 절대 또는 상대 경로. .mov, .mp4, .m4v가 지원됩니다.
대상 길이(초). (일반적으로 20–45초)
음악. (a) 기존 오디오 파일, (b) Suno를 통해 생성(SUNO_API_KEY가 설정된 경우에만 제공), (c) 음악 없음 중 하나.
인트로. 없음, 정적 이미지(경로), Blender MCP 생성 중 하나.
아웃트로. 인트로와 동일한 선택.
감독 모드. 예 또는 아니오. 예인 경우 여기서 선형으로 계속하지 않고 references/director_mode.md를 따릅니다.

그런 다음 클립 선택을 처리합니다. 두 가지 경로를 제공합니다:

A) 시각적 갤러리(클립이 10개 이상이거나 사용자가 프레임을 보고 신호점을 선택하려는 경우 권장). scripts/gallery.py <clips_dir> --resolution WxH --fps 30 --target-length N을 실행합니다. 축소판, IN/OUT 슬라이더, 속도 슬라이더, 범위 미리보기가 포함된 gallery/gallery.html을 생성합니다. 사용자에게 브라우저에서 열고, 클립을 선택하고, 신호점을 설정한 다음 "Export selection.json"을 클릭하도록 안내합니다. 다운로드된 파일은 build.py에 사용할 준비가 됩니다.

B) 인라인 대화(소규모 배치 또는 브라우저를 사용할 수 없는 경우 적합). 각 클립을 직접 처리합니다:

cue_in 및 cue_out(초 단위, 트림 범위)
speed 배수(1.0 = 원본 속도)
fixed: true(타이밍/속도를 수동으로 조정한 경우), false(자유 채움, 기본값: 중간에서 0.6초, 속도 1.0)

"그냥 기본값으로 줘"를 제공합니다. 모든 클립을 알파벳순으로 선택하고, 자유 기본값을 적용하며, 대상 길이까지 채웁니다.

어느 쪽이든 결과는 templates/selection.schema.json과 일치하는 selection.json입니다. 진행하기 전에 검증합니다.

빌드

selection.json이 유효하면 다음을 실행합니다:

python <skill>/scripts/build.py <selection.json> --out output/<name>.mp4

build.py는 build/(현재 작업 디렉토리 기준) 아래에 중간 아티팩트를 씁니다: build/normalized/, build/trimmed/, build/montage.mp4, build/composed.mp4. 전체 재렌더링을 강제하려면 build/를 삭제합니다.

scripts/ 아래의 모든 하위 모듈은 단독 실행도 가능하며, 전체 파이프라인을 다시 빌드하지 않고 한 단계를 반복하는 데 유용합니다. 각각 --help 인수를 지원합니다.

감독 모드 (선택 사항)

옵트인. 역할 프롬프트는 references/director_mode.md를 참조하세요. 스킬은 네 개의 순차적 역할(내레이터 → 커터 → 작곡가 → 감독자)을 생성하며, 이들은 selection.json을 상태로 공유합니다. 각 역할은 현재 JSON을 읽고 업데이트를 다시 씁니다. 사용자가 "더 안내된 프로세스" 또는 "프로듀서처럼 안내해줘"를 요청할 때 사용합니다.

음악 생성 (선택 사항)

사용자가 "Suno를 통해 생성"을 선택한 경우, 음악 생성 단계를 references/song_builder_agent.md에 정의된 Song-Builder 하위 에이전트에 위임합니다. 해당 하위 에이전트는:

사용자에게 장르, 분위기, BPM 범위, 섹션 구조, 악기 사용 여부를 묻고 비디오 길이를 기간으로 사용합니다.
Suno 프롬프트 + 스타일 태그를 작성합니다.
scripts/music.generate_song(spec)을 호출합니다. 사용자가 비교할 옵션을 원하면 takes > 1을 제공합니다.
선택한 테이크를 비디오 길이에 맞게 자르고 페이드합니다.
최종 mp3 경로를 audio로 selection.json에 씁니다.

호스트가 하위 에이전트 메커니즘(예: Claude Code의 에이전트 도구)을 제공하면 사용합니다. 그렇지 않으면 동일한 스레드에서 역할을 인라인으로 수행합니다.

Blender MCP 통합 (선택 사항)

지원만 제공합니다 — 이 스킬은 Blender 씬을 번들로 포함하지 않습니다.

사용자가 Blender로 렌더링된 인트로 또는 아웃트로를 원하는 경우, references/blender_builder_agent.md에 정의된 Blender-Builder 하위 에이전트에 위임합니다. 이 하위 에이전트는 전체 흐름(사전 점검: 이 호스트에서 Blender + MCP에 실제로 연결 가능한지 확인), 디자인 인터뷰(시각적 방향, 색상, 길이), 씬 빌드, 반복 미리보기, ProRes 4444 알파 MOV로 렌더링, MOV 경로를 selection.json으로 전달을 담당합니다.

호스트가 하위 에이전트 메커니즘(예: Claude Code의 에이전트 도구)을 제공하면 실행합니다. 그렇지 않으면 역할을 인라인으로 수행합니다. 기본 대화 흐름은 사용자가 설문조사의 5단계에서 인트로 또는 아웃트로에 대해 "Blender MCP 생성"을 선택할 때마다 Blender-Builder를 호출해야 합니다.

설정 문서(Blender 설치, MCP 서버 설치, 호스트에 등록)는 references/blender_mcp.md에 있습니다. Blender-Builder 하위 에이전트는 사용자가 처음으로 스택을 구성해야 할 때 해당 문서에서 정보를 가져옵니다.

오류 복구

클립 정규화(코덱/해상도 경계 사례)가 실패하면 build.py는 0이 아닌 코드와 문제 파일을 가리키는 명확한 stderr 메시지와 함께 종료됩니다. 사용자에게 클립을 건너뛸지 또는 조사할지 묻습니다.
Suno가 4xx를 반환하거나 시간 초과되면 사용자에게 재시도, "기존 파일"로 전환, 또는 음악 없이 진행할 것을 제안합니다.
클립을 조용히 삭제하지 마십시오. --force가 전달되지 않는 한 기존 출력 파일을 확인 없이 덮어쓰지 마십시오.

이 스킬에 대한 스타일 참고 사항

호스트별 도구를 절대 가정하지 마십시오. 모든 대화는 일반 채팅입니다.
작업 내용을 보여주십시오. 트리밍할 때 빌드하기 전에 어떤 신호점을 결정했는지 사용자에게 알려주십시오.
실패 시 명확히 알리십시오. ffmpeg가 없으면 그렇게 말하고 사용자 플랫폼에 맞는 설치 명령을 보여주십시오.

프로모-비디오