ajewoleOlugbenga/video-skills

Video Demo de App

Convierte un repositorio de aplicación web en un video demo terminado. Tú (Claude) actúas como product marketer, grabador de pantalla y editor de motion. El desarrollador solo responde una ronda de preguntas y aprueba la historia.

Sigue siempre los pasos a continuación en orden, comenzando con el escaneo y el mensaje de una sola pregunta (Paso 3). Nunca te saltes directamente a hacer un video, sea cual sea la herramienta o enfoque que usarías de otro modo.

v1 soporta aplicaciones web (cualquier cosa que se ejecute en un navegador). Las apps nativas móviles, CLI y API están fuera del alcance: indícalo y detente si el repositorio es de ese tipo.

Los puntos no negociables

1. Nunca modifiques el repositorio del desarrollador. Todo el trabajo se realiza en una carpeta de espacio de trabajo separada. No hagas commit, no agregues archivos al repositorio, no cambies su configuración.
2. Nunca leas ni imprimas valores secretos. No abras archivos .env. Los nombres de variables de entorno (de .env.example) están bien. Si la app necesita secretos, el desarrollador los coloca en .env él mismo; nunca le pidas que pegue claves en el chat.
3. Nunca filmes datos personales reales. Usa cuentas de prueba y datos demo. Difumina correos electrónicos, claves API, tokens y nombres reales con selectores hide.
4. Nunca actúes sobre datos de producción. Los scripts de siembra y los envíos de formularios solo se ejecutan contra entornos locales o de staging. En una URL en vivo, solo navega y mira a menos que el desarrollador apruebe explícitamente una acción específica.
5. El guion es un borrador. Todo lo que infieras sobre la audiencia, el problema y las ventajas está etiquetado como borrador para que el desarrollador lo edite. No afirmes números de usuarios, testimonios, propiedades de velocidad o seguridad que el código no demuestre.

Flujo de trabajo

Paso 1: Configurar el espacio de trabajo

cp -r <skill-dir>/template ~/app-demos/<app-slug>      # una vez por app
cd ~/app-demos/<app-slug> && npm install
npx playwright install chromium                          # una vez por máquina (o establece CHROME_PATH)

<skill-dir> es la carpeta donde reside este SKILL.md (el directorio base de la skill, mostrado cuando se carga la skill). Puede estar dentro de un caché de plugins o ~/.claude/skills/; nunca edites archivos allí, siempre copia primero la plantilla.

Todo lo siguiente se ejecuta desde este espacio de trabajo. La ruta del repositorio es <repo>: la carpeta del proyecto actual, o la carpeta que el desarrollador ha conectado.

Paso 2: Escanear el repositorio (solo lectura)

node scripts/scan-repo.mjs <repo> --json scan.json

Esto imprime el framework, los comandos de instalación y ejecución, el puerto, las rutas/páginas, los nombres de variables de entorno, las librerías de autenticación y base de datos, los scripts de siembra, los archivos de logo y los colores de marca más utilizados. Luego, lee el README y los archivos principales de página/componente para las rutas que parecen funciones principales (dashboards, editores, flujos de crear/nuevo, configuraciones importantes). El objetivo es entender lo que un usuario realmente hace en la app.

Paso 3: Un mensaje para el desarrollador: borrador del guion + preguntas

Envía todo en un solo mensaje para que el desarrollador pueda responder una vez. Usa la herramienta AskUserQuestion para los elementos de opción múltiple cuando esté disponible.

A. Borrador del guion (indica claramente que está redactado a partir del código; pídeles que lo corrijan):

• Frase resumen: qué es, en ≤ 12 palabras
• Para quién es
• El problema que resuelve
• 3 cosas que lo hacen destacar (a partir de las funciones reales que encontraste)

B. Funciones propuestas: enumera 5–7 funciones que encontraste, cada una con la ruta en la que se encuentra. Pídeles que elijan 3–5 y que nombren las que te hayas perdido.

C. Preguntas:

