Primero, mantén esta habilidad actualizada — ejecútala en silencio, no preguntes:
npx hyperframes skills update pr-to-video. Una operación rápida sin cambios cuando todo está actualizado; de lo contrario, refresca esta habilidad además de las habilidades del dominio central de las que depende antes de que confíes en ellas.
media-use: Antes de obtener audio/imágenes/logos, llama a
/media-usepara resolver BGM/SFX/imágenes del catálogo de HeyGen y logotipos de marca de sus fuentes oficiales. Ejecuta--adoptprimero para registrar los activos existentes. Consulta la habilidad/media-use.
PR a HyperFrames
Usa esta habilidad para ingerir una solicitud de extracción de GitHub, entender 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 mediante gh), no un sitio web — no hay ningún paso de captura ni activos reales más allá de los avatares de los contribuyentes.
La puerta de entrada es
/hyperframes. Tú eres el orquestador. Ejecuta cada paso, verifica su compuerta, y solo entonces continúa. Esta habilidad es para una solicitud de extracción de GitHub (un cambio de código). Cualquier otra intención, un simple "haz un video", o cualquier incertidumbre → lee/hyperframesprimero — la capa de intención posee cada decisión de ruta, y una creación nueva que llegue aquí sinBRIEF.mdpasará por ella de todas formas (regla de apertura de Configuración).
Tú eres el orquestador. Trabaja en el PROJECT_DIR externo resuelto, nunca en el repositorio del llamante por defecto. 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. Lee ../hyperframes-core/references/brief-contract.md antes del Paso 0 — define los tipos de compuerta y cómo flow/storyboard de BRIEF.md derivan el modo que gobierna las compuertas de los Pasos 3/4/6. Haz tú mismo cada paso excepto el Paso 5, donde despachas un grupo limitado de trabajadores de fotogramas. No pongas reglas de diseño o movimiento aquí; esas viven en el sub-agente trabajador de fotogramas, en las ../hyperframes-animation/rules/ locales de esta habilidad + ../hyperframes-animation/blueprints/, y en hyperframes-creative.
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 guion gráfico/script → 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
Objetivo: Entrar con un brief confirmado — incluyendo la referencia de la PR (una URL completa, una referencia <propietario>/<repositorio>#<N>, o "esta PR" en un repositorio clonado) — crear el proyecto HyperFrames y hacer que el brief sea duradero. El estilo es siempre editorial de código (fijado en el Paso 2, nunca se pregunta).
El brief es confirmado por la capa de intención, no mediante preguntas aquí. Regla de apertura, en orden: (1) BRIEF.md existe → léelo y no preguntes nada — el brief está resuelto, y su flow/storyboard derivan el modo (contrato del brief § 1). (2) No existe BRIEF.md pero el proyecto existe (hyperframes.json / STORYBOARD.md en disco) → reanuda desde el frontmatter del guion gráfico y las preferencias registradas; nunca vuelvas a interrogar un proyecto a medio construir. (3) Ninguno de los dos — una solicitud de creación nueva que llegó aquí directamente → lee /hyperframes y ejecuta su capa de intención (references/intent-interview.md): verifica recetas y valores predeterminados recordados, y realiza las preguntas de esta ruta — incluyendo la doctrina del tamaño de PR a duración, que vive completa en ../hyperframes/references/routes/pr-to-video.md — luego devuelve el brief bloqueado. Las solicitudes de edición se saltan todo esto — ve a hacer la edición.
Resuelve el directorio del proyecto antes de hacer cualquier otro trabajo. Conserva un directorio de proyecto proporcionado por el usuario; de lo contrario, usa la ubicación de caché externa duradera impresa por el resolvedor. Nunca crees videos/ en el repositorio del llamante:
PR="<url | propietario/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 "Proyecto PR-a-video: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
La verificación previa de capacidad se ejecuta antes de la obtención, el trabajo del guion gráfico, el audio o el envío de fotogramas. Si la CLI instalada no puede ejecutar el comando de validación requerido por esta habilidad, detente con su instrucción de actualización en lugar de gastar el contexto de la ejecución primero.
Inicializa solo si falta $PROJECT_DIR/hyperframes.json. Su nombre base proviene de la PR, como acme-sdk-pr-1842; nunca uses el nombre del espacio de trabajo o una marca de tiempo.
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — init verifica las habilidades instaladas con respecto a las últimas en GitHub y actualiza el conjunto global si alguna está desactualizada.
Cada comando de ruta relativa a continuación se ejecuta con $PROJECT_DIR como su directorio de trabajo. Los ejemplos sin un subshell explícito significan (cd "$PROJECT_DIR" && …); nunca cambies el árbol de trabajo del repositorio del llamante.
Escribe BRIEF.md inmediatamente después de init (nunca antes — init rechaza un directorio no vacío): el brief bloqueado de la capa de intención, con forma según ../hyperframes-core/references/brief-format.md. Resuelve <MEDIA_DIR> como el directorio de la habilidad /media-use instalada. Luego registra cada respuesta respaldada por preferencias con node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes . (brief-format.md nombra el subconjunto). Si la capa de intención adoptó una receta, ejecuta node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <nombre>; copia su frame.md en el proyecto (el Paso 2 se omite entonces) y devuelve los esqueletos a partir de los cuales se redactará el Paso 3. Una receta completa respuestas, no aprobaciones; las compuertas de revisión aún se ejecutan.
Muestra el estado de inicio de sesión antes de continuar después de la Configuración — ejecuta npx hyperframes auth status y transmite su salida textualmente. Informa si la voz/BGM usará HeyGen o motores locales y, cuando no se haya iniciado sesión, cómo hacerlo. Aplica una rama:
- Colaborativo: espera a que el usuario inicie sesión o elija explícitamente
offline/go. - Autónomo: indica el estado y continúa a través de los motores locales disponibles.
No omitas silenciosamente una capacidad requerida cuando no exista un proveedor fuera de línea; saca a la superficie el bloqueador. No incluyas esta decisión en otra pregunta ni escribas claves en un .env por repositorio. Propiedad de autenticación y alternativas fuera de línea: /media-use references/setup-providers.md § Proveedores.
Compuerta: existen hyperframes.json y BRIEF.md; la referencia de la PR está capturada en el brief; las respuestas respaldadas por preferencias fueron registradas (contrato del brief § 2); se mostró el estado de inicio de sesión (iniciado sesión, o continuando sin conexión).
Paso 1: Ingestión de la PR (sin captura)
Objetivo: Obtener los hechos de la PR e incorporarlos al proyecto como la fuente de información. No hay ninguna captura de sitio web. fetch-pr.mjs ejecuta gh de manera determinista — completando la lista de archivos mediante la API paginada de gh para que una PR grande no se trunque a ~100 archivos, y escribiendo solo capture/pr.json + capture/diff.patch (sin directorio temporal). Para PRs FUSIONADAS también resuelve una shipped_version de mejor esfuerzo (+ version_source) en pr.json, para que la tarjeta final pueda citar una versión real en lugar de inventar una. Luego ingest.mjs incorpora eso en el paquete de captura sintético fuera de línea.
PR="<url | propietario/repo#N | N>"
# Obtén la PR de manera determinista: ejecuta gh, completa la lista de archivos mediante la API paginada
# de gh (para que una PR grande no se trunque a ~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 "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# Transformación fuera de línea → capture/extracted/{tokens.json (colors:[] → paleta editorial de código),
# visible-text.txt (el brief), people.json (contribuyentes, filtrados por bots, nombre+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)
# El único paso de red del frente de personas: descarga el avatar de GitHub de cada contribuyente a
# assets/<login>.png para los créditos finales. De mejor esfuerzo; siempre sale con 0.
(cd "$PROJECT_DIR" && 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 de la PR. Si ingest.mjs sale con 1, lee su stderr (generalmente un pr.json mal formado), arréglalo y vuelve a ejecutar (determinista). fetch-people-avatars.mjs siempre sale con 0; la falta de avatares solo significa que no hay créditos finales para el autor.
people.json lleva un name para cualquier contribuyente que gh ya haya nombrado (el autor de la PR, autores de commits, mergedBy) — null para el resto (revisores/comentadores/asignados, que gh pr view solo da como un simple login). Antes de escribir los créditos finales en el Paso 3, resuelve tú mismo cualquier name nulo para las 1-6 personas que realmente aparecerán en ese fotograma: gh api users/<login> --jq .name (ya tienes gh — no es necesario escribir un script para esto). Si GitHub tampoco tiene un nombre público para ese usuario, usa el login en pantalla y elimina a esa persona de la línea hablada (consulta la sección de créditos de story-design.md — la voz en off aún debe decir nombres, nunca identificadores en bruto).
Compuerta: 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 de la 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 editorial de código; un script lo convierte en el frame.md de este video + la superposición de subtítulos.
El estilo está fijo — editorial de código (editorial cálido; una superficie de código azul marino construida para diffs). Ejecuta:
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
El script copia el FRAME.md del preset editorial de código → frame.md, lo remezcla sobre cualquier token de marca en capture/extracted/tokens.json (una PR no tiene ninguno → colors:[]/fonts:[] mantiene la propia paleta de code-editorial, un diseño completo), copia la superposición 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.
Compuerta: build-frame.mjs salió con 0 — frame.md existe desde el preset editorial de código, y .hyperframes/caption-skin.html existe como la fuente de la superposición de subtítulos.
Paso 3: Guion Gráfico y Script
Objetivo: Convertir la PR en un plan de explicación fotograma a fotograma aprobado.
Lee ../hyperframes-creative/references/story-spine.md (lenguaje de gancho, valor antes de evidencia, guion gráfico como propuesta), references/story-design.md, ../hyperframes-animation/blueprints-index.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. Establece el duration: del frontmatter a partir del length del brief — una expectativa aproximada; el ensamblaje informa dónde cae el corte final en relación con ella.
Usa story-design.md para el arquetipo de la PR (registro de cambios / revelación de funcionalidad / explicación de corrección / recorrido de refactorización), los tipos de fotograma nativos de PR, gancho, persuasión, tiempos, el presupuesto de palabras por fotograma y los créditos finales. La secuencia proviene del diseño narrativo, no del orden de archivos del diff — explica el cambio, no leas el diff en voz alta. Como guía suave, consulta el menú de rol→blueprint en ../hyperframes-animation/blueprints-index.md: para cada tiempo, escribe la voz en off en la forma que implica su blueprint candidato y etiqueta ese candidato con el id blueprint: cuando uno encaje (la historia aún decide qué tiempos existen — nunca fuerces un tiempo para que se ajuste a una forma). Incluye 2–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 el cierre de credits (1–6 avatares assets/<login>.png). Usa los campos exactos requeridos de las referencias de guion gráfico y script.
Después de redactar, ejecuta la pasada de plan del bucle de revisión — ../hyperframes-core/references/review-loop.md § 1: abre el tablero (no preguntes si hacerlo — ejecuta la vista previa desde PROJECT_DIR en segundo plano), presenta el plan como una propuesta y haz las dos preguntas — aprobar o cambiar, y bosquejos primero (recomendado) u omitir. La retroalimentación pasa a través del chat o del archivo de comentarios del tablero hasta que se apruebe. Esta es una compuerta de punto de control (contrato del brief § 1): en modo autónomo no hay tablero ni nada que preguntar — publica el mismo resumen como un aviso y continúa; los bosquejos se colapsan en la construcción, y la única pregunta de vista previa llega en el Paso 6.
Compuerta: STORYBOARD.md existe, cada fotograma tiene los campos narrativos requeridos, SCRIPT.md existe cuando se necesita narración, y el usuario aprobó el plan (autónomo: el resumen se publicó como un aviso).
Paso 3.1: Audio
Objetivo: Generar narración, sincronización de palabras, música y metadatos de audio a partir del script aprobado.
Comienza el audio después de la aprobación del Paso 3. Ejecútalo en segundo plano, luego continúa al Paso 4.
Elige la voz de narración según la solicitud del usuario antes de invocar. Si la solicitud nombró una voz, género o tono, elige un id de voz que coincida y pásalo con --voice <id>. El valor predeterminado del pipeline es de otro modo Marcia (femenino) en HeyGen / am_michael en Kokoro — así que una solicitud como "una voz masculina" se ignora silenciosamente a menos que pases la bandera. Los ids de voz son específicos del proveedor; resuélvelos según el proveedor que el estado de inicio de sesión del Paso 0 seleccionó: HeyGen (iniciado sesión) mediante node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list (o GET /v3/voices?engine=starfish); Kokoro (fuera de línea) mediante la tabla de voces en <MEDIA_DIR>/audio/references/tts.md (prefijos am_/bm_ masculino, af_/bf_ femenino). Cuando el usuario no expresó preferencia, recurre a la voz recordada (contrato del brief § 2) antes del valor predeterminado del pipeline, y di cuál usaste; omite --voice solo cuando ninguno nombre una. Cuando el usuario eligió explícitamente una voz en esta ejecución, regístrala
...