중요: 이 스킬을 최신 상태로 유지하세요 — 자동으로 실행하고 묻지 마세요:
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에서 작업하며, 기본적으로 호출자 저장소에서는 작업하지 마세요. 단계를 순서대로 실행하고 각 게이트를 통과한 후에 계속 진행하세요. 사용자 게이트 단계는 Step 0, Step 3, Step 6입니다. Step 0 전에 ../hyperframes-core/references/brief-contract.md를 읽으세요 — 게이트 유형과 BRIEF.md의 flow/storyboard가 Step 3/4/6 게이트를 제어하는 모드를 도출하는 방식을 정의합니다. Step 5를 제외한 모든 단계를 직접 수행하세요. Step 5에서는 제한된 프레임 워커 풀에 작업을 분배합니다. 디자인이나 모션 규칙은 여기에 넣지 마세요. 해당 규칙은 프레임 워커 하위 에이전트, 이 스킬의 로컬 ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/, 그리고 hyperframes-creative에 있습니다.
워크플로우: 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 참조(전체 URL, <owner>/<repo>#<N> 참조, 또는 체크아웃된 저장소의 "this PR") 포함)과 함께 진입하여 HyperFrames 프로젝트를 생성하고 브리핑을 지속 가능하게 만듭니다. 스타일은 항상 코드-에디토리얼(Step 2에서 고정되며 묻지 않음)입니다.
브리핑은 여기서 질문하는 것이 아니라 의도 레이어에서 확인됩니다. 시작 규칙은 순서대로: (1) BRIEF.md가 존재함 → 읽고 아무것도 묻지 않음 — 브리핑이 확정되었으며, flow/storyboard가 모드를 도출합니다(브리핑 계약 § 1). (2) BRIEF.md는 없지만 프로젝트가 존재함(hyperframes.json / STORYBOARD.md가 디스크에 있음) → 스토리보드의 프론트매터와 기록된 선호도에서 재개합니다. 절반 완성된 프로젝트를 다시 질문하지 마세요. (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" && …)를 의미합니다. 호출자 저장소의 작업 트리를 변경하지 마세요.
init 직후에 BRIEF.md를 작성하세요(절대 그 전에 작성하지 마세요 — init은 비어 있지 않은 디렉터리를 거부합니다): 의도 레이어의 잠긴 브리핑, ../hyperframes-core/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를 프로젝트로 복사하고(Step 2는 건너뜀) Step 3 초안이 작성될 스켈레톤을 반환합니다. 레시피는 답변을 채우고 승인을 채우지 않습니다. 검토 게이트는 여전히 실행됩니다.
설정을 진행하기 전에 로그인 상태를 표시하세요 — npx hyperframes auth status를 실행하고 출력을 그대로 전달하세요. 음성/BGM이 HeyGen을 사용할지 로컬 엔진을 사용할지, 그리고 로그아웃된 경우 로그인 방법을 보고합니다. 하나의 분기를 적용하세요:
- 협업: 사용자가 로그인하거나 명시적으로
offline/go를 선택할 때까지 기다립니다. - 자동: 상태를 알리고 사용 가능한 로컬 엔진을 통해 계속 진행합니다.
오프라인 제공자가 없을 때 필수 기능을 조용히 생략하지 마세요. 장애물을 표면화하세요. 이 결정을 다른 질문에 포함시키거나 키를 저장소별 .env에 작성하지 마세요. 인증 소유권 및 오프라인 폴백: /media-use references/setup-providers.md § 제공자.
게이트: hyperframes.json과 BRIEF.md가 존재합니다. PR 참조가 브리핑에 캡처되었습니다. 선호도 기반 답변이 기록되었습니다(브리핑 계약 § 2). 로그인 상태가 표시되었습니다(로그인됨 또는 오프라인 계속).
Step 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 인증/찾을 수 없음/비공개 오류는 여기에서 exit 1로 종료.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# 오프라인 변환 → capture/extracted/{tokens.json (colors:[] → 코드-에디토리얼 팔레트),
# 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가 1로 종료되면(gh 인증/찾을 수 없음/비공개), stderr를 보고하고 중단하세요 — PR 내용을 조작하지 마세요. ingest.mjs가 1로 종료되면 stderr를 읽고(보통 잘못된 형식의 pr.json), 수정하고 다시 실행하세요(결정론적). fetch-people-avatars.mjs는 항상 0으로 종료됩니다. 아바타가 없으면 저자 크레딧 클로즈가 없다는 의미일 뿐입니다.
people.json은 gh가 이미 이름을 지정한 기여자(PR 작성자, 커밋 작성자, mergedBy)에 대해 name을 전달합니다. 나머지(리뷰어/댓글 작성자/담당자, gh pr view는 항상 login만 제공)는 null입니다. Step 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는 최선 노력 — 없어도 실패가 아닙니다.
Step 2: 디자인 시스템
목표: 코드-에디토리얼 프레임 프리셋을 채택합니다. 스크립트가 이를 이 동영상의 frame.md + 캡션 스킨으로 변환합니다.
스타일은 고정되어 있습니다 — 코드-에디토리얼(웜 에디토리얼; diff에 최적화된 네이비 코드 표면). 실행:
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
스크립트는 코드-에디토리얼 프리셋의 FRAME.md를 복사 → frame.md로 만들고, capture/extracted/tokens.json의 브랜드 토큰(PR에는 없음 → colors:[]/fonts:[]는 코드-에디토리얼 고유 팔레트를 유지, 완전한 디자인)에 리믹스하고, 프리셋의 캡션 스킨을 .hyperframes/caption-skin.html로 복사하고, 자체 유효성 검사(깨진 매핑 시 1로 종료)합니다. 0으로 종료되는 즉시 진행하세요 — 수동 편집하지 마세요.
게이트: build-frame.mjs가 0으로 종료됨 — frame.md가 코드-에디토리얼 프리셋에서 존재하고, .hyperframes/caption-skin.html이 캡션 스킨 소스로 존재합니다.
Step 3: 스토리보드 및 스크립트
목표: PR을 승인된 프레임별 설명 계획으로 변환합니다.
../hyperframes-creative/references/story-spine.md(훅 언어, 증거 전 가치, 제안으로서의 스토리보드), references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes-core/references/storyboard-format.md, ../hyperframes-core/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에서 실제 diff 청크(2-4개)를 특징으로 하며, 각각 작은 읽기 쉬운 조각입니다. 각 프레임의 scene에서 원하는 code-* 블록의 이름을 지정하세요. 프레임에는 asset_candidates가 없습니다. credits 클로즈(1-6 assets/<login>.png 아바타)를 제외하고는 없습니다. 스토리보드 및 스크립트 참조의 정확한 필수 필드를 사용하세요.
초안을 작성한 후, 검토 루프의 계획 패스를 실행하세요 — ../hyperframes-core/references/review-loop.md § 1: 보드를 열고(물을 것인지 묻지 마세요 — PROJECT_DIR에서 백그라운드로 미리보기를 실행), 계획을 제안으로 제시하고, 두 가지 질문을 하세요 — 승인 또는 변경, 그리고 스케치 우선(권장) 또는 건너뛰기. 피드백은 승인될 때까지 채팅이나 보드의 주석 파일을 통해 반복됩니다. 이는 체크포인트 게이트(브리핑 계약 § 1)입니다: 자동 모드에서는 보드가 없고 물을 것이 없습니다 — 동일한 요약을 헤드업으로 게시하고 진행하세요. 스케치는 빌드에 통합되며, 하나의 미리보기 질문은 Step 6에서 나옵니다.
게이트: STORYBOARD.md가 존재하고, 모든 프레임에 필수 내러티브 필드가 있으며, 나레이션이 필요할 때 SCRIPT.md가 존재하고, 사용자가 계획을 승인했습니다(자동: 요약이 헤드업으로 게시됨).
Step 3.1: 오디오
목표: 승인된 스크립트에서 나레이션, 단어 타이밍, 음악 및 오디오 메타데이터를 생성합니다.
Step 3 승인 후 오디오를 시작하세요. 백그라운드에서 실행한 다음 Step 4로 계속 진행하세요.
호출하기 전에 사용자의 요청에서 나레이션 음성을 선택하세요. 요청이 음성, 성별 또는 톤을 지정한 경우, 일치하는 음성 ID를 선택하여 --voice <id>와 함께 전달하세요. 그렇지 않은 경우 파이프라인 기본값은 Marcia(여성) on HeyGen / am_michael on Kokoro입니다 — 따라서 "남성 음성"과 같은 요청은 플래그를 전달하지 않으면 자동으로 무시됩니다. 음성 ID는 제공자별로 다릅니다. Step 0의 로그인 상태가 선택한 제공자에 따라 확인하세요: HeyGen(로그인됨) via node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list(또는 GET /v3/voices?engine=starfish); Kokoro(오프라인) via <MEDIA_DIR>/audio/references/tts.md의 음성 테이블(접두사 am_/bm_ 남성, af_/bf_ 여성). 사용자가 선호도를 표현하지 않은 경우, 파이프라인 기본값 전에 기억된 음성(브리핑 계약 § 2)으로 폴백하고 사용한 음성을 말하세요. 둘 다 이름을 지정하지 않은 경우에만 --voice를 생략하세요. 사용자가 이 실행에서 명시적으로 음성을 선택한 경우 기록하세요.
… (잘림)
게이트: audio_meta.json이 존재하고 유효한 오디오 메타데이터를 포함합니다.
Step 4: 비주얼 디자인
목표: 방금 승인된 스토리보드의 각 프레임에 정확한 비주얼 지시사항을 추가합니다.
../hyperframes-animation/rules/및../hyperframes-animation/blueprints/를 읽으세요.../hyperframes-creative/references/visual-design.md를 읽으세요.STORYBOARD.md의 각 프레임에 대해scene및visual필드를../hyperframes-animation/rules/의 애니메이션 규칙을 따르는 정확한 비주얼 지시사항으로 강화하세요.- 사용 가능한 블루프린트에 코드 프레임 스타일(
code-diff,code-single-block등)을 적용하는 방법을 결정하세요. - 비주얼 시퀀스가 스토리보드의 내러티브 흐름과 일치하는지 확인하세요.
게이트: STORYBOARD.md의 모든 프레임이 완전하고 정확한 비주얼 지시사항으로 강화되었습니다.
Step 5: 프레임 구성
목표: 강화된 STORYBOARD.md에서 HTML 프레임 파일을 생성합니다.
이 단계는 허브 에이전트가 하위 프레임 워커를 사용하여 여러 프레임을 동시에 디스패치할 수 있는 지점입니다. 하위 프레임 워커가 완료될 때까지 기다리세요.
# 프레임 디스패치 스크립트 실행
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/dispatch-frames.mjs)
대규모 PR의 경우 워커 풀을 확장하는 것을 고려하세요.
게이트: compositions/frames/에 모든 예상 프레임(NN-*.html)이 존재하고, compositions/index.html이 존재합니다.
Step 6: 최종 렌더링
목표: 모든 프레임을 최종 비디오 파일로 컴파일합니다.
최종 렌더링 전에 사용자에게 미리보기를 제공하세요(협업 모드). 자동 모드에서는 자동으로 렌더링하세요.
# 비디오 렌더링
(cd "$PROJECT_DIR" && npx hyperframes render --output ./renders/video.mp4)
렌더링 후 최종 비디오의 위치를 보고하세요.
게이트: renders/video.mp4가 존재하고 재생 가능합니다.
추가 참고 사항
- 항상 브리핑 계약(
../hyperframes-core/references/brief-contract.md)을 참조하여 게이트 유형과 모드 파생을 이해하세요. - 이 스킬은 코드 변경(PR) 전용입니다. 다른 입력 유형(웹사이트, 일반 주제)의 경우
/hyperframes경로로 리디렉션하세요. - 필요한 경우(예: 큰 PR, 복잡한 변경 사항)에도 사용자에게 명확한 진행 상황과 다음 단계를 제공하세요.