Communitygithub.com

federicobrancasi/pr-studio

Úsalo cuando el usuario quiera un video que explique un pull request (un video explicativo de PR, una revisión en video, 'haz un video para <URL del PR>'). Cubre todo el flujo de trabajo en este repositorio: obtener el PR, escribir la narración, la voz, elegir y completar los diagramas, verificaciones, renderizado, aprobación del director de PR y entrega.

¿Qué es pr-studio?

PR Studio es una habilidad especializada para agentes de IA (como Claude Code) que automatiza la creación de videos explicativos de pull requests en 40-100 segundos. Está diseñada para audiencias técnicas pero no expertas (como gerentes) que necesitan entender los cambios, el porqué, cómo funciona, los riesgos, el estado y por dónde empezar a revisar. Todo el proceso se controla mediante comandos CLI (`prs <comando>`) y cubre desde la obtención del PR, redacción del guion, generación de voz (con Azure o Kokoro local), selección de diagramas, renderizado de fotogramas, verificación de reglas de contenido (precisión factual, proveniencia del texto), renderizado final, publicación y aprobación por un agente 'pr-director'. Soporta flujos de trabajo desatendidos (GitHub Actions) o iniciados desde Slack, con un presupuesto de 59 minutos para sesiones en la nube. La habilidad enfatiza la precisión: cada afirmación en pantalla y narración debe provenir del PR, sin conjeturas ni lenguaje de marketing.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/federicobrancasi/pr-studio/tree/HEAD/.claude/skills/pr-video

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Video de PR

Un video explicativo de 40 a 100 segundos sobre un pull request, dirigido a alguien que no lo leerá (a menudo un gerente): qué cambios, por qué, cómo funciona, qué riesgos tiene, el estado y por dónde debería empezar un revisor. Técnico pero sencillo. Todo se ejecuta a través de la CLI: node cli/prs.mjs <comando> desde la raíz del repositorio, o node <ruta a pr-studio>/cli/prs.mjs <comando> desde cualquier lugar (abajo: prs).

Inicio

  • Nadie está mirando (un trabajo de GitHub Actions)? Lee primero guides/unattended.md: sin preguntas, un límite de tiempo, una ronda de revisión, dónde va el resultado.
  • Iniciado desde Slack (@GitHub, una sesión en la nube)? Lee primero guides/slack.md: triaje, el presupuesto de 59 minutos, publicar cada video en el hilo y qué no hacer allí.
  • Una vez por máquina: prs doctor (navegador, modelo de voz, Whisper, ffmpeg; solo agrega lo que falta).
  • Luego lee guides/story.md y guides/visuals.md. Hojea catalog.md para conocer los diagramas disponibles.

Flujo de trabajo (apunta a 15-20 minutos)

  1. Obtener. prs new <URL del PR> escribe videos/<slug>/: brief.md (léelo completo), pr.diff (búscalo para las líneas que necesites; no lo leas completo), pr.json y un esqueleto de guion gráfico con el número correcto de viñetas.
  2. Historia. Escribe videos/<slug>/storyboard.json: una idea por viñeta, una necesidad por viñeta, pistas y las afirmaciones con evidencia (guides/story.md). Ejecuta prs check hasta que diga listo para voz prs.
  3. Voz, en segundo plano. Inicia prs voice (aproximadamente un minuto; MAI-Voice-2 cuando hay una clave de Azure configurada, de lo contrario la voz local Kokoro) y sigue trabajando mientras se ejecuta.
  4. Dirección. prs direct elige un tratamiento para cada viñeta y el movimiento para el video, escribe direction.json y genera el esqueleto de scenes.js con esos tratamientos. Completa cada TODO del PR. Mantén las selecciones: se eligen para diferenciarse de videos recientes. Si uno realmente no puede mostrar su viñeta, vuelve a elegirlo con prs direct --use <beat>=<treatment> --reason "..." (la razón se registra y revisa).
  5. Apariencia. prs stills renderiza fotogramas clave y build/stills/contact.png. Abre la hoja de contactos y los fotogramas que importan, y arregla lo que veas. Los fotogramas funcionan antes de que la voz esté lista (temporización provisional).
  6. Verificación. prs lint debe reportar 0 problemas (diseño, procedencia del texto, banda de subtítulos, novedad, QR).
  7. Renderizar y publicar. prs render (segundos, los fotogramas están en caché), luego prs publish: codificar, subtítulos, la puerta de sincronización (audio vs subtítulos), entrega en ~/Downloads/pr-videos/<slug>/ y la entrada en la galería.
  8. Aprobación. Sigue guides/review.md hasta que el agente pr-director responda VEREDICTO: APROBADO; vuelve a publicar después de las correcciones.
  9. Entregar. Proporciona la ruta del mp4, su duración, un resumen de una línea por viñeta, el veredicto y lo que no pudiste verificar (no puedes escuchar el audio; la puerta de sincronización lo mide).

Opcional: si el usuario solicita opciones, agrega export const concepts = { beat, options: { a, b, c } } a scenes.js y ejecuta prs concepts: renderiza la viñeta de tres maneras lado a lado.

Reglas

  • Preciso o ausente. Cada afirmación en la narración y en pantalla debe provenir del PR: su cuerpo, commits, diff, pruebas o código en el commit principal. Escribe las afirmaciones no probadas del autor como "según el autor". Sin conjeturas sobre intenciones, sin marketing.
  • Procedencia del texto. El texto en pantalla pasa por label() (tus palabras), fact() (números y nombres de pr.json), quote() (texto exacto del PR), ident() (nombres de código en el diff), path() y code(). prepare verifica cada uno contra el PR; los números dentro de un label() se marcan.
  • Un solo aspecto visual. Blanco, paleta de Microsoft, Aptos. No agregues colores, fuentes, fondos o nuevos diseños dentro de un video. El primer fotograma (título) y la tarjeta final son fijos.
  • Explicaciones diferentes. Nunca abras ni copies el scenes.js de otro video; la galería solo guarda guiones gráficos y hojas de contactos. Si al catálogo le falta un diagrama que el PR necesita, agrega un tratamiento a catalog/ (con demo, when, parámetros, un fotograma de catálogo mediante prs catalog --stills, lint limpio) en lugar de colocar píxeles manualmente.
  • Mira lo que haces. Abre los fotogramas y la hoja de contactos antes de decir que algo funciona.

Comandos

prs new <url>obtener el PR, escribir brief.md y un esqueleto de guion gráfico
prs checkguion gráfico: ventana de duración, pistas, marcadores de posición, anclas de evidencia, sugerencias de pronunciación
prs voice [--provider mai|kokoro|recording|silent]narración + temporización de palabras (ajustada por pausas)
prs direct [--use beat=treatment --reason ...]elegir tratamientos y movimiento; generar el esqueleto de scenes.js
prs stills [--beat id] [--at 12.3,20]fotogramas clave + hoja de contactos
prs lint [--every 0.5]diseño, procedencia, banda de subtítulos, novedad, QR
prs render / prs draftfotogramas finales / un mp4 de vista previa a mitad de tamaño
prs publishcodificar, subtítulos, puerta de sincronización, entregar, galería
prs catalogcada tratamiento con sus parámetros
prs triage <PRs> | --file f, prs summary, prs budgetqué PRs merecen un video (ejecuciones de Slack); el mensaje de cierre; minutos restantes en una sesión en la nube
prs history, prs reportvideos recientes; dónde se fue el tiempo
prs smokeun video de demostración corto de principio a fin, con tiempos: ¿está lista esta máquina?

Skills relacionados