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 activos existentes. Consulta la habilidad/media-use.
¿Qué hace De PR a HyperFrames?
Usa esta habilidad para ingerir un pull request de GitHub, comprender el cambio, planificar un vídeo 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 paso de captura ni activos reales más allá de los avatares de los contribuyentes.
Confirma la ruta antes del Paso 0. Eres el orquestador. Ejecuta cada paso, verifica su puerta y solo entonces continúa. Esta habilidad es para un pull request de GitHub (un cambio de código). Enruta otras intenciones a otro lado: lanzamiento/promoción de producto →
/product-launch-video; recorrido general de sitio web →/website-to-video; explicador de tema sin PR →/faceless-explainer; subtítulos en metraje existente →/embedded-captions; gráfico en movimiento corto sin narración →/motion-graphics; recorrido de lanzamiento de repositorio completo o multi-PR →/general-video. Fuera de alcance: datos en vivo / en tiempo de renderizado — los hechos del PR se leen una vez en tiempo de autoría y se integran. Si el usuario dice solo "haz un vídeo" 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 cada paso tú mismo excepto el Paso 5, donde envías un subagente por cuadro. No pongas reglas de diseño o movimiento aquí; esas viven en el subagente de trabajo de cuadro, hyperframes-creative y hyperframes-animation.
Flujo de trabajo: Paso 0 configuración → hyperframes.json; Paso 1 ingestión → capture/extracted/ + assets/<login>.png; Paso 2 sistema de diseño → frame.md; Paso 3 storyboard/guion → STORYBOARD.md y SCRIPT.md; Paso 3.1 audio → audio_meta.json; Paso 4 diseño visual → STORYBOARD.md enriquecido; Paso 5 cuadros → compositions/frames/NN-*.html e index.html; Paso 6 renderizado final → renders/video.mp4.
Paso 0: Configuración y Brief
Objetivo: Fijar la referencia del PR y el brief central del vídeo, 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 mensaje, confirma el brief — presenta un valor predeterminado recomendado para cada campo y rellena previamente cualquier cosa que /hyperframes ya haya establecido: ángulo (registro de cambios / revelación de funcionalidad / explicador de corrección / recorrido 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 estimación fija. Antes de confirmar el brief, 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 <PR_REF> --json title,additions,deletions,changedFiles
Elige el nivel de additions + deletions (ajustado por changedFiles) y preséntalo como 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 |
| centrado (~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 (ej. "~40s — cambio pequeño, +44/−13 en 12 archivos"). Un PR enorme no significa un vídeo largo — si la historia es un cambio destacado, sé 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 ni una marca de tiempo.
npx hyperframes init "videos/<project>" --non-interactive --example=blank — init comprueba las habilidades instaladas frente a las últimas en GitHub y actualiza el conjunto global si alguna está desactualizada.
Muestra el estado de inicio de sesión antes del brief — ejecuta npx hyperframes auth status y transmite su salida textualmente (no la parafrasees ni reescribas). Informa si la voz/BGM usará HeyGen o motores locales y, cuando no se 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 brief o cualquier otra cosa. Trátalo como un punto de decisión real, no una nota pasajera; no incluyas la elección en la pregunta del brief 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 → Preflight para obtener la guía canónica.
Puerta: hyperframes.json existe; la referencia 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 (sesión iniciada, o continuando sin conexión).
Paso 1: Ingestión del PR (sin captura)
Objetivo: Obtener los hechos del PR y agregarlos al proyecto como fuente de información. No hay captura de sitio web. fetch-pr.mjs ejecuta gh de forma determinista — completa la lista de archivos mediante gh api paginada 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 integra eso en el 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/<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 brief), people.json (contribuyentes, filtrados de 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 único paso de red del frente de personas: descarga el avatar de GitHub de cada contribuyente a
# 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 inventes 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; 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 indicar el cambio del PR en una frase 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 cuadro claude; un script lo convierte en frame.md + piel de subtítulos de este vídeo.
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 FRAME.md del preset claude → frame.md, lo remezcla sobre 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 un mapeo roto). Procede tan pronto como salga con 0 — sin edición manual.
Puerta: build-frame.mjs salió con 0 — frame.md existe desde el 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 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 / explicador de corrección / recorrido de refactorización), los tipos de cuadro nativos del PR, gancho, persuasión, tiempos, el presupuesto de palabras por cuadro 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 cuadro. Los cuadros no llevan asset_candidates excepto un cierre credits opcional (2–6 avatares assets/<login>.png). Usa los campos exactos requeridos de las referencias de storyboard 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 andamio del storyboard (npx hyperframes preview) — ábrela solo con un sí. Itera hasta que se apruebe; lleva la elección de vista previa al Paso 6.
Puerta: STORYBOARD.md existe, cada cuadro 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, temporización 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, la temporización de palabras, la búsqueda de BGM en la biblioteca de música de HeyGen y los metadatos de temporización. El estado de ánimo del BGM proviene del campo music: del storyboard. Esto usa la API de Audio de HeyGen para recuperación, no generación, y la misma credencial ~/.heygen que para TTS. Para detalles del proveedor, lee ../hyperframes-media/references/tts.md.
Si no hay narración ni SCRIPT.md, omite la generación de voz. El BGM puede ejecutarse igualmente 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 Cuadros
Objetivo: Añadir la dirección visual, la intención de diseño y las elecciones de movimiento a cada cuadro del storyboard.
Edita STORYBOARD.md directamente. No crees otro storyboard. Usa frame.md como fuente de verdad para color, tipo, sensación de diseño y 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 cuadro requeridos y el bloque requerido ## Video direction, 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 diseño/jerarquía/puntos focales y motion-language.md + ../hyperframes-animation/ para IDs de efectos y blueprints válidos. No inventes nombres de efectos ni IDs de bloques/blueprints.
Para cada cuadro, añade los campos visuales y de movimiento requeridos, incluyendo effects y focal y/o roles. Para un tiempo de código, nombra el bloque code-* como focal y deja que effects coreografie la Superficie de Código claude circundante (no la animación del código, que pertenece al bloque). Añade un bloque ## Video direction para todo el vídeo.
No cambies la historia, el guion, transition_in, asset_candidates ni 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 cuadro tiene effects más focal y/o roles; los cuadros de código nombran un bloque code-*; existe ## Video direction.
Paso 5: Construir Cuadros
Objetivo: Construir cada cuadro del storyboard como una composición HTML y ensamblar el vídeo reproducible.
Espera a que termine el audio del Paso 3.1 si se inició el audio. Luego sincroniza duraciones y obtén SFX; omite ambos si es silencioso.
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 duraciones es mecánica: la duración real de la voz gana; los cuadros silenciosos mantienen estimaciones; nunca edites manualmente las duraciones sincronizadas.
Preinstala los bloques de registro nombrados en STORYBOARD.md de una vez, antes del envío, para que los trabajadores paralelos no compitan por el registro:
for b in <cada bloque de 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. Envía un subagente por cuadro, en paralelo si es posible; de lo contrario, ejecuta trabajadores en oleadas. Cada trabajador recibe exactamente un cuadro. El contexto de cada trabajador debe incluir PROJECT_DIR, frame_id, tamaño del lienzo, estado de 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/blueprint 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 cuadro como animated en STORYBOARD.md.
Después de que existan las temporizaciones de audio, construye 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 archivo .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 no se necesita narración (sin SCRIPT.md) o el usuario optó por no usar subtítulos en el Paso 3. El índice se escribe en compositions/index.html y apunta a cada cuadro animado; la reproducción secuencial reproduce el vídeo. Después de la previsualización y antes de la puerta del Paso 6, ejecuta npx hyperframes check para verificar consistencia.
Puerta: todos los cuadros están animated (marcados en STORYBOARD.md); compositions/index.html existe; captions: * está resuelto; npx hyperframes check pasa.
Paso 6: Renderizado Final
Objetivo: Renderizar el proyecto como un archivo MP4 y confirmar la salida.
Primero, pregunta al usuario si desea reproducir la vista previa del Paso 5 (npx hyperframes preview desde el directorio del proyecto) — abre el enlace solo con un sí. Luego pregunta el perfil de renderizado: ultra (calidad máxima), normal (calidad estándar) o bajo (prueba rápida). Predeterminado: normal. Ejecuta el renderizado:
cd "videos/<project>"
npx hyperframes render --profile <ultra|normal|bajo> --out-dir ./renders
El renderizado puede tardar varios minutos. Si falla, lee y reporta el error; sugiere reintentar con un perfil más bajo. Cuando termine, confirma que renders/video.mp4 se ha creado con una duración razonable (~30–110s para un cambio centrado) y está listo para compartir.
Puerta: renders/video.mp4 existe con una duración y modo de reproducción correctos.
Fin de la Habilidad
Has completado el PR a HyperFrames. El vídeo final está en videos/<project>/renders/video.mp4. Puedes compartir el enlace o el archivo directamente.