Instalación del plugin: Antes de ejecutar comandos de configuración o actualización, sigue las reglas de ejecución de plugins cuando esta habilidad esté dentro de un plugin de HyperFrames. Las instalaciones independientes mantienen las instrucciones de actualización a continuación.
Primero, mantén esta habilidad actualizada — confirma con el usuario antes de ejecutar:
npx hyperframes skills update pr-to-video. Es una operación rápida sin cambios si todo está actualizado; de lo contrario, actualiza esta habilidad y las habilidades del dominio central de las que depende antes de utilizarlas.
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 primero--adoptpara registrar los assets existentes. Consulta la habilidad/media-use.
PR a HyperFrames
Usa esta habilidad para ingerir una solicitud de extracción 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 mediante gh), no un sitio web — no hay paso de captura ni assets reales más allá de los avatares de los colaboradores.
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 primero/hyperframes— la capa de intención es dueña de cada decisión de ruta, y una creación nueva que llega aquí sinBRIEF.mdpasa por ella de todos modos (regla de apertura de Configuración).
Eres el orquestador. Trabaja en el PROJECT_DIR externo resuelto, nunca en el repositorio de la llamada de forma predeterminada. 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/references/brief-contract.md antes del Paso 0 — define los tipos de compuerta y cómo BRIEF.md's flow/storyboard derivan el modo que rige 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 ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ locales de esta habilidad, y en hyperframes-creative.
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 storyboard/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
Objetivo: Entrar con un brief confirmado — incluyendo la referencia del PR (una URL completa, una referencia <propietario>/<repo>#<N>, o "este PR" en un repositorio clonado) — crear el proyecto HyperFrames y hacer duradero el brief. El estilo es siempre code-editorial (fijado en el Paso 2, nunca preguntado).
El brief es confirmado por la capa de intención, no por preguntas hechas 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 de brief § 1). (2) No hay BRIEF.md pero el proyecto existe (hyperframes.json / STORYBOARD.md en disco) → reanuda desde el frontmatter del storyboard 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 tamaño del PR → duración, que vive completa en ../hyperframes/references/routes/pr-to-video.md — luego devuelve el brief bloqueado. Las solicitudes de edición omiten 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 que imprime el resolvedor. Nunca crees videos/ en el repositorio de la llamada:
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-to-video: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
La verificación previa de capacidad se ejecuta antes de la obtención de datos, el trabajo de historia, el audio o el despacho 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 del PR, por ejemplo 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 contra 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 de la llamada.
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 la forma según ../hyperframes/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 desde los cuales se redacta el Paso 3. Una receta llena respuestas, no aprobaciones; las compuertas de revisión aún se ejecutan.
Muestra el estado de inicio de sesión antes de continuar más allá 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 iniciarla. 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 sin conexión; muestra el bloqueador. No combines esta decisión en otra pregunta ni escribas claves en un .env por repositorio. Propiedad de autenticación y alternativas sin conexión: /media-use references/setup-providers.md § Proveedores.
Compuerta: hyperframes.json y BRIEF.md existen; la referencia del PR está capturada en el brief; las respuestas respaldadas por preferencias fueron registradas (contrato de brief § 2); se mostró el estado de inicio de sesión (iniciada sesión, o continuando sin conexión).
Paso 1: Ingesta del PR (sin captura)
Objetivo: Obtener los datos del PR y plasmarlos en el proyecto como fuente de información. No hay captura de sitio web. fetch-pr.mjs ejecuta gh de forma determinista — completando la lista de archivos a través de gh api paginado para que un PR grande no se trunque en ~100 archivos, y escribiendo solo capture/pr.json + capture/diff.patch (sin directorio temporal). Para PRs FUSIONADOS también resuelve un 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 pliega eso en el paquete de captura sintético sin conexión.
PR="<url | propietario/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. 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 sin conexión → capture/extracted/{tokens.json (colors:[] → paleta code-editorial),
# visible-text.txt (el brief), people.json (colaboradores, 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 para las personas: descarga el avatar de GitHub de cada colaborador a
# assets/<login>.png para los créditos de cierre. 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 contenido 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 créditos de cierre para el autor.
people.json lleva un name para los colaboradores que gh ya nombró (el autor del PR, autores de commits, mergedBy) — null para el resto (revisores/comentaristas/asignados, para los cuales gh pr view solo da un login simple). Antes de escribir los créditos de cierre 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 necesitas escribir un script para esto). Si GitHub tampoco tiene un nombre público para ese usuario, recurre al 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 debe decir los nombres, nunca los identificadores en bruto).
Compuerta: capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt y capture/extracted/people.json existen; puedes enunciar 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 code-editorial; un script lo convierte en frame.md + la máscara de subtítulos de este video.
El estilo es fijo — code-editorial (editorial cálido; una superficie de código azul marino diseñada para diffs). Ejecuta:
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
El script copia el FRAME.md del preset code-editorial → 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 code-editorial, un diseño completo), copia la máscara 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.
Compuerta: build-frame.mjs salió con 0 — frame.md existe desde el preset code-editorial, y .hyperframes/caption-skin.html existe como fuente de la máscara de subtítulos.
Paso 3: Storyboard y Guion
Objetivo: Convertir el PR en un plan de explicación fotograma por fotograma aprobado.
Lee ../hyperframes-creative/references/story-spine.md (lenguaje de gancho, valor antes de evidencia, storyboard como propuesta, imágenes trazables a la fuente), references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes/references/storyboard-format.md y ../hyperframes/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 en relación con ella.
Usa story-design.md para el arquetipo del PR (registro de cambios / revelación de función / 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 los créditos de cierre. 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ú 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 verdad de la historia aún decide qué tiempos existen — nunca fuerces un tiempo para que encaje en una forma). Presenta 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 el cierre de credits (1–6 avatares assets/<login>.png). Usa los campos exactos requeridos de las referencias de storyboard y guion.
Después de redactar, ejecuta el pase de plan del bucle de revisión — ../hyperframes/references/review-loop.md § 1: presenta el plan como una propuesta y haz las dos preguntas — aprobar o cambiar, y bocetos primero (recomendado) o saltar. La retroalimentación llega como una respuesta de chat; repite hasta que se apruebe. Esta es una compuerta de control (contrato de brief § 1): en modo autónomo no hay nada que preguntar — publica el mismo resumen como aviso y procede; los bocetos se fusionan en la construcción, y la vista previa final con su única pregunta 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 fue publicado como aviso).
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, 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 de la canalización es, de lo contrario, Marcia (femenina) en HeyGen / am_michael en Kokoro — por lo 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 seleccionó el estado de inicio de sesión del Paso 0: HeyGen (con sesión iniciada) a través de node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list (o GET /v3/voices?engine=starfish); Kokoro (sin conexión) a través de la tabla de voces en <MEDIA_DIR>/audio/references/tts.md (prefijos am_/bm_ masculino, af_/bf_ femenino). Cuando el usuario no expresó ninguna preferencia, recurre a la voz recordada (contrato de brief § 2) antes del valor predeterminado de la canalización. Los comandos de ejemplo a continuación muestran la bandera; ajústala según corresponda.