hup-dev/promo-animation-skill

제품 애니메이션

현재 코드베이스 제품에 대한 완성된 MP4 애니메이션을 제작합니다. 이 스킬은 결정론적 애니메이션 엔진 + 방법론으로, 고정된 형식이 아닙니다. 사용자가 요청한 내용에 맞는 패턴(채팅 데모, 브랜드 인트로, 통계 공개, 워크플로우 둘러보기, 전후 비교 등)을 직접 결정합니다.

모든 패턴에서 일관되게 유지되는 사항:

• 실제 브랜드 자산을 저장소에서 가져옵니다(로고 SVG, 디자인 토큰, 폰트).
• Linear/Vercel/Stripe 수준의 시각적 완성도(부드러운 그림자, 실제 타이포그래피, 단일 히어로 순간).
• 결정론적 __setTime(t) 타임라인을 사용하여 Playwright가 매 렌더링마다 완벽한 프레임을 캡처합니다.
• 애니메이션이 주장하는 모든 내용에 구체적이고 이름이 명시된 콘텐츠를 사용합니다. "AI가 비용을 절약합니다"와 같은 일반적인 카피는 사용하지 않습니다.

이 모든 것을 가능하게 하는 전체 참조는 methodology.md에 있습니다. 다른 작업을 하기 전에 먼저 읽으십시오. 시각적 스타일, 타이밍, 카메라 수학, ffmpeg 플래그, 그리고 첫 시도에서 흔히 빠지는 10가지 함정에 대한 구체적인 세부 정보가 포함되어 있습니다.

출력 대상

기본값: 1920×1080 @ 30fps, H.264 (선택적 음악 + 1초 테일 페이드 포함). 길이는 패턴에 따라 다릅니다:

• 브랜드 인트로 / 로고 리빌: 5–8초
• 통계 리빌: 6–10초
• 제품 프로모션(채팅 스타일 등): 15–22초
• 워크플로우 둘러보기: 20–40초

사용자가 지정하지 않은 경우 길이와 화면 비율을 사용자에게 확인하십시오. 소셜/세로 형식을 요청하지 않는 한 기본값은 16:9 1920×1080입니다.

두 가지 컷(예: 정적 카메라 + 시네마틱 카메라)이 모두 적합한 경우, 둘 다 제공합니다.

사전 점검

작업을 시작하기 전에 환경이 이를 수행할 수 있는지 확인하십시오:

which ffmpeg && ffmpeg -version | head -1
which node && node --version
ls ~/Library/Caches/ms-playwright/ 2>/dev/null | head -3   # macOS playwright 캐시

Playwright chromium이 캐시되지 않은 경우 npx playwright install chromium을 실행하십시오. ffmpeg는 필수입니다.

작업 공간을 생성하십시오:

mkdir -p product-animation/frames
cd product-animation

4단계 파이프라인

4단계를 시작하기 전에 1~3단계를 병렬로 서브에이전트(독립적인 작업)로 실행하십시오.

1단계 — 브랜드 및 자산 검색 (서브에이전트)

agents/01-brand-extractor.md의 프롬프트로 브랜드 추출기를 실행하십시오. 다음을 전달합니다:

• 저장소 루트 경로
• 제품이 무엇을 하는지에 대한 몇 가지 힌트

다음의 JSON을 반환합니다: 실제 로고 SVG 경로, 정확한 16진수 토큰, 폰트 스택, 히어로 UI 규칙(테두리 반경, 패딩, 기본 버튼 스타일), 제품명 + 태그라인.

실제 워드마크 SVG를 작업 공간에 복사하십시오 (예: <product>-wordmark.svg). 브랜드 자산은 인라인으로 사용하며, 래스터 이미지는 사용하지 않습니다.

2단계 — 콘셉트 + 스크립트 (서브에이전트)

agents/02-script-writer.md의 프롬프트로 스크립트 작성을 실행하십시오. 1단계의 브랜드 요약, 제품이 무엇을 하는지, 사용자가 요청한 애니메이션 유형(프로모션, 브랜드 인트로, 통계 리빌 등)을 전달합니다.

다음을 반환합니다:

• 이 제품에 대해 선택된 애니메이션 패턴 (예: "chat-demo", "stat-reveal", "brand-intro")
• 씬 타이밍이 포함된 스토리보드: 콜드 오픈 → 메인 콘텐츠 → 아웃트로
• 각 씬에 표시할 정확한 텍스트/숫자/시각 자료

