package.json도, 파이썬도, API 호출도 없다. 유일하게 "돌아가는" 파일은 README 검사용 bash 스크립트 하나뿐이다. 진짜 알맹이는 SKILL.md와 그것이 참조하는 계약서(contract) 문서들이고, 이들이 LLM을 단계별로 몰아 "글 → 6장면 감독 콘티 → 자립형 영상 프롬프트 6개"를 만들게 한다. 영상 자체는 렌더링하지 않는다 — 사람이 그 프롬프트를 Gemini Omni Flash에 붙여 넣는다.
kaomei/stickman-video-director · 라이선스 MIT · 형태 OpenAI Codex용 마크다운 에이전트 스킬 · 파일 29개(그중 21개가 .md) · 런타임 의존성 0개 · 다국어 README 5종(en·zh·ja·ko·pt) · 최신 커밋 2026-08-04 · 렌더 대상 Google Gemini Omni Flash · TrendShift Daily #12)
stickman-video-director는 "글 한 편을, 승인 절차를 거쳐 6장면짜리 감독 콘티로 바꾸고, 다시 Gemini Omni Flash용 영상 프롬프트 6개로 뽑아내도록 LLM을 조종하는, 마크다운으로만 쓰인 Codex 에이전트 스킬"이다. 겉보기엔 "AI 영상 생성 도구" 같지만, 열어보면 실행 코드는 없고 프롬프트 엔지니어링 계약서만 정교하게 쌓여 있다.
영상을 실제로 '찍는' 것은 Gemini Omni Flash라는 AI 모델이다. 이 저장소는 카메라를 들지 않는다. 대신 감독의 머릿속 규칙을 문서로 적어둔다 — "먼저 화면비와 톤을 정하고, 콘티부터 그려 승인받고, 그 다음에야 6개 장면 지시서를 쓴다. 색은 숫자코드 대신 '선명한 빨강'처럼 말로만 부른다"…
즉 이 레포가 파는 것은 영상이 아니라 '감독의 판단 절차'다. 그 절차를 LLM에게 통째로 이식해, 아무 글이나 넣어도 일관된 품질의 영상 프롬프트가 나오게 만든다.
SKILL.md(핵심 지시)와 참조 문서들로 이뤄진다. 코드가 아니라 자연어 지시서가 본체라는 점이 특징. Anthropic의 Claude 스킬과 같은 계열의 발상이다.사용자가 글을 던진 순간부터 영상 프롬프트가 손에 쥐어질 때까지, 이 스킬 안에서 벌어지는 일을 압축하면 이렇다:
여기서 핵심은 ①과 ③의 "게이트"다. 이 스킬은 자유롭게 술술 답하지 않는다. 정보가 부족하면 멈추고 묻고, 승인 없이는 다음 단계로 넘어가지 않는다. 코드로 치면 if 문으로 막아둘 흐름 제어를, 순전히 프롬프트 문장으로 구현한 것이 이 레포의 첫 번째 볼거리다.
첫째, 설치할 게 없다. 무거운 파이썬 환경도, GPU도, API 키도 필요 없다. 폴더 하나를 Codex 스킬 디렉토리에 복사하고 재시작하면 끝이다. 진입 장벽이 "git clone + cp" 두 줄이라, 누구나 5분 안에 써볼 수 있다는 점이 확산 속도를 만든다.
요리 로봇 vs 레시피 카드. 대부분의 AI 영상 도구는 재료·불·팬이 다 들어간 '요리 로봇'이라 설치와 유지가 무겁다. 이 스킬은 정교하게 쓰인 레시피 카드 한 장이다. 요리(생성)는 이미 당신 부엌에 있는 셰프(Codex + Gemini)가 하고, 이 카드는 "순서와 금기"만 정확히 일러준다. 그래서 가볍고, 어떤 부엌에도 얹힌다.
둘째, 텍스트-투-비디오의 '함정'을 정면으로 정리했다. AI 영상 모델을 써본 사람은 안다 — 화면에 깨진 자막이 뜨고, 색코드(#FF0000)가 글자로 박히고, 클립마다 캐릭터가 딴판이 된다. 이 스킬은 그 실패들을 "하지 마" 규칙 목록으로 못 박아 매번 재현되게 만든다. 색은 말로만(선명한 빨강), 대사는 오디오로만, 다음 클립 첫 프레임 = 이전 클립 마지막 프레임 … 이런 현장에서 얻은 크래프트(craft)가 문서의 진짜 값어치다.
가장 놀라운 지점. 이 스킬은 테스트 주도 개발(RED→GREEN) 방식으로 만들어졌다. tests/reports/baseline.md는 스킬이 없을 때 에이전트가 어떻게 실패하는지를 기록한다 — 압박을 받으면 화면비를 멋대로 16:9로 정하고, 최종 프롬프트를 몰래 뱉는다(셋업 게이트 0/5). forward.md는 스킬이 있을 때 매번 멈춰 묻는 걸 보여준다(5/5). 규칙 준수를 22개 항목(SETUP-1…PACK-6)으로 채점하는 evaluation-rubric.md까지 있다. "프롬프트도 소프트웨어처럼 검증한다"는 사고방식의 교보재다.
셋째, 사회공학적 압박에 견디도록 설계됐다. 셋업 게이트는 "급하다 / 생성 비용이 든다 / 그냥 표준으로 골라줘" 같은 재촉으로는 절대 면제되지 않는다고 명시한다. 또 "주제 승인"이나 "예전 초안 승인"은 "지금의 Phase A 승인"이 아니라고 못 박는다. 사람을 상대하는 에이전트가 어떻게 일관된 원칙을 지키게 만드는지 보여주는 좋은 사례다.
오해하기 쉬운데, 이 저장소는 영상을 만들어 주지 않는다. 최종 산출물은 마크다운 텍스트 — 붙여넣을 수 있는 프롬프트 6개다. 실제 렌더링·붙이기(stitching)·음성 이어붙이기는 사람이 Gemini Omni Flash와 편집 도구로 해야 한다. 또 대상 모델(Omni Flash)에 접근할 수 없으면 프롬프트가 있어도 결과물을 볼 수 없다. "프롬프트 품질"이 제품이지 "영상"이 제품이 아니다.
이 저장소에 프로그래밍 언어 스택은 없다(마크다운·YAML·bash 각 소량이 전부). 대신 에이전트 스킬을 구성하는 문서 계층이 곧 아키텍처다. 핵심은 점진적 공개(progressive disclosure) — 가벼운 SKILL.md가 진입점이 되고, 무거운 규칙은 필요할 때만 references/에서 불러온다.
| 계층 | 파일 | 역할 |
|---|---|---|
| 진입점 | skills/directing-stickman-videos/SKILL.md | 500단어 미만의 핵심 워크플로. "언제 무엇을 하고 무엇을 참조하라"만 담고, 세부는 참조 문서로 넘김 |
| 도구 메타데이터 | agents/openai.yaml | Codex UI에 표시될 이름·설명·기본 프롬프트. 이 스킬이 OpenAI Codex용임을 알려주는 부분 |
| Phase A 계약 | references/storyboard-template.md | 감독 콘티(스토리보드) 작성 규칙 — 나레이션 길이·표 형식·서사 패턴·품질 게이트 |
| Phase B 계약 | references/omni-flash-prompt-contract.md | 최종 영상 프롬프트 6개의 작성 규칙 — 12부 구성·연속성·금기 목록 |
| 완결 예시 | references/examples.md | 실제 카피 하나를 끝까지 처리한 워크드 예제. 애매할 때만 참조 |
| 테스트 | tests/ (rubric·reports·scenarios·verify-readmes.sh) | 규칙 준수 채점표 22개 + RED/GREEN 리포트 + 시나리오. 스킬을 "검증 가능한 것"으로 만듦 |
| 설계 이력 | docs/superpowers/ (plans·specs) | 스킬을 어떻게 만들지 설계·계획한 문서. "왜 이렇게 짰나"의 기록 |
| 현지화 | README.md 외 4개 언어 | en·zh-CN·ja·ko·pt-BR. bash 스크립트가 5개 README의 동기화를 강제 검사 |
SKILL.md가 "storyboard-template를 읽어라"라고만 지시하고, 실제 상세는 그 파일에 있는 식.~/.codex/skills/에 복사하면, 사용자가 $directing-stickman-videos로 호출한다. (Anthropic의 Claude Code 스킬과 발상은 같지만, 이 저장소는 Codex용으로 패키징돼 있다.)스킬의 "입구" 파일은 이렇게 생겼다. 짧지만, 아래 Setup gate / Workflow / Output rules 세 덩어리가 전체 흐름을 좌우한다:
# SKILL.md 발췌 — 이 짧은 문서가 곧 "제품"이다 --- name: directing-stickman-videos description: Use when turning copy, notes, articles, or topics into one-minute English stick-figure videos ... --- ## Setup gate # ← 시작 전 반드시 셋 확보 - source material - aspect ratio: 16:9, 9:16, or 1:1 - theme: light / dark 빠지면 한 번에 다 묻고 멈춤. "표준으로 골라줘" 요청에도 몰래 안 정함. ## Workflow # ← 참조 문서를 '필요할 때' 로드 (점진적 공개) 1. storyboard-template.md 읽고 Phase A 생산 2. 감독 제안서 후 멈추고 명시적 승인 요청 3. 화면비/테마/나레이션/구조 바뀌면 Phase A 재작성 → 재승인 4. 승인 후에만 omni-flash-prompt-contract.md 읽고 Phase B 생산 ## Output rules (일부) - 영어 VO 6클립 합쳐 130~150단어 - 강조색 3개까지, "vivid red"처럼 말로만 (hex/RGB/HSL/Pantone 금지) - 대사는 오디오 전용, 자막·캡션 금지 - 각 프롬프트는 자립형 — 모든 잠금(lock)을 반복해 넣음 - 클립 N의 끝 = 클립 N+1의 시작
런타임 의존성이 없다는 건 썩지 않는다는 뜻이다. npm 패키지가 낡거나 API가 바뀌어 깨질 일이 없다. 스킬의 값어치는 전부 자연어로 적힌 판단 규칙에 있고, 이는 모델이 바뀌어도(=더 똑똑해져도) 그대로 유효하거나 오히려 더 잘 지켜진다. "코드가 없다"가 약점이 아니라 이 장르의 설계 철학이다.
이 스킬의 뼈대는 두 개의 게이트로 나뉜 상태 기계(state machine)다. 각 상태는 명확한 통과 조건이 있고, 조건 미달이면 앞으로 못 간다. 코드가 아니라 지시문으로 구현됐다는 점만 빼면, 흐름은 여느 워크플로 엔진과 같다.
셋업 게이트와 승인 게이트는 이 스킬의 안전장치다. LLM은 원래 "도움이 되려고" 빈칸을 알아서 채우는 경향이 있는데, 영상 생성처럼 되돌리기 비싼 작업에서는 그게 독이 된다(잘못된 화면비로 6클립을 다 뽑아버림). 그래서 규칙은 재촉·비용·"알아서 해"를 모두 게이트 면제 사유에서 제외한다. 승인 게이트는 한 걸음 더 나가, "예전 초안 승인 ≠ 지금 초안 승인"이라고 승인의 유효 범위까지 못 박는다.
수술 전 체크리스트. 수술방에선 아무리 급해도 "환자 이름·부위·동의서"를 소리 내 확인하고서야 칼을 든다. 이 스킬의 셋업 게이트가 바로 그거다 — "급하니 그냥 시작하자"가 통하지 않는다. 6개 클립을 뽑는 건 마취처럼 되돌리기 번거로운 일이라, 시작 전에 못을 박아둔다.
가장 실전적인 설계. 각 ~10초 클립은 서로 기억을 공유하지 않는 독립 생성이다. 모델은 클립 2를 만들 때 클립 1에서 뭘 정했는지 모른다. 그래서 프롬프트 6개는 화면비·테마·캐릭터·팔레트·나레이터·오디오·전환·금기를 매번 통째로 반복한다. "중복이 낭비"가 아니라, 중복이 곧 일관성을 지키는 신뢰성 장치인 셈이다. 각 프롬프트는 고정된 12부 순서를 따른다:
# 자립형 프롬프트 12부 구성 (omni-flash-prompt-contract.md)
1. 출력 스펙: ~10초, 화면비, 720p, 24 FPS, 오디오 동기화
2. 배경 + 기본 라인아트 극성 (light=순백 캔버스, 음영·3D 금지)
3. 캐릭터 잠금: 빈 원형 머리, 얼굴/옷/채움 없음, 일정한 선 굵기
4. 3색 팔레트: 일상어 이름 + 의미 역할
5. 화면비별 구도 전략
6. 첫 프레임 상태 ← "이전 클립"에서 물려받음
7. [0–3s] / [3–7s] / [7–10s] 3비트 타임라인
8. 오디오 전용 영어 대사(따옴표 안), 딱 한 번
9. 나레이터 묘사/감정/전달 (동일 유지)
10. BGM + 동기화 SFX + 보이스 우선 믹싱
11. 마지막 프레임 상태 ← "다음 클립"이 물려받음
12. 네거티브(금지) 제약
독립 생성인데도 클립이 매끄럽게 이어지는 비결. 클립 N의 마지막 프레임 상태 = 클립 N+1의 첫 프레임 상태로 문장을 맞춰 쓴다. 예: 클립 1이 "보라색 선이 화면을 가득 채우며 끝"이면, 클립 2는 "그 동일한 보라색 엉킴 속을 통과하며 시작". 위 12부의 6번과 11번이 이 손잡이(handle)다.
텍스트-투-비디오 모델의 나쁜 버릇을 정확히 겨눈 규칙들. 두 개가 특히 교훈적이다:
#FF0000·RGB·HSL·Pantone를 프롬프트에 쓰면, 모델이 그 표기를 화면에 글자로 그대로 그려버린다. 그래서 "vivid red, electric blue, warm gold"처럼 일상어로만 부른다. 흰색조차 "digitally pure-white canvas"라 쓰지 #FFFFFF라 쓰지 않는다. (최신 커밋 제목이 바로 "Prevent color codes in generated videos".)아래는 실제로 생성되는 프롬프트 한 개의 모습이다(예제 "Clip 1 — Thought storm" 발췌). 위 12부·연속성·금기가 어떻게 한 덩어리 지시문으로 녹아드는지 보라:
Create an approximately 10-second 16:9 ... clip targeting 720p at 24 FPS with synchronized audio. Use a pure black background and one minimalist white stick figure ... Lock a hollow circular head, no face, no hair, no clothing ... Use only saturated anxiety violet, vivid danger red, and warm action gold as accents; this clip primarily uses violet. First frame: A stands alone with lowered shoulders in empty black space. [0–3s] ... a tiny violet thought dot appears ... pulses electrically ... [3–7s] ... the dot splits into hundreds of violet lines ... [7–10s] ... End with violet lines filling the entire frame for Clip 2. # ← 연속성 손잡이 Audio-only dialogue, exactly once: "Do you ever feel exhausted before ..." Do not display or transcribe the dialogue visually. # ← 자막 금지 Do not generate photorealism ... visible writing, technical color notation, palette labels, ... captions, subtitles, logos, or watermarks. # ← 네거티브
읽는 순서를 추천하면 이렇다: README.md(전체 그림) → SKILL.md(뼈대) → references/storyboard-template.md(Phase A) → references/omni-flash-prompt-contract.md(Phase B) → references/examples.md(완결 예제) → tests/reports/baseline.md·forward.md(왜 게이트가 필요한지 증거). 코드가 없으니 테스트 리포트가 곧 명세서이자 설득 자료 역할을 한다. baseline과 forward를 나란히 읽으면 "스킬이 있고 없고"의 차이가 손에 잡힌다.
if (!ratio) ask() 같은 흐름 제어를 자연어 규칙으로 구현하는 법. "빠지면 한 번에 묻고 멈춰라", "승인 전엔 다음 단계 금지" 같은 문장이 어떻게 결정적 동작을 만드는지 본다. 배울 것: 에이전트에게 멈출 줄 아는 절제를 심는 법, 면제 사유를 선제적으로 차단하는 문구 설계.
상태를 공유하지 않는 독립 생성들 사이에서 일관성을 유지하려면, "중복을 감수하고 모든 잠금을 매번 반복"하는 게 답이라는 통찰. 분산 시스템에서 멱등성(idempotency)·비공유 아키텍처를 다뤄본 사람에겐 익숙한 사고가, 프롬프트 설계에도 그대로 적용된다. 배울 것: 왜 "장황한 반복"이 때로 옳은 설계인가.
baseline(RED)→forward(GREEN) 리포트와 22개 채점 루브릭은 "프롬프트도 회귀 테스트가 필요하다"는 실천의 표본이다. 스킬 없을 때 무너지는 지점을 먼저 문서화하고, 스킬을 넣어 그 지점을 통과시키는 흐름. 배울 것: 프롬프트 변경이 기존 동작을 깨지 않았는지 확인하는 평가 하네스(eval harness)의 최소 형태.
모델을 직접 호출하지 않아도, 이 문서만 읽으면 영상 프롬프트 잘 쓰는 법이 손에 들어온다 — 색은 일상어로(코드 금지), 대사는 오디오 전용, 자막은 후반작업으로, 클립 연속성은 프레임 상태로 잇기. 배울 것: 생성 모델이 "프롬프트의 표기를 화면에 literally 그려버리는" 실패를 어떻게 피하는가.
얇은 SKILL.md + 필요 시 로드하는 references/ 구조로 컨텍스트를 아끼는 법, 그리고 5개 언어 README를 verify-readmes.sh로 동기화 검사하는 발상. 배울 것: 문서에도 "깨지면 CI가 잡는" 불변식을 걸 수 있다는 것(공유 섹션 마커·금칙어 검사).
Codex가 없어도 좋다. 아무 챗봇에 SKILL.md의 Setup gate 부분만 시스템 프롬프트로 주고, "급하니 그냥 시작해"라고 압박해 보라. 규칙이 있을 때(멈추고 물음)와 없을 때(멋대로 시작)의 차이를 직접 재현하면, baseline↔forward 실험을 축소판으로 체험할 수 있다.
| 구분 | 요구 |
|---|---|
| 스킬 실행 환경 | OpenAI Codex(스킬을 인식하는 버전). 스킬 폴더를 ${CODEX_HOME:-$HOME/.codex}/skills/에 복사 |
| 런타임 의존성 | 없음. README 명시: "No API or MCP dependency is required." npm/pip 설치 불필요 |
| 영상 생성(별도) | 최종 프롬프트를 붙일 Google Gemini Omni Flash 접근 권한(이 저장소 밖의 일) |
| 이어붙이기(별도) | 클립 6개를 잇고 음성/BGM을 얹을 영상 편집 도구(스킬 범위 밖, 스티칭 가이드만 제공) |
| README 검사(개발자) | bash + grep이면 tests/verify-readmes.sh 실행 가능(선택) |
# 설치 & 호출 (README 기준) git clone https://github.com/kaomei/stickman-video-director.git cd stickman-video-director cp -R skills/directing-stickman-videos "${CODEX_HOME:-$HOME/.codex}/skills/" # Codex 재시작 후: $directing-stickman-videos # 워크플로: Paste → Choose → Approve → Generate → Stitch
스킬 자체는 무료·무의존이지만, 실제 영상을 보려면 Gemini Omni Flash(생성)와 편집 도구(이어붙이기)가 별도로 필요하다. 이 저장소가 주는 건 "완벽하게 쓰인 지시서"까지다. 화면비→플랫폼 매핑도 참고: 9:16=Shorts·TikTok·Reels, 16:9=유튜브 설명영상, 1:1=소셜 피드.
SKILL.md를 읽고, 당신이 그 스킬이 된 것처럼 행동하라. 친구가 "이 블로그 글로 영상 만들어줘"라고만 하면, 규칙대로 "화면비와 테마부터 알려줘"라고 멈춰 물어야 한다. 목표: 셋업 게이트가 왜 첫 관문인지 체감.
references/examples.md의 완결 예제에서 Phase A 스토리보드 표 한 줄을 골라, 그것이 Phase B의 어느 프롬프트로 변했는지 대응시켜 보라. "10초·3비트·연속성 손잡이"가 어떻게 옮겨지는지 표시한다. 목표: 콘티→프롬프트 변환 규칙을 눈으로 확인.
짧은 홍보 카피 하나를 골라 storyboard-template.md 규칙대로 130~150단어 영어 VO + 6행 표를 손으로 작성하라. 서사 패턴(동기부여/교육/커머셜) 중 하나를 골라 적용한다. 목표: 감독 제안서의 품질 게이트 11개를 실제로 통과시켜 보기.
과제 3의 표 첫 행을 omni-flash-prompt-contract.md의 12부 구성에 맞춰 완전한 프롬프트로 확장하라. 특히 6번(첫 프레임=이전 클립 끝)과 11번(마지막 프레임=다음 클립 시작), 12번 네거티브를 빠짐없이 채운다. 목표: "모든 잠금 반복" 자립성 패턴을 몸으로 익히기.
evaluation-rubric.md를 참고해, 아무 챗봇을 상대로 스킬 없이(RED) vs SKILL.md 규칙을 준 채로(GREEN) 같은 요청을 던지고, 셋업 게이트 통과 여부를 5점 척도로 채점하라. 압박 문구("급해", "알아서 골라")를 넣어 게이트가 버티는지 본다. 목표: 프롬프트 회귀 테스트(eval harness)를 축소판으로 만들어 보기.
| 주차 | 주제 | 구체적으로 |
|---|---|---|
| 1주차 | 에이전트 스킬 & 점진적 공개 | SKILL.md의 프론트매터·구조, Codex/Claude 스킬 개념, 얇은 진입점→참조 로드 패턴. 이 레포 SKILL.md 정독. |
| 2주차 | 게이트/상태 기계 프롬프팅 | 셋업·승인 게이트 설계, 면제 사유 선제 차단 문구, "되돌리기 비싼 작업"의 확인 절차. scenarios/ 5종 읽기. |
| 3주차 | 스토리보드·서사 설계 | storyboard-template.md 정독. 동기부여/교육/커머셜 3서사 패턴, 130~150단어 VO, 7열×6행 표, 품질 게이트 11개. |
| 4주차 | 텍스트-투-비디오 크래프트 | omni-flash-prompt-contract.md의 12부 구성·네거티브. "색은 말로", 자막 회피, 720p·24FPS 스펙 이유. |
| 5주차 | 연속성·자립성 | 프레임 체이닝(6↔11번), 자립형 프롬프트의 잠금 반복, 음성/음악 연속성 노트. examples.md로 실제 대응. |
| 6주차 | 프롬프트 TDD·평가 | evaluation-rubric.md 22항목, reports/baseline.md↔forward.md. eval harness·회귀 테스트 개념 일반화. |
| 7주차 | 실제 생성 파이프라인 | Gemini Omni Flash로 클립 렌더, 스티칭 가이드대로 이어붙이기, 후반작업 오버레이(생성 밖 텍스트) 처리. |
| 8주차 | 문서 계약·현지화 | verify-readmes.sh 분석 — 공유 섹션 마커·토큰 동기화, 금칙어 검사. 다국어 문서를 CI 불변식으로 거는 법. |
SKILL.md가 진입점이고 참조 문서로 세부를 넘긴다. 코드가 아니라 규칙이 본체.9:16→16:9로 바꾸면 문자열만 교체하는 게 아니라 구도·카메라·전환·여백을 다시 짜야 함. 전역 변경은 이전 승인을 무효화.skills/directing-stickman-videos/SKILL.md(뼈대) · references/storyboard-template.md·omni-flash-prompt-contract.md(두 계약) · references/examples.md(완결 예제) · tests/reports/baseline.md·forward.md(RED/GREEN 증거) · tests/evaluation-rubric.md(채점표)