hup-dev/promo-animation-skill

Animación de Producto

Estás produciendo una animación MP4 finalizada para el producto del repositorio actual. La habilidad es un motor de animación determinista + metodología, no un formato fijo: tú decides el patrón que se ajusta a lo que el usuario pidió (demo tipo chat, intro de marca, revelación de estadísticas, recorrido de flujo de trabajo, antes/después, etc.).

Lo que se mantiene constante en cada patrón:

• Activos reales de marca extraídos del repositorio (logo SVG, tokens de diseño, tipografía).
• Pulido visual de nivel Linear/Vercel/Stripe (sombras suaves, tipografía real, un solo momento heroico).
• Línea de tiempo determinista __setTime(t) para que Playwright capture fotogramas perfectos en cada renderizado.
• Contenido específico y con nombre dondequiera que la animación haga una afirmación — sin texto genérico como "La IA ahorra dinero".

La referencia completa de cómo funciona esto está en methodology.md — léelo antes de hacer cualquier otra cosa. Detalles concretos sobre estilo visual, temporización, matemáticas de cámara, flags de ffmpeg y los 10 errores que afectan los primeros intentos.

Objetivo de salida

Por defecto: 1920×1080 a 30fps, H.264 con música opcional + fundido de 1s al final. La duración depende del patrón:

• Intro de marca / revelación de logo: 5–8s
• Revelación de estadística: 6–10s
• Promo de producto (tipo chat u otro): 15–22s
• Recorrido de flujo de trabajo: 20–40s

Confirma la duración y la relación de aspecto con el usuario si no las especificó. Usa 16:9 1920×1080 por defecto, a menos que pida formato social/vertical.

Cuando tengan sentido dos cortes (por ejemplo, cámara estática + cámara cinematográfica), entrega ambos.

Verificación previa

Antes de hacer nada, confirma que el entorno puede hacer esto:

which ffmpeg && ffmpeg -version | head -1
which node && node --version
ls ~/Library/Caches/ms-playwright/ 2>/dev/null | head -3   # caché de playwright en macOS

Si Playwright chromium no está en caché, ejecuta npx playwright install chromium. ffmpeg es obligatorio.

Crea el espacio de trabajo:

mkdir -p product-animation/frames
cd product-animation

El pipeline de 4 fases

Ejecuta las fases 1 a 3 en paralelo como subagentes (trabajo independiente) antes de comenzar la fase 4.

Fase 1 — Descubrimiento de marca y activos (subagente)

Ejecuta el extractor de marca con el prompt en agents/01-brand-extractor.md. Pásale:

• La ruta raíz del repositorio
• Algunas pistas sobre lo que hace el producto

Devuelve un JSON con: ruta real del logo SVG, tokens hex exactos, pila de tipografía, convenciones de UI heroicas (border-radius, padding, estilo del botón principal), nombre del producto + eslogan.

Copia el wordmark SVG real en el espacio de trabajo (por ejemplo, <product>-wordmark.svg). Activos de marca en línea, sin ráster.

Fase 2 — Concepto + guion (subagente)

Ejecuta el escritor de guiones con el prompt en agents/02-script-writer.md. Pásale el resumen de marca de la fase 1, lo que hace el producto y el tipo de animación que pidió el usuario (promo, intro de marca, revelación de estadísticas, etc.).

Devuelve:

• Patrón de animación seleccionado para este producto (ej. "chat-demo", "stat-reveal", "brand-intro")
• Storyboard con tiempos de escena: apertura en frío → contenido principal → outro
• El texto/números/visuales exactos a destacar en cada escena

Si el patrón es chat-demo, la plantilla en templates/chat-demo.html es un punto de partida completo funcional: llena la estructura de datos CASES.BIGGEST con el contenido del guion. Para otros patrones, construye el HTML desde cero usando el motor de animación descrito en methodology.md § 2 — el mismo controlador __setTime(t), el mismo conjunto de herramientas de easing, la misma captura de Playwright.

Fase 3 — Investigación de contenido (subagente)

Ejecuta el investigador de casos con el prompt en agents/03-case-researcher.md. Pásale el dominio del producto y el patrón de animación.

Lo que devuelve depende del patrón:

• Demo tipo chat / promo: UN caso canónico, con nombre, dramático antes/después con números reales (el "momento Converse Chuck Taylor" para el dominio) + 3-4 casos secundarios.
• Revelación de estadística: UNA métrica pública grande que el producto pueda poseer de forma creíble, con una cita.
• Intro de marca / revelación de logo: el titular real de la empresa, número real de clientes, historia real de lanzamiento — cualquier cosa verificable para poner en pantalla.
• Recorrido de flujo de trabajo: el recorrido de usuario real más común, pasos nombrados del propio producto.

Específico, con nombre, verificable dondequiera que la animación haga una afirmación.

Fase 4 — Construcción y renderizado

Combina las salidas en la plantilla HTML elegida (o una que hayas escrito desde cero), renderiza los fotogramas con Playwright, codifica con ffmpeg.

Fase de construcción

La construcción varía ligeramente según el patrón. La forma compartida:

1. Copia o escribe el HTML de la animación.

   • Si el escritor de guiones eligió chat-demo, copia templates/chat-demo.html en el espacio de trabajo y edita el objeto de datos CASES.BIGGEST con el contenido del guion de la fase 2 + la investigación de la fase 3. También intercambia los :root { --tokens } de la marca, el texto del encabezado ("Atlas Trade", "Intelligence", distintivo), la barra de URL, la <img src> del wordmark, y el eslogan + CTA del logo de salida.
   • Para otros patrones (intro de marca, revelación de estadística, recorrido, antes/después), escribe el HTML desde cero usando el motor de animación — methodology.md § 2 muestra el patrón de línea de tiempo determinista. Reutiliza las reglas de diseño de reference/design-rules.md, las matemáticas de cámara de reference/camera-modes.md y el mismo contrato de renderizado de Playwright.