패턴이 chat-demo인 경우, templates/chat-demo.html의 템플릿은 완전한 작동 시작점입니다. CASES.BIGGEST 데이터 구조에 스크립트의 내용을 채우십시오. 다른 패턴의 경우, methodology.md § 2에 설명된 애니메이션 엔진을 사용하여 HTML을 처음부터 작성하십시오. 동일한 __setTime(t) 드라이버, 동일한 이징 툴킷, 동일한 Playwright 캡처를 사용합니다.

3단계 — 콘텐츠 리서치 (서브에이전트)

agents/03-case-researcher.md의 프롬프트로 케이스 리서처를 실행하십시오. 제품 도메인과 애니메이션 패턴을 전달합니다.

반환되는 내용은 패턴에 따라 다릅니다:

• 채팅 데모 / 프로모션: 실질적인 숫자가 포함된 하나의 정식적이고 명명된 드라마틱한 전후 사례(해당 도메인의 "Converse Chuck Taylor 순간") + 3~4개의 보조 사례.
• 통계 리빌: 제품이 신뢰성 있게 소유할 수 있는 하나의 큰 공개 지표(출처 포함).
• 브랜드 인트로 / 로고 리빌: 회사의 실제 헤드라인, 실제 고객 수, 실제 론칭 스토리 — 화면에 표시할 수 있는 검증 가능한 모든 것.
• 워크플로우 둘러보기: 가장 일반적인 실제 사용자 여정, 제품 자체의 명명된 단계.

애니메이션이 주장하는 모든 내용에 대해 구체적이고 명명되며 검증 가능해야 합니다.

4단계 — 빌드 및 렌더링

출력을 결합하여 선택한 HTML 템플릿(또는 직접 작성한 템플릿)에 넣고 Playwright로 프레임을 렌더링한 후 ffmpeg로 인코딩합니다.

빌드 단계

빌드는 패턴마다 약간 다릅니다. 공통된 형태는 다음과 같습니다:

1. 애니메이션 HTML을 복사하거나 작성합니다.

   • 스크립트 작성자가 chat-demo를 선택한 경우, templates/chat-demo.html을 작업 공간에 복사하고 CASES.BIGGEST 데이터 객체를 2단계 스크립트 내용 + 3단계 리서치로 편집합니다. 또한 브랜드 :root { --tokens }, 헤더 텍스트("Atlas Trade", "Intelligence", 배지), URL 표시줄, 워드마크 <img src>, 로고 아웃트로 태그라인 및 CTA를 교체합니다.
   • 다른 패턴(브랜드 인트로, 통계 리빌, 워크플로우, 전후 비교)의 경우, 애니메이션 엔진을 사용하여 HTML을 처음부터 작성합니다. methodology.md § 2는 결정론적 타임라인 패턴을 보여줍니다. reference/design-rules.md의 디자인 규칙, reference/camera-modes.md의 카메라 수학, 그리고 동일한 Playwright 렌더링 계약을 재사용합니다.

2. 렌더 스크립트를 복사합니다. chat-demo의 경우 templates/render-chat-demo.js(525프레임, ~17.5초) 또는 render-chat-demo-zoom.js(585프레임, ~19.5초, 시네마틱 카메라)를 사용합니다. 사용자 정의 패턴의 경우 렌더 스크립트 중 하나를 복사하고 DURATION 상수를 업데이트합니다. 나머지는 그대로 작동합니다.

3. 먼저 브라우저에서 확인합니다. HTML을 직접 엽니다. 애니메이션이 자동으로 루프 재생됩니다. 모든 씬을 눈으로 확인합니다. 브라우저에서 5분을 사용하면 반복당 3분의 렌더링 시간을 절약할 수 있습니다.

4. 스모크 렌더 — 전체 렌더링을 시작하기 전에 씬 경계에서 6~8개의 키프레임을 렌더링합니다. 패턴은 scripts/smoke.js를 참조하십시오. 30초 안에 레이아웃 겹침, 폰트 대체, 화면 밖 요소를 잡아냅니다.

렌더링 단계

작업 공간에 Playwright를 설치합니다:

npm install [email protected] --no-save --no-audit --no-fund --silent

프레임을 렌더링합니다:

node render-<pattern>.js          # frames/f_*.png 파일 작성 (~지속 시간(초) × FPS의 3~5프레임)

ffmpeg로 인코딩합니다. -t를 애니메이션 지속 시간에 맞게 조정하고 afade=t=out:st=X를 종료 1초 전에 페이드가 되도록 조정합니다:

ffmpeg -y -framerate 30 -i frames/f_%05d.png \
  -i /path/to/music.mp3 \
  -c:v libx264 -pix_fmt yuv420p -crf 18 -preset medium -movflags +faststart \
  -c:a aac -b:a 192k -af "afade=t=out:st=<DURATION-1>:d=1.0" \
  -t <DURATION> -shortest animation.mp4

