먼저, 이 스킬을 최신 상태로 유지하세요 — 사용자에게 확인 후 실행:
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가 디스크에 있음) → 스토리보드의 frontmatter와 기록된 선호도에서 재개하세요. 절반만 완성된 프로젝트에 대해 다시 질문하지 마세요. (3) 둘 다 없음 — 여기에 직접 도착한 새로운 생성 요청 → /hyperframes를 읽고 의도 레이어(references/intent-interview.md)를 실행하세요. 레시피와 기억된 기본값을 확인하고, 이 경로의 질문(PR 크기 → 길이 원칙 포함, 이는 ../hyperframes/references/routes/pr-to-video.md 전체에 있습니다)을 수행한 다음, 잠긴 브리프를 반환합니다. 편집 요청은 이 모든 것을 건너뜁니다 — 바로 편집을 수행하세요.
다른 작업을 수행하기 전에 프로젝트 디렉토리를 확인하세요. 사용자가 제공한 프로젝트 디렉토리를 유지하세요. 그렇지 않으면 리졸버가 출력하는 영구 외부 캐시 위치를 사용하세요. 호출 저장소에 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이 없는 경우에만 초기화하세요. 기본 이름은 PR에서 비롯됩니다(예: acme-sdk-pr-1842). 워크스페이스 이름이나 타임스탬프를 사용하지 마세요.
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — init은 설치된 스킬을 GitHub의 최신 버전과 비교하고, 오래된 것이 있으면 전역 세트를 업데이트합니다.
아래의 모든 상대 경로 명령은 $PROJECT_DIR을 작업 디렉토리로 사용하여 실행됩니다. 명시적인 서브쉘이 없는 예제는 (cd "$PROJECT_DIR" && …)를 의미합니다. 호출 저장소의 작업 트리를 절대 변경하지 마세요.
초기화 직후 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만 작성합니다(스크래치 디렉토리 없음). MERGED 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 auth / not-found / private 오류는 여기서 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으로 다운로드하여 크레딧 종료에 사용합니다. 최선의 노력; 항상 0으로 종료합니다.
(cd "$PROJECT_DIR" && 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는 항상 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를 작성하세요. frontmatter 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)으로 대체하고 사용한 음성을 말하세요. 둘 다 지정하지 않은 경우에만 --voice를 생략하세요. 사용자가 이 실행에서 명시적으로 음성을 선택한 경우 기록하세요(prefs.mjs record --key voice).
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --project-dir . — 스크립트를 처리하고, 단어 타이밍을 생성하고, 직렬 오디오 파일을 로컬에 캐시하고(자동 오프라인 대체), audio_meta.json을 작성하며, 자체 유효성 검사(누락된 스크립트 시 exit 1)를 수행합니다. 이는 워크플로우 깊이에서 실행되므로 일반 --storyboard --script 외에 --project-dir .이 필요하여 HyperFrames CLI의 기본 pwd 기반 위치에서 audio_meta.json을 읽습니다. audio_meta.json이 전달되면 배경 오디오가 활성화됩니다. 이 단계에서 배경 음악을 수동으로 선택하거나 음악 설정에 대해 질문하지 마세요. audio.mjs가 해당 결정을 처리합니다. 로그아웃 상태에서 내레이션 음성을 사용할 수 없거나 오디오 엔진을 사용할 수 없는 경우 이를 표면화하세요.
audio_meta.json이 존재하는 즉시, 후속 단계는 STORYBOARD.md 및 SCRIPT.md만 사용합니다. 오디오 메타데이터를 다시 쿼리하지 마세요.
게이트: audio_meta.json이 존재합니다.
4단계: 시각 디자인
목표: 각 프레임의 동작, 전환 및 구성을 결정합니다.
../hyperframes-animation/의 청사진과 규칙을 사용하여 STORYBOARD.md에 디자인 결정으로 주석을 추가하세요. 각 프레임에 대해 시각적 레이아웃, 애니메이션 동작 및 전환 스타일을 지정하세요. code-editorial 스타일과 일관성을 유지하세요.
자동 모드에서는 계획 승인 후 스케치 단계를 건너뛰고 3단계에서 바로 이 작업을 수행하세요.
게이트: STORYBOARD.md에 모든 프레임에 대한 시각적 디자인 세부 정보가 주석으로 추가되었습니다.
5단계: 프레임 구축
목표: 프레임 작업자 풀을 사용하여 HTML 프레임 파일을 생성합니다.
각 프레임 작업자는 제한된 프레임 세트를 담당하며, 청사진과 규칙을 따르고, 완료를 보고합니다.
게이트: 모든 프레임 HTML 파일이 compositions/frames/에 존재하고 index.html이 생성되었습니다.
6단계: 최종 렌더링
목표: 최종 비디오 파일을 생성합니다.
npx hyperframes render를 실행하여 오디오, 전환 및 내레이션이 포함된 최종 비디오를 생성하세요. 렌더링 후 사용자에게 미리보기 및 승인을 요청하세요.
게이트: renders/video.mp4가 존재하고 사용자가 최종 출력을 승인했습니다.
시작하기 위한 빠른 참조
# 개발/생성
PR="https://github.com/owner/repo/pull/123"
npx hyperframes init my-pr-video --example=blank --skill=pr-to-video
cd my-pr-video
node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture
node <SKILL_DIR>/scripts/ingest.mjs --pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted
주요 파일 구조
hyperframes.json— 프로젝트 설정BRIEF.md— 브리프 문서STORYBOARD.md— 스토리보드 및 시각적 디자인SCRIPT.md— 내레이션 스크립트(해당하는 경우)frame.md— 프레임 디자인 시스템capture/— 수집된 PR 데이터assets/— 기여자 아바타compositions/frames/— 생성된 프레임 HTMLrenders/— 최종 비디오 출력