media-use: 오디오/이미지를 가져오기 전에
/media-use를 호출하여 HeyGen 카탈로그에서 BGM/SFX/이미지를 해결하세요. 기존 자산을 등록하려면--adopt를 먼저 실행하세요./media-use스킬을 참조하세요.
PR to HyperFrames
이 스킬을 사용하여 GitHub 풀 리퀘스트를 분석하고, 코드 변경의 설명을 이해하며, 코드 변경 설명 영상을 계획하고 HyperFrames에서 프레임별로 제작하세요. 입력은 코드 변경(gh로 읽음)이며, 웹사이트가 아닙니다 — 캡처 단계가 없고 실제 자산은 기여자의 아바타 외에는 없습니다.
Step 0 이전에 경로를 확인하세요. 당신은 오케스트레이터입니다. 각 단계를 실행하고, 게이트를 확인한 후에만 계속 진행하세요. 이 스킬은 GitHub 풀 리퀘스트(코드 변경)를 위한 것입니다. 다른 의도는 다른 곳으로 라우팅하세요: 제품 출시/프로모션 →
/product-launch-video; 일반 웹사이트 둘러보기 →/website-to-video; PR 없는 주제 설명 →/faceless-explainer; 기존 영상에 자막 추가 →/embedded-captions; 짧은 설명 없는 모션 그래픽 →/motion-graphics; 전체 리포지토리 또는 다중 PR 릴리스 워크스루 →/general-video. 범위 외: 라이브/렌더링 시점 데이터 — PR 사실은 작성 시점에 한 번 읽혀서 고정됩니다. 사용자가 "영상 만들어줘"라고만 말하거나 경로가 불확실하면 먼저/hyperframes를 읽으세요.
당신은 오케스트레이터입니다. videos/<project>/ 디렉토리에서 작업하세요. 순서대로 단계를 실행하고 각 게이트를 통과한 후에만 계속 진행하세요. 사용자 게이트 단계는 Step 0, Step 3, Step 6입니다. Step 5를 제외한 모든 단계를 직접 실행하세요. Step 5에서는 프레임당 하나의 하위 에이전트를 파견합니다. 디자인 또는 모션 규칙을 여기에 두지 마세요. 그것들은 프레임 작업자 하위 에이전트인 hyperframes-creative와 hyperframes-animation에 있습니다.
워크플로우: Step 0 설정 → hyperframes.json; Step 1 수집 → capture/extracted/ + assets/<login>.png; Step 2 디자인 시스템 → frame.md; Step 3 스토리보드/스크립트 → STORYBOARD.md 및 SCRIPT.md; Step 3.1 오디오 → audio_meta.json; Step 4 시각 디자인 → 보강된 STORYBOARD.md; Step 5 프레임 → compositions/frames/NN-*.html 및 index.html; Step 6 최종 렌더링 → renders/video.mp4.
Step 0: 설정 및 브리핑
목표: PR 참조와 핵심 영상 브리핑을 확정하고, 필요한 경우 HyperFrames 프로젝트를 생성합니다.
PR 참조(전체 URL, <owner>/<repo>#<N> 참조, 또는 체크아웃된 리포지토리에서 "this PR")를 가져오고, 한 메시지에서 브리핑을 확인하세요 — 각 항목에 대한 권장 기본값을 제시하고 /hyperframes가 이미 설정한 내용을 미리 채우세요: 관점(changelog / feature-reveal / fix-explainer / refactor-walkthrough — 기본값: PR에서 유추), 대상(기본값: 개발자), 길이(기본값: PR의 변경 크기에 맞게 조정 — 아래 참조), 비율(기본값 16:9), 언어. 스타일은 항상 claude입니다. 사용자가 응답한 후에만 진행하세요. "go"는 기본값을 수락합니다.
PR의 변경 크기에서 길이를 추천하세요. 고정된 추측을 하지 마세요. 브리핑을 확인하기 전에 PR을 한 번 살펴보세요 — 관점을 뒷받침하는 읽기 전용 호출입니다(Step 1에서 여전히 전체 결정론적 가져오기를 수행합니다):
gh pr view <PR_REF> --json title,additions,deletions,changedFiles
additions + deletions( changedFiles에 의해 약간 올림)에서 등급을 선택하고 기본값으로 제시하세요(사용자가 재정의할 수 있음, 하드 캡 ~3분):
| PR 변경 크기 | 권장 길이 |
|---|---|
| 사소함 (약 50줄 미만 변경) | ~20–40초 |
| 집중됨 (약 50–200줄) | ~40–70초 |
| 상당함 (약 200–600줄) | ~70–110초 |
| 큼 (약 600줄 초과, 또는 25+ 파일) | ~110–180초 |
제안할 때 하나의 구문으로 근거를 명시하세요(예: "~40초 — 작은 변경, +44/−13, 12개 파일"). 거대한 PR이 항상 긴 영상을 의미하지는 않습니다. 스토리가 하나의 주요 변경 사항이라면 간결하게 유지하고 그렇게 말하세요.
hyperframes.json이 없을 때만 초기화하세요. <project> 이름은 PR에서 케밥-케이스로 지정하세요(예: acme-sdk-pr-1842). 워크스페이스 이름이나 타임스탬프를 사용하지 마세요.
npx hyperframes init "videos/<project>" --non-interactive --example=blank — init는 설치된 스킬을 GitHub의 최신 버전과 비교하고 오래된 것이 있으면 전역 집합을 업데이트합니다.
브리핑 전에 로그인 상태를 표시하세요 — npx hyperframes auth status를 실행하고 출력을 그대로 전달하세요(바꿔 말하거나 다시 작성하지 마세요). 음성/BGM이 HeyGen 또는 로컬 엔진을 사용하는지, 그리고 로그인되지 않은 경우 로그인 방법을 보고합니다. 로그인되지 않은 경우 중지하고 사용자가 선택하기를 기다리세요 — 로그인하거나, "go"/"offline"이라고 말하여 로컬 엔진으로 계속 진행하세요 — 브리핑이나 다른 것을 묻기 전에. 그것을 지나가는 메모가 아닌 실제 결정 지점으로 취급하세요. 선택 사항을 브리핑 질문에 포함시키지 말고, 리포지토리별 .env에 키를 작성하지 마세요. (자율 모드에서는 상태를 기록하고 오프라인으로 계속 진행하세요.) 표준 지침은 ../hyperframes-media → Preflight를 참조하세요.
게이트: hyperframes.json이 존재함; PR 참조가 캡처됨; 관점, 길이, 종횡비 및 언어가 고정됨; 로그인 상태가 표시됨(로그인됨, 또는 오프라인으로 계속 진행).
Step 1: PR 수집 (캡처 없음)
목표: PR의 사실을 가져와 정보 소스로 프로젝트에 통합합니다. 웹사이트 캡처는 없습니다. fetch-pr.mjs는 gh를 결정론적으로 실행합니다 — 페이지가 매겨진 gh api를 통해 파일 목록을 완성하여 큰 PR이 약 100개 파일에서 잘리지 않도록 하고, capture/pr.json + capture/diff.patch만 작성합니다(임시 디렉토리 없음). 그런 다음 ingest.mjs가 이를 합성 캡처 패키지로 오프라인에서 통합합니다.
PR="<url | owner/repo#N | N>"
# PR을 결정론적으로 가져오기: gh 실행, 페이지가 매겨진
# gh api를 통해 파일 목록 완성(큰 PR이 약 100개 파일에서 잘리지 않도록),
# capture/pr.json + capture/diff.patch만 작성 — 임시 디렉토리 없음.
# gh auth / not-found / private 오류는 여기서 exit 1.
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# 오프라인 변환 → capture/extracted/{tokens.json (colors:[] → 클로드 팔레트),
# visible-text.txt (브리핑), people.json (기여자, 봇 필터링됨, avatarFile=assets/<login>.png)}.
(cd "videos/<project>" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# 사람 앞부분의 유일한 네트워크 단계 — 각 기여자의 GitHub 아바타를
# assets/<login>.png로 다운로드하여 선택적 크레딧 클로즈에 사용.
# 최선 노력; 항상 exit 0.
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
fetch-pr.mjs가 exit 1이면(gh auth / not found / private), stderr를 보고하고 중지하세요 — PR 내용을 조작하지 마십시오. ingest.mjs가 exit 1이면, stderr를 읽고(일반적으로 잘못된 형식의 pr.json), 수정하고, 다시 실행하세요(결정론적). fetch-people-avatars.mjs는 항상 exit 0입니다. 누락된 아바타는 작성자에 대한 크레딧 클로즈가 없음을 의미할 뿐입니다.
게이트: capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt 및 capture/extracted/people.json이 존재함; 한 문장으로 PR의 변경 사항을 설명할 수 있음. assets/<login>.png는 최선 노력 — 그것의 부재는 실패가 아닙니다.
Step 2: 디자인 시스템
목표: 'claude' 프레임 프리셋을 채택합니다. 스크립트가 이를 이 영상의 frame.md + 캡션 스킨으로 변환합니다.
스타일은 고정됨 — claude(따뜻한 편집 스타일; diff에 맞춰진 네이비 코드 표면). 실행:
node <SKILL_DIR>/scripts/build-frame.mjs --preset claude --hyperframes .
스크립트는 'claude' 프리셋의 FRAME.md를 복사하여 frame.md로 만들고, capture/extracted/tokens.json(PR에는 없음 → colors:[]/fonts:[]는 claude의 자체 팔레트, 완전한 디자인 유지)의 브랜드 토큰 위에 리믹스하며, 프리셋의 캡션 스킨을 .hyperframes/caption-skin.html로 복사하고, 자체 검증(잘못된 매핑 시 exit 1)합니다. exit 0이 되는 즉시 진행하세요 — 수동 편집 없음.
게이트: build-frame.mjs가 exit 0 — frame.md가 claude 프리셋에서 존재하고, .hyperframes/caption-skin.html이 캡션 스킨 소스로 존재함.
Step 3: 스토리보드 및 스크립트
목표: PR을 승인된 프레임별 설명 계획으로 전환합니다.
references/story-design.md, ../hyperframes-core/references/storyboard-format.md 및 ../hyperframes-core/references/script-format.md를 읽으세요. 이를 사용하여 STORYBOARD.md를 작성하고, 내레이션이 필요할 때 SCRIPT.md를 작성하세요.
story-design.md를 PR 아키타입(changelog / feature-reveal / fix-explainer / refactor-walkthrough), PR 네이티브 프레임 유형, 훅, 설득, 비트, 프레임당 단어 예산 및 선택적 크레딧 클로즈에 사용하세요. 순서는 내러티브 디자인에서 나오며, diff의 파일 순서가 아닙니다 — 변경 사항을 설명하고, diff를 그대로 읽지 마세요. capture/diff.patch에서 2-4개의 실제 diff 헝크를 기능으로 사용하고, 각각 작고 읽기 쉬운 조각을 만드세요. 각 프레임의 scene에서 원하는 code-* 블록의 이름을 지정하세요. 선택적 credits 클로즈(2-6개의 assets/<login>.png 아바타)를 제외하고 프레임에는 asset_candidates가 없습니다. 스토리보드 및 스크립트 참조의 정확한 필수 필드를 사용하세요.
초안 작성 후 프레임별 요약을 표시하세요. 같은 메시지에서 사용자에게 (a) 승인 또는 변경 요청을 하고, (b) 스토리보드 스캐폴드의 실시간 미리보기를 원하는지(npx hyperframes preview) 물으세요 — 예인 경우에만 엽니다. 승인될 때까지 반복합니다. 미리보기 선택 사항을 Step 6까지 유지하세요.
게이트: STORYBOARD.md가 존재함, 모든 프레임에 필수 내러티브 필드가 있음, 내레이션이 필요할 때 SCRIPT.md가 존재함, 사용자가 계획을 승인함.
Step 3.1: 오디오
목표: 승인된 스크립트에서 내레이션, 단어 타이밍, 음악 및 오디오 메타데이터를 생성합니다.
Step 3 승인 후 오디오를 시작합니다. 백그라운드에서 실행한 다음 Step 4로 계속 진행합니다.
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
오디오 스크립트는 내레이션, 단어 타이밍, HeyGen의 음악 라이브러리에서 BGM 조회 및 타이밍 메타데이터를 처리합니다. BGM 분위기는 스토리보드의 music: 필드에서 가져옵니다. 이는 생성을 위한 것이 아니라 검색을 위해 HeyGen Audio API를 사용하며, TTS와 동일한 ~/.heygen 자격 증명을 사용합니다. 공급자 세부 정보는 ../hyperframes-media/references/tts.md를 읽으세요.
내레이션이 없고 SCRIPT.md가 없으면 음성 생성을 건너뜁니다. 스토리보드에 음악 분위기가 있으면 BGM이 계속 실행될 수 있습니다.
게이트: 오디오 작업이 시작되었거나 프로젝트가 무음으로 표시됨.
Step 4: 프레임 시각 디자인
목표: 각 스토리보드 프레임에 시각적 방향, 레이아웃 의도 및 모션 선택 사항을 추가합니다.
STORYBOARD.md를 그 자리에서 편집하세요. 다른 스토리보드를 만들지 마십시오. 색상, 서체, 레이아웃 느낌 및 스타일에 대한 진실의 원천으로 frame.md를 사용하세요.
references/visual-design.md, references/composition.md, references/motion-language.md, references/code-vocabulary.md 및 ../hyperframes-animation/을 읽으세요. visual-design.md를 필수 프레임 필드 및 필수 ## Video direction 블록, 그리고 코드 비트가 code-* 블록을 focal로 지정하는 방법에 사용하세요. code-vocabulary.md를 비트당 올바른 블록을 선택하는 데 사용하세요(diff = code-diff, 리팩터링 = code-morph, 새 코드 = code-typing, ...). composition.md를 레이아웃/계층/초점 포인트에 사용하고, motion-language.md + ../hyperframes-animation/을 유효한 효과 및 블루프린트 ID에 사용하세요. 효과 이름이나 블록/블루프린트 ID를 임의로 만들지 마십시오.
모든 프레임에 대해 effects 및 focal 및/또는 roles를 포함한 필수 시각 및 모션 필드를 추가하세요. 코드 비트의 경우 code-* 블록을 focal로 지정하고 effects가 주변 'claude Code Surface'를 안무하도록 하세요(블록이 소유하는 코드 애니메이션은 제외). 하나의 비디오 전체 ## Video direction 블록을 추가하세요.
스토리, 스크립트, transition_in, asset_candidates 또는 PR 소스를 변경하지 마십시오. 이 단계에서는 HTML을 작성하지 마십시오. 자산 스테이징 단계가 없습니다 — 유일한 실제 자산은 이미 assets/에 있는 크레딧 아바타입니다.
게이트: 모든 프레임에 effects 및 focal 및/또는 roles가 있음; 코드 프레임이 code-* 블록을 지정함; ## Video direction이 존재함.
Step 5: 프레임 빌드
목표: 모든 스토리보드 프레임을 HTML 구성 요소로 빌드하고 재생 가능한 비디오를 조립합니다.
오디오가 시작된 경우 Step 3.1 오디오가 완료될 때까지 기다리세요. 그런 다음 지속 시간을 동기화하고 SFX를 가져옵니다. 무음이면 둘 다 건너뜁니다.
node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
지속 시간 동기화는 기계적입니다: 실제 음성 지속 시간이 우선합니다. 무음 프레임은 추정치를 유지합니다. 동기화된 지속 시간을 수동으로 편집하지 마십시오.
파견 전에 STORYBOARD.md에 명명된 모든 레지스트리 블록을 한 번 사전 설치하여 병렬 작업자가 레지스트리에서 경쟁하지 않도록 하세요:
for b in <스토리보드에 명명된 각 레지스트리 블록>; do npx hyperframes add "$b"; done
파견 전에 sub-agents/frame-worker.md 및 ../hyperframes-core/references/subagent-dispatch.md를 읽으세요. 가능하면 프레임당 하나의 하위 에이전트를 병렬로 파견하고, 그렇지 않으면 작업자를 웨이브로 실행하세요. 각 작업자는 정확히 하나의 프레임을 받습니다. 각 작업자의 컨텍스트는 PROJECT_DIR, frame_id, 캔버스 크기, 캡션이 활성화된 경우 캡션 상태 및 킵아웃 밴드, ANIM_DIR(../hyperframes-animation/의 절대 경로) 및 references/code-vocabulary.md의 절대 경로를 포함해야 합니다. 각 작업자는 frame.md, ## Frame N 블록, 인용된 각 효과/블루프린트 ID에 대한 레시피 본문, 그리고 코드 비트의 경우 명명된 블록의 입력에 대한 code-vocabulary.md를 읽습니다. 각 작업자는 compositions/frames/NN-*.html만 작성합니다. 작업자는 STORYBOARD.md를 편집하지 않습니다.
각 작업자가 반환될 때마다 해당 프레임을 STORYBOARD.md에서 animated로 표시하세요.
오디오 타이밍이 존재한 후, 백그라운드에서 캡션을 빌드하고 인덱스를 조립합니다:
node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
captions.mjs는 프로젝트의 .hyperframes/caption-skin.html(Step 2에서 복사된 'claude' 스킨)을 사용하고, frame.md의 브랜드 토큰을 주입합니다. captions: skipped (<reason>)는 ...
[원본이 잘렸으므로 계속하지 않음]