heygen-com/hyperframes

플러그인 설치: 설정 또는 업데이트 명령어를 실행하기 전에, 이 스킬이 HyperFrames 플러그인 내부에 있을 때는 플러그인 실행 규칙을 따르세요. 독립 실행형 설치의 경우 아래 업데이트 지침을 유지하세요.

먼저, 이 스킬을 최신 상태로 유지하세요 — 사용자에게 확인 후 실행: npx hyperframes skills update pr-to-video. 모든 것이 최신 상태이면 빠르게 아무 일도 일어나지 않습니다. 그렇지 않으면 이 스킬과 의존하는 핵심 도메인 스킬을 사용하기 전에 업데이트합니다.

media-use: 오디오/이미지/로고를 가져오기 전에 /media-use를 호출하여 HeyGen 카탈로그의 BGM/SFX/이미지와 공식 출처의 브랜드 로고를 확인하세요. 기존 자산을 등록하려면 --adopt를 먼저 실행하세요. /media-use 스킬을 참조하세요.

PR에서 HyperFrames로

이 스킬을 사용하여 GitHub 풀 리퀘스트를 분석하고, 변경 사항을 이해하고, 코드 변경 설명을 계획한 다음, HyperFrames에서 프레임별로 제작합니다. 입력은 gh를 통해 읽은 코드 변경이며, 웹사이트가 아닙니다 — 기여자의 아바타 외에는 캡처 단계도 실제 자산도 없습니다.

진입점은 /hyperframes입니다. 당신은 오케스트레이터입니다. 각 단계를 실행하고, 게이트를 확인한 후에만 계속 진행하세요. 이 스킬은 GitHub 풀 리퀘스트(코드 변경)용입니다. 다른 의도, 단순한 "비디오 만들기" 요청, 또는 불확실한 경우 → 먼저 /hyperframes를 읽으세요 — 의도 레이어가 모든 경로 결정을 소유하며, BRIEF.md 없이 여기에 도착한 새로운 생성 요청은 어쨌든 이를 통해 진행됩니다(설정의 시작 규칙).

당신은 오케스트레이터입니다. 해결된 외부 PROJECT_DIR 내에서 작업하며, 기본적으로 호출자 저장소에서는 작업하지 마세요. 단계를 순서대로 실행하고 각 게이트를 통과한 후에 계속 진행하세요. 사용자 게이트 단계는 0단계, 3단계, 6단계입니다. 0단계 전에 ../hyperframes/references/brief-contract.md를 읽으세요 — 이는 게이트 유형과 BRIEF.md의 flow/storyboard가 3/4/6단계 게이트를 제어하는 모드를 도출하는 방법을 정의합니다. 5단계(제한된 프레임 작업자 풀을 파견하는 단계)를 제외한 모든 단계를 직접 수행하세요. 디자인 또는 모션 규칙을 여기에 넣지 마세요. 이는 프레임 작업자 하위 에이전트, 이 스킬의 로컬 ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/, 그리고 hyperframes-creative에 있습니다.

워크플로우: 0단계 설정 → hyperframes.json; 1단계 수집 → capture/extracted/ + assets/<login>.png; 2단계 디자인 시스템 → frame.md; 3단계 스토리보드/스크립트 → STORYBOARD.md 및 SCRIPT.md; 3.1단계 오디오 → audio_meta.json; 4단계 시각 디자인 → 보강된 STORYBOARD.md; 5단계 프레임 → compositions/frames/NN-*.html 및 index.html; 6단계 최종 렌더링 → renders/video.mp4.

---

0단계: 설정