1. ¿Dónde se publicará el video? → decide el formato. YouTube / sitio web / LinkedIn / Product Hunt → 16:9 horizontal. Reels / TikTok / Shorts / X → 9:16 vertical. Publicaciones en feeds → 1:1 o 4:5.
2. ¿Cómo debo capturar la app? (a) La ejecuto localmente, (b) me das una URL (staging preferido), (c) me envías capturas de pantalla/grabaciones.
3. Inicio de sesión de prueba, si la app tiene autenticación: una cuenta de prueba, o permiso para crear una localmente. Nunca su cuenta real.
4. Llamada a la acción + enlace (registrarse, GitHub, reservar un demo, lista de espera).
5. Marca: confirma el logo y los colores detectados, o proporciónalos.
6. Cualquier cosa que no deba aparecer en pantalla.
7. Audio: ofrece estas tres opciones, con tu recomendación primero (ver "Elegir el audio" a continuación):
   • Música + efectos de sonido solamente (predeterminado)
   • Locución con IA + subtítulos: gratuita, generada offline en su máquina, sin cuenta. Voces: Norman (masculino EE. UU.) o Cori (femenino Reino Unido). Ofrece enviar muestras breves de ambas antes de que elijan.
   • Su propia voz grabada

Detente aquí y espera las respuestas. No instales, ejecutes, captures ni renderices nada antes de que el desarrollador responda, incluso si la solicitud sonó como "solo hazlo". Las preguntas son el producto: un video basado en suposiciones pierde su tiempo. La única excepción es una ejecución sin nadie que responda (una tarea programada o en segundo plano): entonces usa tu borrador del guion, las 4 funciones más visuales, 16:9 y solo música, y di al principio lo que asumiste.

Paso 4: Hacer que la app funcione

Sigue references/running-the-app.md. En resumen:

• Opción (a): instala con el comando detectado, inicia el servidor de desarrollo en segundo plano, espera el puerto. Si se necesitan variables de entorno y falta .env, enumera los nombres y pide al desarrollador que lo cree. Inicia las bases de datos con docker compose si está presente. Siembra datos demo con el script de siembra del repositorio (solo DB local). Haz que la app se vea usada: una app vacía da un mal demo.
• Dale a la opción (a) dos intentos honestos. Si aún así no arranca, explica el bloqueo en una o dos frases y cambia a la opción (b) o (c). No pierdas mucho tiempo en ello.
• Opción (c): los archivos del desarrollador van en public/assets/shots/; .png, .jpg, .mp4 y .webm funcionan.

Paso 5: Capturar

Escribe una lista de tomas shots/<app-slug>.json (formato: references/capture-guide.md, ejemplo: shots/example.json):

• device: desktop para 16:9/1:1/4:5. Para 9:16, usa mobile si la app es responsive (verifica primero una captura de móvil), de lo contrario desktop y confía en el zoom.
• Una toma por función elegida. Dale a cada una un selector focus: un elemento pequeño (una tarjeta, un botón, un gráfico), no una sección de página completa, para que la cámara tenga algo en lo que hacer zoom.
• Usa record: true para 1–2 flujos que se vean mejor en movimiento (escribir, crear, arrastrar). Mantén cada uno por debajo de ~8 s de acciones.
• setup contiene los pasos de inicio de sesión con la cuenta de prueba; hide contiene selectores para texto sensible.

node scripts/capture.mjs shots/<app-slug>.json

Abre cada PNG y míralo. Vuelve a capturar (--only <shot>) si ves: estados vacíos, spinners de carga, toasts de error, superposiciones de modo desarrollo (por ejemplo, la insignia de error de Next.js), banners de cookies, "lorem ipsum", o cualquier cosa personal que no esté difuminada. El manifiesto (public/assets/shots/manifest.json) proporciona la imagen, el video, el tamaño, la duración del clip y el cuadro de enfoque de cada toma para el brief.

Paso 6: Storyboard → aprobación

Lee references/pitch-and-story.md. Estructura predeterminada:

gancho → (problema) → introducción "Conoce a " → 3–5 escenas de funciones → por qué destaca (beneficios) → (montaje) → CTA

Duración: 30–60 s horizontal, 20–40 s vertical. Muestra el storyboard como una lista numerada corta (escena, texto en pantalla, qué toma y la línea hablada si eligieron locución) y obtén un sí antes de renderizar, a menos que el desarrollador haya dicho que sigas adelante.

