uso-de-medios: 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.
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 cuadro por cuadro en HyperFrames. La entrada es un cambio de código (leído mediante gh), no un sitio web — no hay ningún 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 compuerta y solo entonces continúa. Esta skill es para un pull request de GitHub (un cambio de código). Enruta otras intenciones a otra parte: un lanzamiento/promoción de producto →
/product-launch-video; un recorrido general por un sitio web →/general-video; un explicador temático sin PR →/faceless-explainer; subtítulos en material existente →/embedded-captions; un gráfico animado corto sin narración →/motion-graphics; un recorrido de lanzamiento de todo el repositorio o de varios PR →/general-video. Fuera del alcance: datos en vivo/en tiempo de renderizado — los hechos del PR se leen una vez en el momento de la autoría y se incorporan. Si el usuario solo dice "haz un video" o la ruta es incierta, lee/hyperframesprimero.
Eres el orquestador. Trabaja en videos/<proyecto>/. Ejecuta los pasos en orden y pasa cada compuerta antes de continuar. Los pasos con compuerta de usuario son el Paso 0, el Paso 3 y el Paso 6. Haz cada paso 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: Paso 0 configuración → hyperframes.json; Paso 1 ingesta → capture/extracted/ + assets/<login>.png; Paso 2 sistema de diseño → frame.md; Paso 3 guion gráfico/guion → STORYBOARD.md y SCRIPT.md; Paso 3.1 audio → audio_meta.json; Paso 4 diseño visual → STORYBOARD.md enriquecido; Paso 5 fotogramas → compositions/frames/NN-*.html y index.html; Paso 6 renderizado final → renders/video.mp4.
Paso 0: Configuración y Resumen
Objetivo: Fijar la referencia del PR y el resumen central del video, y crear el proyecto HyperFrames si es necesario.
Obtén la referencia del PR (una URL completa, una referencia <owner>/<repo>#<N>, o "este PR" en un repositorio clonado) y, en un solo mensaje, confirma el resumen: presenta un valor predeterminado recomendado para cada uno y completa previamente cualquier cosa que /hyperframes ya haya establecido: ángulo (registro de cambios / revelación de funcionalidad / explicación de corrección / guía de refactorización — predeterminado: inferir del PR), audiencia (predeterminado: desarrolladores), duración (predeterminado: escala según el tamaño del cambio del PR — ver más abajo), relación de aspecto (predeterminado 16:9), idioma. El estilo es siempre 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 al PR una vez — 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 <REF_PR> --json title,additions,deletions,changedFiles
Elige el nivel de additions + deletions (ajustado por changedFiles) y preséntalo como el 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–40 s |
| enfocado (~50–200 líneas) | ~40–70 s |
| sustancial (~200–600 líneas) | ~70–110 s |
| grande (~≳ 600 líneas, o 25+ archivos) | ~110–180 s |
Indica la base en una frase cuando lo propongas (por ejemplo, "~40 s — 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 <proyecto> a partir del PR en kebab-case, por ejemplo, acme-sdk-pr-1842; nunca uses el nombre del espacio de trabajo ni una marca de tiempo.
npx hyperframes init "videos/<proyecto>" --non-interactive --example=blank — init verifica las skills instaladas contra 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 utilizará 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 motores locales — antes de preguntar el resumen o cualquier otra cosa. Trátalo como un punto de decisión real, no como una nota pasajera; no incluyas 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.
Compuerta: hyperframes.json existe; la referencia del PR está capturada; el ángulo, la duración, la relación de aspecto y el idioma están fijos; se mostró el estado de inicio de sesión (inició sesión, o continúa sin conexión).
Paso 1: Ingesta del PR (sin captura)
Objetivo: Obtener los hechos del PR e incorporarlos al proyecto como fuente de información. No hay ninguna captura de sitio web. fetch-pr.mjs ejecuta gh de forma determinista — completando la lista de archivos mediante gh api paginada para que un PR grande no se trunque en ~100 archivos, y escribiendo 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 paginada (para que un PR grande no se trunque en ~100 archivos), escribe solo capture/pr.json +
# capture/diff.patch — sin directorio temporal. Los errores de gh auth / no encontrado / privado salen con 1 aquí.
(cd "videos/<proyecto>" && 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 de bots, avatarFile=assets/<login>.png)}.
(cd "videos/<proyecto>" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# El único paso de red del front de personas: descarga 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/<proyecto>" && 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 mal formado), corrige y vuelve a ejecutar (determinista). fetch-people-avatars.mjs siempre sale con 0; los avatares faltantes solo significan que no hay cierre de créditos para el autor.
Compuerta: capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt y capture/extracted/people.json existen; puedes indicar 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 de claude; un script lo convierte en el frame.md de este video + la máscara de subtítulos.
El estilo es fijo — claude (editorial cálido; 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:[] conserva la propia paleta de claude, un diseño completo), copia la máscara de subtítulos del preset en .hyperframes/caption-skin.html y se autovalida (sale con 1 en un mapeo roto). Procede tan pronto como salga con 0 — sin edición manual.
Compuerta: build-frame.mjs salió con 0 — frame.md existe desde el preset claude, y .hyperframes/caption-skin.html existe como fuente de la máscara de subtítulos.
Paso 3: Guion Gráfico y Guion
Objetivo: Convertir el PR en un plan de explicación cuadro por cuadro 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 / guía de refactorización), los tipos de fotograma nativos del PR, el gancho, la persuasión, los compases, 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. Incluye de 2 a 4 fragmentos de diff reales (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 créditos opcional (2–6 avatares assets/<login>.png). Usa los campos obligatorios exactos de las referencias de guion gráfico y guion.
Después de redactar, muestra un resumen cuadro por cuadro. En ese mismo mensaje, pregunta al usuario (a) si aprueba o solicita cambios, y (b) si desea una vista previa en vivo del andamiaje del guion gráfico (npx hyperframes preview) — ábrela solo si responde que sí. Itera hasta que esté aprobado; traslada la elección de la vista previa al Paso 6.
Compuerta: STORYBOARD.md existe, cada fotograma tiene los campos narrativos obligatorios, 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 con el 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 las palabras, la búsqueda de BGM en la biblioteca de música de HeyGen y los metadatos de sincronización. El estado de ánimo de BGM proviene del campo music: del guion gráfico. 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. BGM aún puede ejecutarse si el guion gráfico tiene un estado de ánimo musical.
Compuerta: el trabajo de audio ha comenzado, o el proyecto está marcado como silencioso.
Paso 4: Diseño Visual del Fotograma
Objetivo: Agregar la dirección visual, la intención de diseño y las opciones de movimiento a cada fotograma del guion gráfico.
Edita STORYBOARD.md en su lugar. No crees otro guion gráfico. Usa frame.md como fuente de referencia 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 obligatorios del fotograma y el bloque obligatorio ## Video direction, y para saber cómo un compás de código nombra un bloque code-* como su focal. Usa code-vocabulary.md para elegir el bloque correcto por compás (diff = code-diff, refactorización = code-morph, código nuevo = code-typing, …). Usa composition.md para el diseño/jerarquía/puntos focales y motion-language.md + ../hyperframes-animation/ para los ID de efecto y blueprint válidos. No inventes nombres de efectos o ID de bloques/blueprints.
Para cada fotograma, agrega los campos visuales y de movimiento obligatorios, incluidos effects y focal y/o roles. Para un compás de código, nombra el bloque code-* como el focal y permite que effects coreografie la superficie de código de claude circundante (no la animación del código, que posee el bloque). 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 ningún paso de preparación de activos — los únicos activos reales son los avatares de créditos, ya en assets/.
Compuerta: cada fotograma tiene effects más focal y/o roles; los fotogramas de código nombran un bloque code-*; ## Video direction existe.
Paso 5: Construir Fotogramas
Objetivo: Construir cada fotograma del guion gráfico como una composición HTML y ensamblar el video reproducible.
Espera a que el audio del Paso 3.1 termine si se inició. 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 de 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 de registro nombrado en el storyboard>; do npx hyperframes add "$b"; done
Antes de enviar, 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 los trabajadores en oleadas. Cada trabajador recibe exactamente un fotograma. El contexto de cada trabajador debe incluir PROJECT_DIR, frame_id, el tamaño del lienzo, el estado de los subtítulos y la 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/blueprint citado y — para un compás 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 (<motivo>) es v
…
[truncado para traducción]