Instalación del plugin: Antes de ejecutar comandos de configuración o actualización, siga las reglas de ejecución de plugins cuando este skill esté dentro de un plugin de HyperFrames. Las instalaciones independientes mantienen las instrucciones de actualización a continuación.
Primero, mantenga este skill actualizado — confirme con el usuario antes de ejecutar:
npx hyperframes skills update pr-to-video. Una operación rápida y sin cambios cuando todo está actualizado; de lo contrario, actualiza este skill y los skills centrales de los que depende antes de que confíe en ellos.
media-use: Antes de obtener audio/imágenes/logotipos, llame a
/media-usepara resolver BGM/SFX/imágenes del catálogo de HeyGen y logotipos de marca de sus fuentes oficiales. Ejecute--adoptprimero para registrar los activos existentes. Consulte el skill/media-use.
PR a HyperFrames
Utilice este skill para ingerir una solicitud de extracción (pull request) de GitHub, comprender el cambio, planificar un video explicativo de cambios 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 activos reales más allá de los avatares de los contribuyentes.
La puerta de entrada es
/hyperframes. Usted es el orquestador. Ejecute cada paso, verifique su compuerta y solo entonces continúe. Este skill es para una solicitud de extracción de GitHub (un cambio de código). Cualquier otra intención, un simple "hacer un video" o cualquier incertidumbre → lea/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 de apertura de Configuración).
Usted es el orquestador. Trabaje en el PROJECT_DIR externo resuelto, nunca en el repositorio de la persona que llama de forma predeterminada. Ejecute los pasos en orden y pase cada compuerta antes de continuar. Los pasos con compuerta de usuario son el Paso 0, el Paso 3 y el Paso 6. Lea ../hyperframes/references/brief-contract.md antes del Paso 0 — define los tipos de compuerta y cómo el flujo/storyboard de BRIEF.md derivan el modo que gobierna las compuertas de los Pasos 3/4/6. Haga usted mismo cada paso excepto el Paso 5, donde despacha un grupo limitado de trabajadores de fotogramas. No coloque reglas de diseño o movimiento aquí; esas residen en el sub-agente trabajador de fotogramas, los ../hyperframes-animation/rules/ locales + ../hyperframes-animation/blueprints/ de este skill, y 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 de la PR (una URL completa, una referencia <propietario>/<repositorio>#<N>, o "esta PR" en un repositorio clonado) — crear el proyecto HyperFrames y hacer durable el brief. El estilo es siempre editorial-código (fijo 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éalo y no pregunte nada — el brief está resuelto, y su flujo/storyboard derivan el modo (contrato del brief § 1). (2) No hay BRIEF.md pero el proyecto existe (hyperframes.json / STORYBOARD.md en disco) → reanude desde el frontmatter del storyboard y las preferencias registradas; nunca reinterrogue un proyecto a medio construir. (3) Ninguno de los dos — una solicitud de creación nueva que llegó aquí directamente → lea /hyperframes y ejecute 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 de PR → duración, que reside completa en ../hyperframes/references/routes/pr-to-video.md — luego devuelve el brief bloqueado. Las solicitudes de edición omiten todo esto — vaya y edite.
Resuelva el directorio del proyecto antes de realizar cualquier otro trabajo. Conserve un directorio de proyecto proporcionado por el usuario; de lo contrario, use la ubicación de caché externa duradera que imprime el resolvedor. Nunca cree videos/ en el repositorio de la persona que llama:
PR="<url | owner/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, el trabajo de historia, el audio o el envío de fotogramas. Si la CLI instalada no puede ejecutar el comando de validación requerido por este skill, deténgase con su instrucción de actualización en lugar de gastar el contexto de la ejecución primero.
Inicialice solo si falta $PROJECT_DIR/hyperframes.json. Su nombre base proviene de la PR, por ejemplo, acme-sdk-pr-1842; nunca use 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 los skills instalados con los últimos en GitHub y actualiza el conjunto global si alguno está desactualizado.
Cada comando con 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 cambie el árbol de trabajo del repositorio de la persona que llama.
Escriba 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/references/brief-format.md. Resuelva <MEDIA_DIR> como el directorio del skill /media-use instalado. Luego registre 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, ejecute 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 se redacta el Paso 3. Una receta completa respuestas, no aprobaciones; las compuertas de revisión aún se ejecutan.
Muestre el estado de inicio de sesión antes de continuar más allá de la Configuración — ejecute npx hyperframes auth status y transmita su salida textualmente. Informa si la voz/BGM usará HeyGen o motores locales y, cuando no haya iniciado sesión, cómo hacerlo. Aplique una rama:
- Colaborativo: espere a que el usuario inicie sesión o elija explícitamente
offline/go. - Autónomo: indique el estado y continúe a través de los motores locales disponibles.
No omita silenciosamente una capacidad requerida cuando no exista un proveedor fuera de línea; muestre el bloqueador. No incluya esta decisión en otra pregunta ni escriba claves en un .env por repositorio. Propiedad de autenticación y alternativas fuera de línea: /media-use references/setup-providers.md § Proveedores.
Compuerta: hyperframes.json y BRIEF.md existen; la referencia de la PR está capturada en el brief; las respuestas respaldadas por preferencias se registraron (contrato del brief § 2); se mostró el estado de inicio de sesión (inició sesión, o continúa sin conexión).
Paso 1: Ingerir la PR (sin captura)
Objetivo: Obtener los datos de la PR y combinarlos en el proyecto como fuente de información. No hay captura de sitio web. fetch-pr.mjs ejecuta gh de manera determinista — completando la lista de archivos mediante gh api paginada para que una PR grande no se trunque en ~100 archivos, y escribiendo solo capture/pr.json + capture/diff.patch (sin directorio temporal). Para PRs FUSIONADAS, 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 combina eso en el paquete de captura sintético sin conexión.
PR="<url | owner/repo#N | N>"
# Obtiene la PR de manera determinista: ejecuta gh, completa la lista de archivos mediante
# gh api paginada (para que una 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 editorial-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: descargar 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), informe su stderr y deténgase — no invente contenidos de PR. Si ingest.mjs sale con 1, lea su stderr (generalmente un pr.json malformado), corrija y vuelva a ejecutar (determinista). fetch-people-avatars.mjs siempre sale con 0; la falta de avatares solo significa que no hay créditos para el autor.
people.json lleva un name para los contribuyentes que gh ya nombró (el autor de la PR, autores de commits, mergedBy) — null para el resto (revisores/comentaristas/asignados, a los que gh pr view solo da un login simple). Antes de escribir los créditos finales en el Paso 3, resuelva usted mismo cualquier name nulo para las 1-6 personas que realmente aparecerán en ese fotograma: gh api users/<login> --jq .name (ya tiene gh — no necesita un script para esto). Si GitHub no tiene un nombre público para ese usuario, recurra al login en pantalla y elimine a esa persona de la línea hablada (consulte la sección de créditos de story-design.md — la voz en off aún debe decir nombres, nunca identificadores sin procesar).
Compuerta: capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt y capture/extracted/people.json existen; puede declarar 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-código; un script lo convierte en el frame.md + piel de subtítulos de este video.
El estilo es fijo — editorial-código (editorial cálido; una superficie de código azul marino diseñada para diffs). Ejecute:
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
El script copia el FRAME.md del preset editorial-código → frame.md, lo remezcla con cualquier token de marca en capture/extracted/tokens.json (una PR no tiene ninguno → colors:[]/fonts:[] mantiene la propia paleta del editorial-código, un diseño completo), copia la piel de subtítulos del preset en .hyperframes/caption-skin.html y se autovalida (sale con 1 en un mapeo roto). Proceda tan pronto como salga con 0 — sin edición manual.
Compuerta: build-frame.mjs salió con 0 — frame.md existe desde el preset editorial-código, y .hyperframes/caption-skin.html existe como fuente de la piel de subtítulos.
Paso 3: Storyboard y Guion
Objetivo: Convertir la PR en un plan de explicación fotograma por fotograma aprobado.
Lea ../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. Úselos para escribir STORYBOARD.md y, cuando se necesite narración, SCRIPT.md. Establezca el duration: del frontmatter desde el length del brief — una expectativa aproximada; el ensamblaje informa dónde cae el corte con respecto a ella.
Use story-design.md para el arquetipo de la PR (registro de cambios / presentación de funciones / explicación de corrección / resumen 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 — explique el cambio, no lea el diff en voz alta. Como guía suave, consulte el menú de rol→plano en ../hyperframes-animation/blueprints-index.md: para cada tiempo, escriba la voz en off en la forma que implica su plano candidato y etiquete ese candidato con el blueprint: id cuando se ajuste (la verdad de la historia aún decide qué tiempos existen — nunca fuerce un tiempo para que se ajuste a una forma). Presente 2–4 fragmentos de diff reales (de capture/diff.patch), cada uno un pequeño fragmento legible; nombre el bloque code-* que cada uno quiere en la scene del fotograma. Los fotogramas no llevan asset_candidates excepto los créditos finales (1–6 avatares assets/<login>.png). Use los campos obligatorios exactos de las referencias de storyboard y guion.
Después de redactar, ejecute el pase de plan del bucle de revisión — ../hyperframes/references/review-loop.md § 1: presente el plan como una propuesta y haga las dos preguntas — aprobar o cambiar, y bocetos primero (recomendado) u omitir. La retroalimentación llega como una respuesta de chat; repita hasta que se apruebe. Esta es una compuerta de punto de control (contrato del brief § 1): en modo autónomo no hay nada que preguntar — publique el mismo resumen como aviso y proceda; los bocetos 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 aviso).
Paso 3.1: Audio
Objetivo: Generar narración, tiempos de palabras, música y metadatos de audio a partir del guion aprobado.
Comience el audio después de la aprobación del Paso 3. Ejecútelo en segundo plano, luego continúe con el Paso 4.
Elija la voz de narración de la solicitud del usuario antes de invocar. Si la solicitud nombró una voz, género o tono, elija un id de voz coincidente y páselo con --voice <id>. El valor predeterminado de la canalización es Marcia (femenina) en HeyGen / am_michael en Kokoro — por lo tanto, una solicitud como "una voz masculina" se ignora silenciosamente a menos que pase la bandera. Los ids de voz son específicos del proveedor; resuelva contra el proveedor que seleccionó el estado de inicio de sesión del Paso 0: HeyGen (inició sesión) mediante node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list (o GET /v3/voices?engine=starfish); Kokoro (sin conexión) mediante 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, recurra a la voz recordada (contrato del brief § 2) antes del valor predeterminado de la canalización,
…
[truncado para traducción]