jackyuyz/repo-demo-video-skill

Repo Demo Video

Usa este skill para convertir un repositorio en un plan pulido de demostración de producto y, cuando haya suficiente información de tiempo de ejecución, en un video de demostración grabado desde el navegador.

Principio Fundamental

Prefiere la evidencia del repositorio sobre la configuración perfecta del usuario:

1. Usa demo.config.json o demo.config.yaml cuando estén presentes.
2. Usa DEMO_GUIDE.md cuando esté presente.
3. Usa README.md.
4. Usa package.json, archivos del framework, carpetas de rutas, nombres de componentes, títulos de página y estructura del código fuente.
5. Explora una aplicación desplegada o local en el navegador cuando exista una URL segura.
6. Genera suposiciones alternativas con puntuaciones de confianza.

Trata README.md más el código fuente como la fuente principal, DEMO_GUIDE.md como la guía amigable recomendada y demo.config.* como una anulación opcional legible por máquina.

Flujo de Trabajo

1. Resuelve la ruta o URL del repositorio objetivo. Para la CLI MVP, usa una ruta de repositorio local; si se proporciona una URL de GitHub, pide al usuario que proporcione un clon local a menos que un flujo de clonación futuro esté explícitamente disponible.

2. Ejecuta el analizador:

   npm run demo -- --repo ./ruta-al-repositorio
   

   Entradas opcionales:

   npm run demo -- --repo ./ruta-al-repositorio --config ./demo.config.json
   npm run demo -- --repo ./ruta-al-repositorio --url https://example.com
   npm run demo -- --repo ./ruta-al-repositorio --mode draft
   npm run demo -- --repo ./ruta-al-repositorio --mode full
   

3. Revisa los artefactos generados en una carpeta de salida con marca de tiempo, como demoOutput-2026-05-10-143012/:

   • project_summary.md
   • demo_plan.draft.json
   • demo_plan.json cuando la confianza es suficientemente alta
   • narration_script.draft.md
   • narration_script.md
   • script_quality_report.json
   • timing_plan.json
   • demo_storyboard.md
   • manual_recording_guide.md
   • recordings/ cuando la captura del navegador tiene éxito
   • screenshots/ cuando la exploración del navegador tiene éxito
   • voiceover.mp3 cuando TTS_PROVIDER=openai y OPENAI_API_KEY están disponibles
   • demo_video.html como alternativa de vista previa local cuando la composición MP4 está incompleta
   • demo_video.mp4 solo cuando la grabación, el audio real y ffmpeg están disponibles

Reglas de Confianza

• Marca las afirmaciones de documentación explícita y de configuración como alta.
• Trata las listas de características del README como evidencia suficiente para generar un plan final cuando el nombre del proyecto, el resumen y al menos una característica estén claros.
• Marca los nombres de rutas, nombres de componentes, metadatos de paquete y estructura de código clara como media.
• Marca afirmaciones especulativas del producto y acciones adivinadas como baja.
• Si las afirmaciones importantes tienen baja confianza, genera demo_plan.draft.json, explica lo que falta y evita presentar el plan de video final como seguro.

Análisis de README

• Ignora insignias, imágenes de escudo, filas de imágenes decorativas, URLs sin procesar y metadatos de licencia/estado al extraer resúmenes del producto.
• Prefiere la propuesta de DEMO_GUIDE.md, el resumen en cita del README, las secciones de descripción general/resumen/descripción del README, y luego la descripción del paquete.
• Reconoce encabezados decorados como ## Features con emojis o símbolos normalizando los encabezados antes de la coincidencia.
• Extrae listas con viñetas bajo encabezados de características/capacidades/destacados como características de alta confianza.
• Extrae flujos de trabajo numerados bajo encabezados de uso/cómo usar/demo/inicio rápido como pistas de flujo de demostración de confianza media.
• Sanitiza las entradas de narración antes de escribir guiones; no incorpores insignias de Markdown, sintaxis de imágenes ni URLs sin procesar en el texto de la voz en off.

Seguridad

• Mantén el análisis del repositorio como de solo lectura.
• Escribe los artefactos generados solo en una nueva carpeta demoOutput-YYYY-MM-DD-HHMMSS/ con marca de tiempo dentro del repositorio objetivo.
• No elimines archivos de forma recursiva ni ejecutes comandos destructivos.
• No ejecutes comandos de despliegue.
• Se permiten llamadas externas a LLM/TTS cuando el usuario solicita salida narrada o configura variables de entorno del proveedor. Envía solo resúmenes de proyecto sanitizados, planes de demostración, observaciones del navegador y texto del guión de narración.
• No envíes archivos .env sin procesar, claves de API, tokens privados, datos de usuario privados, credenciales reales ni archivos fuente innecesarios a proveedores externos de LLM/TTS.
• No expongas secretos, claves de API, tokens privados, valores de .env, datos de usuario privados ni credenciales reales en la narración, capturas de pantalla, video, registros o artefactos generados.
• Si se documenta una cuenta de prueba, menciona solo que se usa una cuenta de demostración a menos que el usuario solicite explícitamente lo contrario.

