Primero, mantén esta habilidad actualizada — ejecútala en silencio, sin preguntar:
npx hyperframes skills update pr-to-video. Un no-op rápido cuando todo está actualizado; de lo contrario, actualiza esta habilidad y las habilidades del dominio central de las que depende antes de confiar 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 marcas 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, comprender el cambio, planificar un explicador de cambios de código y construirlo cuadro por cuadro 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.
La puerta de entrada es
/hyperframes. Tú eres el orquestador. Ejecuta cada paso, verifica su puerta de acceso 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 todos modos (regla inicial de Configuración).
Tú eres el orquestador. Trabaja en el PROJECT_DIR externo resuelto, nunca en el repositorio de la persona que llama por defecto. 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. Lee ../hyperframes-core/references/brief-contract.md antes del Paso 0 — define los tipos de puerta y cómo flow/storyboard de BRIEF.md derivan el modo que rige las puertas de los Pasos 3/4/6. Haz cada paso tú mismo excepto el Paso 5, donde despachas un grupo acotado de trabajadores de cuadros. No coloques reglas de diseño o movimiento aquí; esas viven en el subagente trabajador de cuadros, 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 ingesta → 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 cuadros → compositions/frames/NN-*.html y index.html; Paso 6 renderizado final → renders/video.mp4.
Paso 0: Configuración
Objetivo: Ingresar 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 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 por preguntas hechas aquí. Regla de apertura, en orden: (1) BRIEF.md existe → léelo y no preguntes nada — el brief está establecido, 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 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ó directamente aquí → 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 de tamaño del PR → duración, que reside completa en ../hyperframes/references/routes/pr-to-video.md — luego entrega 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 impresa por el resolvedor. Nunca crees videos/ en el repositorio de la persona que llama:
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 de 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 de la historia, el audio o el despacho de cuadros. 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 primero el contexto de la ejecución.
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 persona que llama.
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, 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 desde los que el Paso 3 redacta. Una receta completa las respuestas, no las aprobaciones; las puertas 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á los motores de HeyGen o locales y, cuando no 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; muestra el bloqueador. No incluyas esta decisión en otra pregunta ni escribas claves en un .env por repositorio. Propiedad de la autenticación y alternativas fuera de línea: /media-use references/setup-providers.md § Proveedores.
Puerta: hyperframes.json y BRIEF.md existen; la referencia del PR está capturada en el brief; las respuestas respaldadas por preferencias se registraron (contrato de brief § 2); se mostró el estado de inicio de sesión (inició sesión, o continúa sin conexión).
Paso 1: Ingestar el PR (sin captura)
Objetivo: Obtener los hechos del PR e incorporarlos al 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 COMBINADOS 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 incorpora eso en el paquete de captura sintético fuera de línea.
PR="<url | propietario/repo#N | N>"
# Obtén el PR de forma determinista: ejecuta gh, completa la lista de archivos a través de 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 fuera de línea → capture/extracted/{tokens.json (colors:[] → paleta editorial-de-código),
# visible-text.txt (el brief), people.json (contribuidores, filtrados por bots, nombre+inicioSesión,
# avatarFile=assets/<inicioSesión>.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 front de personas: descarga el avatar de GitHub de cada contribuidor en
# assets/<inicioSesión>.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 (autenticación gh / no encontrado / privado), reporta su salida de error estándar y detente — no fabriques contenido del PR. Si ingest.mjs sale con 1, lee su salida de error estándar (normalmente 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 finales para el autor.
people.json lleva un name para los contribuidores que gh ya nombró (el autor del PR, autores de commits, mergedBy) — null para el resto (revisores/comentaristas/asignados, que gh pr view solo da un login simple). Antes de escribir los créditos finales en el Paso 3, resuelve cualquier name nulo tú mismo para las 1 a 6 personas que realmente aparecerán en ese cuadro: gh api users/<login> --jq .name (ya tienes gh — no necesitas convertir esto en un script). Si GitHub tampoco tiene un nombre público para ese usuario, recurre al inicio de sesión 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).
Puerta: 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 cuadro editorial-de-código; un script lo convierte en frame.md de este video + máscara de título.
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 FRAME.md del preset editorial-de-código → 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 editorial-de-código, un diseño completo), copia la máscara de título del preset en .hyperframes/caption-skin.html y se autovalida (sale con 1 en un mapeo roto). Continúa tan pronto como salga con 0 — sin edición manual.
Puerta: 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 máscara de título.
Paso 3: Guion Gráfico y Script
Objetivo: Convertir el PR en un plan de explicación cuadro por cuadro aprobado.
Lee ../hyperframes-creative/references/story-spine.md (lenguaje del 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 duration: en el frontmatter según length del brief — una expectativa aproximada; el ensamblaje informa dónde cae el corte contra 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 cuadro nativos del PR, gancho, persuasión, tiempos, el presupuesto de palabras por cuadro 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→modelo en ../hyperframes-animation/blueprints-index.md: para cada tiempo, escribe la voz en off en la forma que implica su modelo candidato y etiqueta ese id de blueprint: candidato cuando encaje (la historia aún decide qué tiempos existen — nunca fuerces un tiempo para que encaje en una forma). Presenta 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 el cierre de credits (1 a 6 avatares assets/<login>.png). Usa los campos requeridos exactos de las referencias del guion gráfico y el 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 bocetos primero (recomendado) u omitir. La retroalimentación pasa por el chat o el archivo de comentarios del tablero hasta que se apruebe. Esta es una puerta de punto de control (contrato de brief § 1): en el modo autónomo no hay tablero ni nada que preguntar — publica el mismo resumen como aviso y continúa; los bocetos se colapsan en la compilación, y la única pregunta de vista previa llega en el 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 (autónomo: el resumen se publicó como aviso).
Paso 3.1: Audio
Objetivo: Generar narración, tiempos de palabras, música y metadatos de audio a partir del script 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 de la solicitud del usuario antes de invocar. Si la solicitud nombró una voz, género o tono, elige un id de voz coincidente y pásalo con --voice <id>. El valor predeterminado de la tubería es Marcia (femenino) en HeyGen / am_michael en Kokoro — por lo que una solicitud como "una voz masculina" se ignora silenciosamente a menos que pases el indicador. Los ids de voz son específicos del proveedor; resuélvelos contra el proveedor que seleccionó el estado de inicio de sesión del Paso 0: HeyGen (inició sesión) a través de node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list (o GET /v3/voices?engine=starfish); Kokoro (fuera de línea) 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 tubería, y di cuál usaste; omite --voice solo cuando ninguno nombra una. Cuando el usuario eligió explícitamente una voz en esta ejecución, regístrala.
[truncado para la traducción — el contenido original continuaba, pero aquí se trunca según la solicitud; en la traducción completa se mantendría la fidelidad al original.]