media-use: Antes de obtener audio/imágenes, llama a
/media-usepara resolver BGM/SFX/imágenes del catálogo de HeyGen. Ejecuta--adoptprimero para registrar los activos existentes. Consulta la skill/media-use.
¿Qué hace PR a HyperFrames?
Usa esta skill para ingerir un pull request de GitHub, comprender el cambio, planificar un video explicativo del cambio de código y construirlo fotograma a fotograma en HyperFrames. La entrada es un cambio de código (leído a través de gh), no un sitio web — no hay paso de captura ni activos reales más allá de los avatares de los colaboradores.
Confirma la ruta antes del Paso 0. Eres el orquestador. Ejecuta cada paso, verifica su puerta y solo entonces continúa. Esta skill es para un pull request de GitHub (un cambio de código). Enruta otras intenciones a otro lugar: un lanzamiento/promoción de producto →
/product-launch-video; un recorrido general por un sitio web →/website-to-video; un explicador de tema sin PR →/faceless-explainer; subtítulos en metraje existente →/embedded-captions; un gráfico en movimiento corto sin narración →/motion-graphics; un recorrido de lanzamiento de todo el repositorio o de múltiples PR →/general-video. Fuera del alcance: datos en vivo/en tiempo de renderizado — los datos del PR se leen una vez en el momento de la autoría y se incorporan. Si el usuario dice solo "haz un video" o la ruta es incierta, lee/hyperframesprimero.
Eres el orquestador. Trabaja en videos/<project>/. Ejecuta los pasos en orden y pasa cada puerta antes de continuar. Los pasos con puerta de usuario son el Paso 0, el Paso 3 y el Paso 6. Haz todos los pasos tú mismo excepto el Paso 5, donde despachas un sub-agente por fotograma. No pongas reglas de diseño o movimiento aquí; esas viven en el sub-agente de trabajo de fotogramas, hyperframes-creative y hyperframes-animation.
Flujo de trabajo: Configuración del Paso 0 → hyperframes.json; Ingesta del Paso 1 → capture/extracted/ + assets/<login>.png; Sistema de diseño del Paso 2 → frame.md; Storyboard/guion del Paso 3 → STORYBOARD.md y SCRIPT.md; Audio del Paso 3.1 → audio_meta.json; Diseño visual del Paso 4 → STORYBOARD.md enriquecido; Fotogramas del Paso 5 → compositions/frames/NN-*.html e index.html; Renderizado final del Paso 6 → renders/video.mp4.
Paso 0: Configuración y Resumen
Objetivo: Fijar la referencia del PR y el resumen básico del video, y crear el proyecto HyperFrames si es necesario.
Obtén la referencia del PR (una URL completa, una ref <owner>/<repo>#<N>, o "este PR" en un repositorio clonado) y, en un mensaje, confirma el resumen — encabeza con un valor predeterminado recomendado para cada uno y rellena previamente cualquier cosa que /hyperframes ya haya establecido: ángulo (registro de cambios / revelación de funcionalidad / explicación de corrección / recorrido de refactorización — predeterminado: inferir del PR), audiencia (predeterminado: desarrolladores), duración (predeterminado: escalar al tamaño del cambio del PR — ver más abajo), relación de aspecto (predeterminado 16:9), idioma. El estilo siempre es claude. Procede solo después de que el usuario responda; un "adelante" acepta los valores predeterminados.
Recomienda la duración según el tamaño del cambio del PR, no una suposición fija. Antes de confirmar el resumen, echa un vistazo rápido al PR — una llamada de solo lectura que también fundamenta el ángulo (el Paso 1 aún realiza la obtención determinista completa):
gh pr view <PR_REF> --json title,additions,deletions,changedFiles
Elige el nivel de additions + deletions (ajustado por changedFiles) y encabeza con él como valor predeterminado (el usuario puede anularlo; límite máximo ~3 min):
| Tamaño del cambio del PR | Duración recomendada |
|---|---|
| trivial (≲ 50 líneas cambiadas) | ~20–40s |
| enfocado (~50–200 líneas) | ~40–70s |
| sustancial (~200–600 líneas) | ~70–110s |
| grande (≳ 600 líneas, o 25+ archivos) | ~110–180s |
Indica la base en una frase cuando lo propongas (p. ej., "~40s — cambio pequeño, +44/−13 en 12 archivos"). Un PR enorme no significa un video largo — si la historia es un cambio principal, mantenlo conciso y dilo.
Inicializa solo si falta hyperframes.json. Nombra <project> a partir del PR en kebab-case, como acme-sdk-pr-1842; nunca uses el nombre del espacio de trabajo o una marca de tiempo.
npx hyperframes init "videos/<project>" --non-interactive --example=blank — init verifica las skills instaladas con las últimas en GitHub y actualiza el conjunto global si alguna está desactualizada.
Muestra el estado de inicio de sesión antes del resumen — ejecuta npx hyperframes auth status y transmite su salida textualmente (no la parafrasees ni la reescribas). Informa si la voz/BGM usará los motores de HeyGen o locales y, cuando no haya iniciado sesión, cómo iniciarla. Si no has iniciado sesión, DETENTE y espera a que el usuario elija — iniciar sesión, o decir "adelante"/"sin conexión" para continuar con los motores locales — antes de preguntar el resumen o cualquier otra cosa. Trátalo como un punto de decisión real, no una nota pasajera; no combines la elección en la pregunta del resumen y no escribas claves en un .env por repositorio. (En modo autónomo, anota el estado y continúa sin conexión). Consulta ../hyperframes-media → Verificación previa para obtener la guía canónica.
Puerta: hyperframes.json existe; la ref del PR está capturada; el ángulo, la duración, la relación de aspecto y el idioma están fijados; se mostró el estado de inicio de sesión (con sesión iniciada, o continuando sin conexión).
Paso 1: Ingesta del PR (sin captura)
Objetivo: Obtener los datos del PR e incorporarlos al proyecto como fuente de información. No hay captura de sitio web. fetch-pr.mjs ejecuta gh de manera determinista — completa la lista de archivos a través de gh api paginado para que un PR grande no se trunque en ~100 archivos, y escribe solo capture/pr.json + capture/diff.patch (sin directorio temporal). Luego, ingest.mjs incorpora eso al paquete de captura sintético sin conexión.
PR="<url | owner/repo#N | N>"
# Obtiene el PR de forma determinista: ejecuta gh, completa la lista de archivos mediante
# gh api paginado (para que un PR grande no se trunque en ~100 archivos), escribe solo capture/pr.json +
# capture/diff.patch — sin directorio temporal. gh auth / no encontrado / errores privados salen con 1 aquí.
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# Transformación sin conexión → capture/extracted/{tokens.json (colors:[] → paleta claude),
# visible-text.txt (el resumen), people.json (colaboradores, filtrados por bots, 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)
# El frente de personas tiene un paso de red: descargar el avatar de GitHub de cada colaborador en
# assets/<login>.png para un cierre de créditos opcional. Mejor esfuerzo; siempre sale con 0.
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Si fetch-pr.mjs sale con 1 (gh auth / no encontrado / privado), informa su stderr y detente — no fabriques contenidos del PR. Si ingest.mjs sale con 1, lee su stderr (generalmente un pr.json malformado), corrige y vuelve a ejecutar (determinista). fetch-people-avatars.mjs siempre sale con 0; la falta de avatares solo significa que no hay cierre de créditos para el autor.
Puerta: existen capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt y capture/extracted/people.json; puedes expresar el cambio del PR en una oración clara. assets/<login>.png es de mejor esfuerzo: su ausencia no es un fallo.
Paso 2: Sistema de Diseño
Objetivo: Adoptar el preset de fotograma claude; un script lo convierte en el frame.md de este video + la piel de subtítulos.
El estilo es fijo — claude (editorial cálida; una superficie de código azul marino diseñada para diffs). Ejecuta:
node <SKILL_DIR>/scripts/build-frame.mjs --preset claude --hyperframes .
El script copia el FRAME.md del preset claude → frame.md, lo remezcla con cualquier token de marca en capture/extracted/tokens.json (un PR no tiene ninguno → colors:[]/fonts:[] mantiene la propia paleta de claude, un diseño completo), copia la piel de subtítulos del preset a .hyperframes/caption-skin.html y se autovalida (sale con 1 en una asignación rota). Procede tan pronto como salga con 0 — sin edición manual.
Puerta: build-frame.mjs salió con 0 — frame.md existe del preset claude, y .hyperframes/caption-skin.html existe como fuente de la piel de subtítulos.
Paso 3: Storyboard y Guion
Objetivo: Convertir el PR en un plan de explicación fotograma a fotograma aprobado.
Lee references/story-design.md, ../hyperframes-core/references/storyboard-format.md y ../hyperframes-core/references/script-format.md. Úsalos para escribir STORYBOARD.md y, cuando se necesite narración, SCRIPT.md.
Usa story-design.md para el arquetipo del PR (registro de cambios / revelación de funcionalidad / explicación de corrección / recorrido de refactorización), los tipos de fotograma nativos del PR, gancho, persuasión, tiempos, el presupuesto de palabras por fotograma y el cierre de créditos opcional. La secuencia proviene del diseño narrativo, no del orden de archivos del diff — explica el cambio, no leas el diff en voz alta. Presenta de 2 a 4 fragmentos reales del diff (de capture/diff.patch), cada uno un pequeño fragmento legible; nombra el bloque code-* que cada uno quiere en la scene del fotograma. Los fotogramas no llevan asset_candidates excepto un cierre de credits opcional (2–6 avatares assets/<login>.png). Usa los campos requeridos exactos de las referencias de storyboard y guion.
Después de redactarlo, muestra un resumen fotograma a fotograma. En ese mismo mensaje, pregunta al usuario (a) si aprueba o solicita cambios, y (b) si desea una vista previa en vivo del andamio del storyboard (npx hyperframes preview) — ábrelo solo si dice que sí. Itera hasta que se apruebe; lleva la elección de vista previa al Paso 6.
Puerta: STORYBOARD.md existe, cada fotograma tiene los campos narrativos requeridos, SCRIPT.md existe cuando se necesita narración y el usuario aprobó el plan.
Paso 3.1: Audio
Objetivo: Generar narración, tiempos de palabras, música y metadatos de audio a partir del guion aprobado.
Inicia el audio después de la aprobación del Paso 3. Ejecútalo en segundo plano y luego continúa al Paso 4.
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
El script de audio maneja la narración, los tiempos de palabras, la búsqueda de BGM en la biblioteca musical de HeyGen y los metadatos de sincronización. El estado de ánimo del BGM proviene del campo music: del storyboard. Esto utiliza la API de Audio de HeyGen para la recuperación, no para la generación, y la misma credencial ~/.heygen que TTS. Para obtener detalles del proveedor, lee ../hyperframes-media/references/tts.md.
Si no hay narración y no hay SCRIPT.md, omite la generación de voz. El BGM aún puede ejecutarse si el storyboard tiene un estado de ánimo musical.
Puerta: el trabajo de audio ha comenzado, o el proyecto está marcado como silencioso.
Paso 4: Diseño Visual de Fotogramas
Objetivo: Agregar la dirección visual, la intención de diseño y las opciones de movimiento a cada fotograma del storyboard.
Edita STORYBOARD.md en el lugar. No crees otro storyboard. Usa frame.md como fuente de verdad para el color, la tipografía, la sensación del diseño y el estilo.
Lee references/visual-design.md, references/composition.md, references/motion-language.md, references/code-vocabulary.md y ../hyperframes-animation/. Usa visual-design.md para los campos de fotograma requeridos y el bloque ## Video direction requerido, y para cómo un tiempo de código nombra un bloque code-* como su focal. Usa code-vocabulary.md para elegir el bloque correcto por tiempo (diff = code-diff, refactor = code-morph, código nuevo = code-typing, …). Usa composition.md para la disposición/jerarquía/puntos focales y motion-language.md + ../hyperframes-animation/ para IDs de efectos y planos válidos. No inventes nombres de efectos ni IDs de bloques/planos.
Para cada fotograma, agrega los campos visuales y de movimiento requeridos, incluidos effects y focal y/o roles. Para un tiempo de código, nombra el bloque code-* como el focal y deja que effects coreografie la Superficie de Código claude circundante (no la animación del código, que el bloque posee). Agrega un bloque ## Video direction para todo el video.
No cambies la historia, el guion, transition_in, asset_candidates o la fuente del PR. No escribas HTML en este paso. No hay paso de preparación de activos — los únicos activos reales son los avatares de créditos, ya en assets/.
Puerta: cada fotograma tiene effects más focal y/o roles; los fotogramas de código nombran un bloque code-*; existe ## Video direction.
Paso 5: Construir Fotogramas
Objetivo: Construir cada fotograma del storyboard como una composición HTML y ensamblar el video reproducible.
Espera a que el audio del Paso 3.1 termine si se inició el audio. Luego sincroniza las duraciones y obtén los SFX; omite ambos si está en silencio.
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 .
La sincronización de duración es mecánica: la duración real de la voz gana; los fotogramas silenciosos mantienen las estimaciones; nunca edites manualmente las duraciones sincronizadas.
Preinstala los bloques del registro nombrados en STORYBOARD.md una vez, antes del envío, para que los trabajadores en paralelo no compitan por el registro:
for b in <cada bloque del registro nombrado en el storyboard>; do npx hyperframes add "$b"; done
Antes del envío, lee sub-agents/frame-worker.md y ../hyperframes-core/references/subagent-dispatch.md. Despacha un sub-agente por fotograma, en paralelo si es posible; de lo contrario, ejecuta trabajadores en oleadas. Cada trabajador recibe exactamente un fotograma. El contexto de cada trabajador debe incluir PROJECT_DIR, frame_id, tamaño del lienzo, estado de los subtítulos y banda de exclusión si los subtítulos están habilitados, ANIM_DIR (ruta absoluta a ../hyperframes-animation/) y la ruta absoluta a references/code-vocabulary.md. Cada trabajador lee frame.md, su propio bloque ## Frame N, el cuerpo de la receta para cada ID de efecto/plano citado y — para un tiempo de código — code-vocabulary.md para las entradas del bloque nombrado. Cada trabajador escribe solo compositions/frames/NN-*.html; los trabajadores nunca editan STORYBOARD.md.
A medida que cada trabajador regresa, marca ese fotograma como animated en STORYBOARD.md.
Después de que existan los tiempos de audio, construye los subtítulos en segundo plano y ensambla el índice:
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 usa el .hyperframes/caption-skin.html del proyecto (el de claude, copiado en el Paso 2), inyectando tokens de marca de frame.md; captions: skipped (<reason>) si …