yuv420p는 Slack/LinkedIn/Twitter 재생에 필수입니다. +faststart는 스트리밍을 가능하게 합니다. crf 18은 거의 시각적 무손실에 가깝습니다.

오디오가 제공되지 않은 경우 -i music.mp3, -c:a aac -b:a 192k, -af 플래그를 제거하십시오. scripts/encode.sh는 이 기능을 적절한 기본값으로 래핑합니다.

품질 게이트 — 완료로 선언하기 전에 읽으십시오

범용 (모든 패턴):

• 실제 브랜드 워드마크가 인라인으로 포함됨 (SVG <img>, Inter Tight 볼드체를 로고처럼 스타일링한 것이 아님).
• 모든 색상은 제품의 토큰에서 가져옴 — 절대 임의의 16진수를 사용하지 않음.
• 애니메이션이 코드베이스에서 참조됨 — 해당 UI, 폰트, 카피 관용구를 인식할 수 있음.
• 단일 히어로 순간. 하나의 숫자, 하나의 리빌, 하나의 CTA — 경쟁하는 12개의 초점이 아님.
• 숫자가 변하는 모든 곳에 tabular-nums 사용 (가로로 흔들리지 않도록).
• 애니메이션이 안정적으로 종료됨 — 어떤 요소도 다른 요소가 사라지는 정확히 같은 순간에 나타나지 않음; 진입/종료 창을 준수.
• 로고가 마지막에 충분히 오래 유지됨 (브랜드 아웃트로의 경우 ≥ 3초).
• MP4가 QuickTime에서 재생되며, 정확히 대상 해상도 × fps, 파일 크기가 합리적임 (일반적으로 1–6 MB).
• 사용자를 위해 open <name>.mp4로 MP4를 엽니다.

chat-demo의 경우 추가 확인 사항 (reference/design-rules.md 참조):

• 히어로 $ 숫자는 JetBrains Mono / weight 800 / 6자리 이상.
• 툴 체인에 약 8개의 칩이 있고, 간격은 약 3초 — 그보다 짧으면 가짜로 읽힘.
• 사용자 말풍선이 막대가 사라진 후에 나타나며, 동시에 나타나지 않음.
• 생각 말풍선이 결과가 페이드 인되기 전에 위로 미끄러져 나가야 함 — 둘 다 불투명한 상태가 되어서는 안 됨.
• 캐럿은 타이핑 중에만 나타나고, 자리 표시자에는 절대 나타나지 않음.

완료로 선언하기 전에 정리합니다:

rm -rf frames frames-zoom node_modules package.json package-lock.json smoke_*.png

최종 작업 공간에는 다음이 포함되어야 함: HTML, 렌더 스크립트, 워드마크 SVG, 완성된 MP4.

파일 맵

~/.claude/skills/promo-animation/
├── SKILL.md                  ← 현재 위치
├── methodology.md            ← 심층 참조, 가장 먼저 읽을 것 — 범용 애니메이션 엔진
├── agents/
│   ├── 01-brand-extractor.md   ← 1단계 서브에이전트 프롬프트
│   ├── 02-script-writer.md     ← 2단계 서브에이전트 프롬프트
│   └── 03-case-researcher.md   ← 3단계 서브에이전트 프롬프트
├── templates/
│   ├── chat-demo.html              ← 정식 chat-demo 패턴 (작동 예제)
│   ├── render-chat-demo.js         ← 정적 모드 Playwright 렌더러
│   ├── render-chat-demo-zoom.js    ← 줌 모드 렌더러
│   └── atlas-wordmark.svg          ← 자리 표시자 SVG
├── scripts/
│   ├── smoke.js                ← 키프레임 스모크 테스트
│   └── encode.sh               ← ffmpeg 래퍼
└── reference/
    ├── design-rules.md         ← 시각적 규칙 요약
    ├── camera-modes.md         ← 정적 vs 줌 결정
    └── timing-blueprint.md     ← 씬 타이밍

의문이 들면 templates/chat-demo.html을 읽으십시오. 이 파일은 지금 바로 렌더링할 수 있는 완전한 작동 예제(가상의 "Atlas Trade" / Converse Chuck Taylor 재분류 시나리오)입니다. chat-demo 패턴과 결정론적 애니메이션 엔진 모두에 대한 표준 참조입니다. methodology.md의 모든 시각적 규칙, 타이밍 결정 및 함정이 이 파일에 인코딩되어 있습니다.

다른 애니메이션 패턴의 경우 HTML을 처음부터 작성합니다. 그러나 애니메이션 엔진(methodology.md § 2), 렌더링 계약(§ 5), 디자인 규칙(reference/design-rules.md)은 모두 변경 없이 그대로 적용됩니다.