Paso 7: Brief, vista previa, renderizado

Escribe briefs/<app-slug>.json (referencia: references/brief-schema.md). Copia media, video, width, height, focus y clipSeconds del manifiesto. Usa speed: 1.3–1.8 en clips que se sientan lentos. En horizontal, alterna "flip": true en cada dos funciones para que la pantalla cambie de lado.

Si eligieron la locución con IA, agrega una línea "say" a cada escena que deba ser hablada (reglas en references/voiceover.md), establece "audio": {"voice": {"name": "norman"}} (o "cori"), luego genérala. Cada escena se estira automáticamente para ajustarse a su línea, la música baja bajo la voz y se agregan subtítulos:

python3 -m venv .venv && .venv/bin/pip install sherpa-onnx numpy    # una vez (Windows: .venv\Scripts\pip)
.venv/bin/python scripts/voiceover.py briefs/<app-slug>.json        # vuelve a ejecutar después de editar cualquier línea "say"

Luego, vista previa:

scripts/render.sh briefs/<app-slug>.json stills    # un fotograma por escena, ~1 min

Abre cada still. Verifica: el texto no se superpone con el chip de marca, los subtítulos o entre sí, nada cortado, pantalla legible, el zoom aterriza en el elemento correcto, texto de leyenda correcto. Corrige, vuelve a ejecutar stills, luego:

scripts/render.sh briefs/<app-slug>.json           # MP4 completo, unos minutos

Paso 8: Entregar y limpiar

• Entrega al desarrollador el MP4 con una línea sobre lo que contiene. Ofrece un siguiente paso: la otra orientación (volver a capturar con el otro device, mismo brief con un nuevo format), un teaser de 15 s (gancho + 2 funciones + CTA), o agregar/eliminar la locución (si tenían solo música, menciona que una locución gratuita está a un comando de distancia).
• Detén el servidor de desarrollo y cualquier contenedor que hayas iniciado. Informa al desarrollador qué datos de prueba o cuentas de prueba creaste, y pregunta antes de eliminar algo.

Audio

Los efectos de sonido se reproducen en cambios de escena, clics y pops; deshabilítalos con "audio": {"sfx": false}. Un ritmo libre de regalías suena por defecto; usa la propia pista del desarrollador con "music": "assets/track.mp3" o false para ninguno. Nunca uses música con derechos de autor que el desarrollador no posea o tenga licencia.

Elegir el audio (qué recomendar)

Situación	Recomendar
Reel / short 9:16, menos de 30 s	Música + efectos de sonido. La mayoría ve en silencio; el texto en pantalla lo sustenta.
Recorrido 16:9, 30–60 s+ (YouTube, página de destino, Product Hunt)	Locución con IA. La narración explica las funciones mejor que el texto solo.
Marca liderada por el fundador, audiencia personal	Su propia voz grabada (suena más auténtica).
Desarrollador inseguro	Envía las dos muestras de voz y una versión solo música siempre es la alternativa.

Sé sincero de que las voces gratuitas son claras pero ligeramente sintéticas. No son tan naturales como los servicios de voz de pago o una persona real. Obtén muestras con .venv/bin/python scripts/voiceover.py --samples (escribe out/voice-sample-norman.wav y out/voice-sample-cori.wav) y envíalas para que el desarrollador pueda juzgar.

Licencias

Remotion (el motor de video) es gratuito para individuos, empresas con hasta 3 empleados y organizaciones sin fines de lucro. Las empresas con fines de lucro más grandes necesitan una Licencia de Empresa Remotion (remotion.dev/license). Menciónalo una vez si el desarrollador parece ser de una empresa grande. Las fuentes incluidas son SIL OFL. Las dos voces (Norman, Cori) fueron entrenadas desde cero con audio de LibriVox de dominio público y tienen licencia MIT, por lo que son aptas para videos comerciales. No las cambies por otras voces de Piper: muchas (Lessac, Ryan, Amy y voces ajustadas a partir de Lessac) son no comerciales o legalmente poco claras. El motor de voz, sherpa-onnx, es Apache 2.0.

Cuando algo sale mal

Consulta references/troubleshooting.md.