목표: 확정된 브리핑 — PR 참조(전체 URL, <owner>/<repo>#<N> 참조, 또는 체크아웃된 저장소의 "this PR") 포함 —을 가지고 시작하여 HyperFrames 프로젝트를 생성하고 브리핑을 영구적으로 만듭니다. 스타일은 항상 code-editorial(2단계에서 고정되며, 질문하지 않음)입니다.

브리핑은 여기서 질문하는 것이 아니라 의도 레이어에 의해 확정됩니다. 시작 규칙, 순서대로: (1) BRIEF.md가 존재 → 읽고 아무것도 묻지 않음 — 브리핑이 확정되었으며, flow/storyboard가 모드를 도출합니다(브리핑 계약 § 1). (2) BRIEF.md는 없지만 프로젝트가 존재(hyperframes.json / STORYBOARD.md가 디스크에 있음) → 스토리보드의 프론트매터와 기록된 기본 설정에서 재개하며, 반쯤 완성된 프로젝트에 대해 다시 질문하지 않음. (3) 둘 다 아님 — 여기에 직접 도착한 새로운 생성 요청 → /hyperframes를 읽고 의도 레이어(references/intent-interview.md)를 실행: 레시피와 기억된 기본값을 확인하고, 이 경로의 질문을 수행합니다 — 전체 ../hyperframes/references/routes/pr-to-video.md에 있는 PR 크기 → 길이 교리를 포함 — 그런 다음 잠긴 브리핑을 반환합니다. 수정 요청은 이 모든 것을 건너뜁니다 — 바로 수정을 진행하세요.

다른 작업을 수행하기 전에 프로젝트 디렉토리를 해결하세요. 사용자가 제공한 프로젝트 디렉토리는 유지하고, 그렇지 않으면 해결기가 출력하는 내구성 있는 외부 캐시 위치를 사용하세요. 호출자 저장소에 videos/를 절대 생성하지 마세요:

PR="<url | owner/repo#N>"
if [ -n "${EXPLICIT_PROJECT_DIR:-}" ]; then
  PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR" --project-dir "$EXPLICIT_PROJECT_DIR")"
else
  PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR")"
fi
echo "PR-to-video project: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs

기능 사전 점검은 가져오기, 스토리 작업, 오디오 또는 프레임 파견 전에 실행됩니다. 설치된 CLI가 이 스킬에 필요한 유효성 검사 명령어를 실행할 수 없으면, 실행 컨텍스트를 먼저 소모하지 말고 업그레이드 지침과 함께 중단하세요.

$PROJECT_DIR/hyperframes.json이 없을 때만 초기화하세요. 기본 이름은 acme-sdk-pr-1842와 같이 PR에서 가져옵니다. 워크스페이스 이름이나 타임스탬프는 절대 사용하지 마세요.

npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — init은 설치된 스킬을 GitHub의 최신 버전과 비교하여 오래된 것이 있으면 전역 세트를 업데이트합니다.

아래의 모든 상대 경로 명령어는 $PROJECT_DIR을 작업 디렉토리로 사용하여 실행됩니다. 명시적인 서브쉘이 없는 예제는 (cd "$PROJECT_DIR" && …)를 의미합니다. 호출자 저장소의 작업 트리를 절대 변경하지 마세요.

init 직후 BRIEF.md 작성 (절대 먼저 작성하지 않음 — init은 비어 있지 않은 디렉토리를 거부합니다): 의도 레이어의 잠긴 브리핑, ../hyperframes/references/brief-format.md에 따른 형식. <MEDIA_DIR>를 설치된 /media-use 스킬 디렉토리로 해결하세요. 그런 다음 각 기본 설정 기반 답변을 node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes .로 기록합니다(brief-format.md는 하위 집합을 지정함). 의도 레이어가 레시피를 채택한 경우, node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name>을 실행하세요. 이 레시피는 frame.md를 프로젝트에 복사하고(2단계 건너뜀) 3단계 초안을 작성할 스켈레톤을 반환합니다. 레시피는 답변을 채우지만 승인은 채우지 않습니다. 검토 게이트는 여전히 실행됩니다.

설정을 통과하기 전에 로그인 상태 표시 — npx hyperframes auth status를 실행하고 그 출력을 그대로 전달하세요. 음성/BGM이 HeyGen 또는 로컬 엔진을 사용할지 여부와 로그아웃된 경우 로그인 방법을 보고합니다. 한 가지 분기를 적용하세요:

• 협업: 사용자가 로그인하거나 offline / go를 명시적으로 선택할 때까지 기다립니다.
• 자율: 상태를 알리고 사용 가능한 로컬 엔진으로 계속 진행합니다.

오프라인 제공자가 없을 때 필요한 기능을 조용히 생략하지 마세요. 장애물을 표면에 드러내세요. 이 결정을 다른 질문에 포함시키거나 저장소별 .env에 키를 쓰지 마세요. 인증 소유권 및 오프라인 대체: /media-use references/setup-providers.md § 제공자.

게이트: hyperframes.json과 BRIEF.md가 존재합니다. PR 참조가 브리핑에 캡처되었습니다. 기본 설정 기반 답변이 기록되었습니다(브리핑 계약 § 2). 로그인 상태가 표시되었습니다(로그인했거나 오프라인으로 계속).

---

1단계: PR 수집(캡처 없음)

목표: PR의 사실을 가져와 정보 소스로 프로젝트에 통합합니다. 웹사이트 캡처는 없습니다. fetch-pr.mjs는 gh를 결정론적으로 실행합니다 — 페이지가 매겨진 gh api를 통해 파일 목록을 완성하여 대규모 PR이 ~100개 파일에서 잘리지 않도록 하고, capture/pr.json + capture/diff.patch만 작성합니다(스크래치 디렉토리 없음). 병합된 PR의 경우 최선의 shipped_version (+ version_source)을 pr.json에 해석하여 종료 카드가 실제 버전을 인용할 수 있도록 합니다. 그런 다음 ingest.mjs가 이를 오프라인에서 합성 캡처 패키지로 통합합니다.

PR="<url | owner/repo#N | N>"

# PR을 결정론적으로 가져옴: gh 실행, 페이지가 매겨진 gh api를 통해 파일 목록 완성
# (큰 PR이 ~100개 파일에서 잘리지 않도록), capture/pr.json +
# capture/diff.patch만 작성 — 스크래치 디렉토리 없음. gh 인증 / 찾을 수 없음 / 비공개 오류는 여기서 exit 1.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)

# 오프라인 변환 → capture/extracted/{tokens.json (colors:[] → code-editorial 팔레트),
# visible-text.txt (브리핑), people.json (기여자, 봇 필터링, name+login,
# avatarFile=assets/<login>.png)}.
(cd "$PROJECT_DIR" && 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 "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
  --people ./capture/extracted/people.json)

fetch-pr.mjs가 exit 1(gh 인증 / 찾을 수 없음 / 비공개)이면 stderr를 보고하고 중단하세요 — PR 내용을 조작하지 마세요. ingest.mjs가 exit 1이면 stderr(보통 잘못된 pr.json)를 읽고 수정한 후 재실행하세요(결정론적). fetch-people-avatars.mjs는 항상 exit 0입니다. 누락된 아바타는 작성자에게 크레딧 종료가 없다는 의미일 뿐입니다.

people.json은 gh가 이미 이름을 지정한 기여자(PR 작성자, 커밋 작성자, mergedBy)에 대해 name을 전달합니다. 나머지(리뷰어/댓글 작성자/담당자, gh pr view는 항상 login만 제공)에 대해서는 null입니다. 3단계에서 크레딧 종료를 작성하기 전에, 해당 프레임에 실제로 나타날 1-6명에 대해 null 이름을 직접 해결하세요: gh api users/<login> --jq .name (이미 gh가 있음 — 스크립팅 불필요). GitHub에도 해당 사용자에 대한 공개 이름이 없으면 화면에 로그인을 표시하고 해당 사람을 음성 대사에서 제외합니다(story-design.md의 크레딧 섹션 참조 — 내레이션은 항상 이름을 말해야 하며, 원시 핸들은 말하지 않음).

게이트: capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt, capture/extracted/people.json이 존재합니다. 한 문장으로 PR의 변경 사항을 명확히 말할 수 있습니다. assets/<login>.png는 최선의 노력 — 없어도 실패가 아닙니다.

---

2단계: 디자인 시스템

목표: code-editorial 프레임 프리셋 채택; 스크립트가 이 비디오의 frame.md + 캡션 스킨으로 변환합니다.

스타일은 고정 — code-editorial(따뜻한 에디토리얼; diff에 맞춰진 네이비 코드 표면). 실행:

node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .

스크립트는 code-editorial 프리셋의 FRAME.md를 복사하여 frame.md로 만들고, capture/extracted/tokens.json의 브랜드 토큰(PR에는 없음 → colors:[]/fonts:[]는 code-editorial 자체 팔레트를 유지, 완전한 디자인)에 리믹스하고, 프리셋의 캡션 스킨을 .hyperframes/caption-skin.html로 복사하며, 자체 검증합니다(깨진 매핑에서 exit 1). exit 0이 되는 즉시 진행하세요 — 수동 편집 없음.

게이트: build-frame.mjs가 exit 0 — frame.md가 code-editorial 프리셋에서 존재하고, .hyperframes/caption-skin.html이 캡션 스킨 소스로 존재합니다.

---

3단계: 스토리보드 및 스크립트

목표: PR을 승인된 프레임별 설명 계획으로 전환합니다.

../hyperframes-creative/references/story-spine.md(후크 언어, 가치-증거-이전, 제안으로서의 스토리보드, 소스 추적 가능한 시각 자료), references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes/references/storyboard-format.md, ../hyperframes/references/script-format.md를 읽으세요. 이를 사용하여 STORYBOARD.md를 작성하고, 내레이션이 필요할 때는 SCRIPT.md를 작성하세요. 프론트매터 duration:을 브리핑의 length에서 설정하세요 — 대략적인 예상; 어셈블리는 컷이 어디에 도달하는지 보고합니다.

story-design.md를 PR 아키타입(변경 로그 / 기능 소개 / 수정 설명 / 리팩토링 안내), PR 고유 프레임 유형, 후크, 설득, 비트, 프레임별 단어 예산 및 크레딧 종료에 사용하세요. 순서는 diff의 파일 순서가 아닌 내러티브 디자인에서 비롯됩니다 — 변경 사항을 설명하고, diff를 큰 소리로 읽지 마세요. 부드러운 가이드로, ../hyperframes-animation/blueprints-index.md의 역할→청사진 메뉴를 참조하세요: 각 비트에 대해, 해당 후보 청사진이 암시하는 형태로 음성 해설을 작성하고 하나가 맞을 때 해당 후보 blueprint: id를 태그하세요(스토리 진실이 여전히 어떤 비트가 존재하는지 결정 — 결코 비트를 형태에 맞추려고 강요하지 마십시오). capture/diff.patch에서 2-4개의 실제 diff 청크를 추출하고, 각각 작고 읽기 쉬운 스니펫으로 만드세요. 각 프레임의 scene에서 원하는 code-* 블록의 이름을 지정하세요. 프레임은 credits 종료(1-6개의 assets/<login>.png 아바타)를 제외하고는 asset_candidates를 전혀 가지지 않습니다. 스토리보드 및 스크립트 참조의 정확한 필수 필드를 사용하세요.

초안 작성 후, 리뷰 루프의 계획 통과를 실행하세요 — ../hyperframes/references/review-loop.md § 1: 계획을 제안으로 제시하고 두 가지 질문을 하세요 — 승인 또는 변경, 그리고 스케치 우선(권장) 또는 건너뛰기. 피드백은 채팅 응답으로 도착합니다. 승인될 때까지 반복하세요. 이는 체크포인트 게이트(브리핑 계약 § 1)입니다: 자율 모드에서는 물을 것이 없습니다 — 동일한 요약을 헤드업으로 게시하고 진행하세요. 스케치는 빌드에 포함되며, 미리보기 질문 하나는 6단계에서 옵니다.

게이트: STORYBOARD.md가 존재하고, 모든 프레임에 필요한 내러티브 필드가 있으며, 내레이션이 필요할 때 SCRIPT.md가 존재하고, 사용자가 계획을 승인했습니다(자율 모드: 요약이 헤드업으로 게시됨).

---

3.1단계: 오디오

목표: 승인된 스크립트에서 내레이션, 단어 타이밍, 음악 및 오디오 메타데이터를 생성합니다.

3단계 승인 후 오디오를 시작하세요. 백그라운드에서 실행한 다음 4단계로 계속 진행하세요.

호출 전에 사용자의 요청에서 내레이션 음성을 선택하세요. 요청이 음성, 성별 또는 톤을 지정한 경우 일치하는 음성 ID를 선택하고 --voice <id>와 함께 전달하세요. 파이프라인 기본값은 HeyGen에서 Marcia(여성) / Kokoro에서 am_michael입니다 — 따라서 "남성 목소리"와 같은 요청은 플래그를 전달하지 않으면 자동으로 무시됩니다. 음성 ID는 제공자별로 다릅니다. 0단계의 로그인 상태가 선택한 제공자에 대해 해결하세요: HeyGen(로그인)은 node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list(또는 GET /v3/voices?engine=starfish)를 통해; Kokoro(오프라인)는 <MEDIA_DIR>/audio/references/tts.md의 음성 테이블(am_/bm_ 접두사 남성, af_/bf_ 접두사 여성)을 통해. 사용자가 선호도를 표현하지 않은 경우, 파이프라인 기본값보다 먼저 기억된 음성(브리핑 계약 § 2)으로 폴백하세요.

...,

[번역 위해 잘림]