2. Copia un script de renderizado. Para chat-demo usa templates/render-chat-demo.js (525 fotogramas, ~17.5s) o render-chat-demo-zoom.js (585 fotogramas, ~19.5s, cámara cinematográfica). Para patrones personalizados, copia uno de los scripts de renderizado y actualiza la constante DURATION — el resto funciona tal cual.

3. Verifica primero en el navegador. Abre el HTML directamente — la animación se reproduce automáticamente en bucle. Échale un ojo a cada escena. 5 minutos en un navegador ahorran 3 minutos de renderizado por iteración.

4. Renderizado de prueba — 6–8 fotogramas clave en los límites de las escenas antes de comprometerte con el renderizado completo. Consulta scripts/smoke.js para el patrón. Detecta superposición de diseño, falla de tipografía, elementos fuera de pantalla en 30s.

Fase de renderizado

Instala Playwright en el espacio de trabajo:

npm install [email protected] --no-save --no-audit --no-fund --silent

Renderiza los fotogramas:

node render-<pattern>.js          # escribe frames/f_*.png  (~3-5 fotogramas por segundo de duración × FPS)

Codifica con ffmpeg. Ajusta -t a la duración de tu animación y afade=t=out:st=X para que el fundido termine 1s antes del final:

ffmpeg -y -framerate 30 -i frames/f_%05d.png \
  -i /path/to/music.mp3 \
  -c:v libx264 -pix_fmt yuv420p -crf 18 -preset medium -movflags +faststart \
  -c:a aac -b:a 192k -af "afade=t=out:st=<DURATION-1>:d=1.0" \
  -t <DURATION> -shortest animation.mp4

yuv420p es necesario para la reproducción en Slack/LinkedIn/Twitter. +faststart permite la transmisión. crf 18 es casi sin pérdida visual.

Si no se proporciona audio, elimina -i music.mp3, -c:a aac -b:a 192k, y los flags -af. scripts/encode.sh encapsula esto con valores predeterminados sensatos.

Control de calidad — léelo antes de declarar terminado

Universal (cada patrón):

• Wordmark real de la marca en línea (SVG <img>, no Inter Tight bold con estilo de logo).
• Todos los colores provienen de los tokens del producto — nunca hex inventado.
• La animación está referenciada desde el repositorio — su UI, tipografía, modismos de copia reconocibles.
• Un solo momento heroico. Un número, una revelación, un CTA — no 12 puntos focales en competencia.
• Cualquier número que cuente usa tabular-nums (no tiembla horizontalmente).
• Las animaciones aterrizan — ningún elemento aparece exactamente en el mismo instante en que otro se desvanece; respeta las ventanas de entrada/salida.
• El logo se mantiene el tiempo suficiente al final (≥ 3s para outros con marca).
• El MP4 se reproduce en QuickTime, exactamente la resolución objetivo × fps, tamaño de archivo razonable (1–6 MB típico).
• Abre el MP4 con open <nombre>.mp4 para el usuario.

Para chat-demo específicamente, verificaciones adicionales (consulta reference/design-rules.md):

• El número heroico $ está en JetBrains Mono / peso 800 / 6 dígitos o más.
• La cadena de herramientas tiene ~8 chips, ritmo ~3s — cualquier cosa más corta parece falsa.
• La burbuja del usuario aparece DESPUÉS de que la barra se despeje, nunca simultáneamente.
• La burbuja de pensamiento se desliza hacia arriba y sale antes de que el resultado aparezca — nunca ambos opacos.
• El cursor solo aparece durante la escritura, nunca en el marcador de posición.

Limpia antes de declarar terminado:

rm -rf frames frames-zoom node_modules package.json package-lock.json smoke_*.png

El espacio de trabajo final debe contener: el HTML, el/los script(s) de renderizado, el wordmark SVG y el/los MP4(s) terminados.

Mapa de archivos

~/.claude/skills/promo-animation/
├── SKILL.md                  ← estás aquí
├── methodology.md            ← referencia detallada, LÉELO PRIMERO — el motor de animación universal
├── agents/
│   ├── 01-brand-extractor.md   ← prompt del subagente de fase 1
│   ├── 02-script-writer.md     ← prompt del subagente de fase 2
│   └── 03-case-researcher.md   ← prompt del subagente de fase 3
├── templates/
│   ├── chat-demo.html              ← patrón canónico de chat-demo (ejemplo funcional)
│   ├── render-chat-demo.js         ← renderizador Playwright en modo estático
│   ├── render-chat-demo-zoom.js    ← renderizador en modo zoom
│   └── atlas-wordmark.svg          ← SVG de marcador de posición
├── scripts/
│   ├── smoke.js                ← prueba rápida de fotogramas clave
│   └── encode.sh               ← envoltorio de ffmpeg
└── reference/
    ├── design-rules.md         ← reglas visuales resumidas
    ├── camera-modes.md         ← decisión entre modo estático y zoom
    └── timing-blueprint.md     ← temporizaciones de escena

Ante la duda, lee templates/chat-demo.html — es un ejemplo funcional completo que puedes renderizar ahora mismo (un escenario ficticio de reclasificación "Atlas Trade" / Converse Chuck Taylor). Es la referencia canónica para el patrón de chat-demo Y para el motor de animación determinista: cada regla visual, decisión de temporización y error en methodology.md está codificado en ese archivo.

Para otros patrones de animación, escribes el HTML desde cero — pero el motor de animación (§ 2 de methodology.md), el contrato de renderizado (§ 5) y las reglas de diseño (reference/design-rules.md) se transfieren sin cambios.