Comportamiento del Navegador y Video

• Prefiere un demoUrl desplegado desde la configuración, DEMO_GUIDE.md, README o el argumento --url.
• Usa Playwright cuando esté disponible para inspeccionar encabezados visibles, botones, enlaces, formularios y capturar capturas de pantalla o grabaciones.
• Usa heurísticas conservadoras del DOM para rellenar entradas de muestra seguras, seleccionar opciones de selector no vacías y hacer clic en controles de demostración comunes como Add, Calculate, Method, Resources, New o Create.
• Mantén cada escena planificada en pantalla el tiempo suficiente para el ritmo de la narración y haz una pausa breve después de las acciones heurísticas para que la grabación no sean solo clics rápidos.
• Registra la ruta canónica de grabación .webm en run_report.json.
• No fuerces el inicio del proyecto local cuando las instrucciones de ejecución sean inciertas.
• Si Playwright, TTS, ffmpeg o el tiempo de ejecución de la aplicación no están disponibles, aún así produce los artefactos escritos, los entregables parciales, demo_video.html y una guía de grabación manual.
• Compone el MP4 final según la duración de la voz en off. No uses truncamiento del flujo más corto. Si la grabación del navegador es más corta que la voz en off, extiende el fotograma final del video con ffmpeg tpad e informa la duración de la extensión.

Escritura Profesional de Guiones

• Usa el borrador determinista como alternativa, pero prefiere el escritor de guiones de OpenAI cuando SCRIPT_PROVIDER=openai y OPENAI_API_KEY están configurados.
• Genera timing_plan.json antes de escribir el guión final. Basa el plan en las características disponibles, escenas del navegador, duración de video configurada y advertencias de ritmo.
• Usa la misma OPENAI_API_KEY para la escritura de guiones y para OpenAI TTS.
• Controla el prompt de escritura de la demostración del producto en src/prompts/demoNarrationPrompt.ts.
• Controla el modelo de OpenAI Responses API con OPENAI_SCRIPT_MODEL; si no está configurado, recurre a OPENAI_MODEL, luego a gpt-5.4-mini.
• Escribe narration_script.draft.md para el borrador de la plantilla y narration_script.md para el guión final LLM o alternativo.
• Escribe script_quality_report.json con el proveedor, modelo, motivo de la alternativa y advertencias de control de calidad.
• El prompt debe hacer que el escritor de guiones entienda primero el producto, evitar insignias y metadatos sin procesar del README, centrarse en la audiencia/problema/valor, usar un lenguaje conservador para afirmaciones inciertas y respetar el recuento de escenas y el presupuesto de palabras del plan de tiempo.

Guía Visual de Demostración

Para grabaciones pulidas del navegador, inyecta superposiciones temporales de guía visual no persistentes a través de Playwright en lugar de editar el código fuente de la aplicación.

Usa:

• Un pie de imagen sutil para el compás actual de la narración.
• Un anillo de resalte alrededor del elemento de UI activo o área de resultado.
• Alto z-index, pointer-events: none y posicionamiento fijo.
• Estilo neutral que no oscurezca la UI del producto.

No uses superposiciones para inventar funcionalidad. Úsalas solo para guiar la atención del espectador hacia cambios reales en el estado de la UI. Las superposiciones deben existir solo en la sesión del navegador de grabación y desaparecer cuando la sesión se cierre.

Voz en Off

• Por defecto, usa OpenAI TTS en modo completo cuando OPENAI_API_KEY está configurada.
• Para generar audio real explícitamente, configura TTS_PROVIDER=openai y OPENAI_API_KEY.
• Si TTS_PROVIDER no está configurado pero existe OPENAI_API_KEY, usa OpenAI TTS.
• Para forzar el modo simulado local, configura TTS_PROVIDER=mock.
• OPENAI_API_KEY puede ser la misma clave utilizada por el escritor de guiones profesional.
• Variables opcionales: OPENAI_TTS_MODEL, OPENAI_TTS_VOICE, OPENAI_TTS_INSTRUCTIONS, TTS_VOICE.
• Escribe el audio real en la carpeta de la ejecución actual, por ejemplo demoOutput-2026-05-10-143012/voiceover.mp3.
• Enviar el texto sanitizado voiceover_script.txt al proveedor TTS configurado es necesario para crear el audio de la voz en off.
• Nunca escribas claves de API en los archivos generados.
• Divulga que la voz en off generada es generada por IA al publicar la demostración.

Extender el Skill

Mantén la arquitectura modular. Agrega soporte futuro para clonación de URL de GitHub, interacción más profunda con la UI, proveedores TTS reales, subtítulos, estilos de video, inicio local y revisión humana extendiendo el módulo src/*.ts correspondiente en lugar de convertir la CLI en un solo script grande.