promo-video (creación de vídeos promocionales)

promo-video

Monta vídeos promocionales cortos a partir de clips sin editar. Vertical, cuadrado o apaisado. Introducción/cierre opcionales renderizados con Blender, música opcional generada por IA.

La habilidad es independiente del agente anfitrión: DEBE funcionar de manera idéntica en cada runtime que implemente el estándar Agent Skills (https://agentskills.io) — Claude, Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, Cline, OpenCode, OpenHands, Goose, Kiro, Junie, y otros. Nunca dependas de herramientas específicas del anfitrión (sin AskUserQuestion, sin comandos slash, sin MCP a menos que esté explícitamente disponible). Realiza toda la interacción con el usuario como mensajes de chat normales.

Cuándo usar

• "Corta estos clips juntos en un reel de 30 segundos."
• "Crea un vídeo promocional de hackathon en vertical."
• "Tengo una carpeta de vídeos de teléfono — haz un clip social de 1080x1920 con música."
• "Genera un promo con logo de introducción + corazón de cierre + pista de fondo."
• El usuario menciona un directorio de archivos .mov/.mp4 y quiere un entregable.

Requisitos previos

• ffmpeg en PATH, compilado con libx264, aac y prores_ks (el último solo se necesita para MOVs con canal alfa de introducción/cierre).
• Python 3.9+.
• Instala las dependencias de Python una vez: pip install -r requirements.txt desde dentro del directorio de la habilidad.
• Opcional: un archivo .env en la raíz del proyecto que contenga SUNO_API_KEY para habilitar la generación de música. La habilidad detecta automáticamente si la clave está configurada y solo ofrece generación de música si lo está.
• Opcional: Blender MCP disponible en el agente anfitrión para producir renders de introducción/cierre. Consulta references/blender_mcp.md.

Flujo predeterminado (basado en diálogo)

Paso 0 — Detectar si los clips han cambiado desde la última ejecución

Antes de hacer cualquier pregunta, verifica si el usuario retoma una sesión anterior. Si existe gallery/.clips_snapshot.json (o si el usuario te indica una carpeta de clips que se usó antes), ejecuta:

python scripts/clip_diff.py <clips_dir>

• Código de salida 0 — la carpeta de clips coincide con la última instantánea. Continúa.
• Código de salida 1 — desviación. El informe lista los clips nuevos / eliminados / modificados. Muéstralo al usuario, luego ofrécele volver a ejecutar scripts/gallery.py para que la galería recoja los clips nuevos. Las selecciones existentes para clips que aún están presentes se conservan intactas.
• Código de salida 2 — no hay instantánea aún. Primera ejecución normal, continúa.

NO omitas este paso al retomar un proyecto existente — trabajar en silencio con una galería/selection.json desactualizada es el clásico error "¿dónde están mis clips nuevos?".

Preguntas

Al inicio, haz al usuario las siguientes preguntas, en orden. Acepta respuestas naturales; no presentes una interfaz de opción múltiple a menos que el anfitrión la soporte. Para cada pregunta, también acepta "tú decides" y aplica la opción predeterminada sensata.

1. Formato objetivo. 1080x1920 vertical (predeterminado), 1920x1080 apaisado o 1080x1080 cuadrado. Tamaños personalizados permitidos.
2. Origen de los clips. Ruta absoluta o relativa a un directorio que contenga los clips sin editar. Se admiten .mov, .mp4, .m4v.
3. Duración objetivo en segundos. (Típico: 20–45 s.)
4. Música. Una de: (a) archivo de audio existente, (b) generar mediante Suno (solo ofrecer si SUNO_API_KEY está configurada), (c) sin música.
5. Introducción. Una de: ninguna, imagen estática (ruta), generada con Blender MCP.
6. Cierre. Las mismas opciones que introducción.
7. Modo director. Sí o no. Si es sí, sigue references/director_mode.md en lugar de continuar linealmente aquí.

Luego maneja la selección de clips. Ofrece dos vías:

A) Galería visual (recomendada para más de 10 clips o cuando el usuario quiere ver fotogramas antes de elegir señales). Ejecuta scripts/gallery.py <clips_dir> --resolution WxH --fps 30 --target-length N — genera gallery/gallery.html con miniaturas, controles deslizantes IN/OUT, control de velocidad y vista previa del rango. Dile al usuario que lo abra en un navegador, seleccione clips, configure señales y luego haga clic en "Exportar selection.json". El archivo descargado está listo para build.py.

B) Diálogo inline (adecuado para lotes pequeños o cuando no hay navegador disponible). Revisa cada clip tú mismo:

• cue_in y cue_out en segundos (rango de recorte)
• speed multiplicador (1.0 = original)
• fixed: true si el tiempo/velocidad está curado manualmente, false para rellenos libres (predeterminado: 0,6 s desde el centro, velocidad 1.0)

Ofrece "Solo dame los valores predeterminados" — selecciona cada clip alfabéticamente, valores predeterminados libres, hasta la duración objetivo.

De cualquier manera, el resultado es un selection.json que coincide con templates/selection.schema.json. Valida antes de continuar.

Construcción

Una vez que selection.json es válido, ejecuta:

python <skill>/scripts/build.py <selection.json> --out output/<name>.mp4

build.py escribe artefactos intermedios en build/ (relativo al directorio de trabajo actual): build/normalized/, build/trimmed/, build/montage.mp4, build/composed.mp4. Elimina build/ para forzar un renderizado completo.

Cada submódulo en scripts/ también se puede ejecutar de forma independiente — útil para iterar en un paso sin reconstruir todo el proceso. Cada uno acepta un argumento --help.

Modo director (opcional)

Opt-in. Consulta references/director_mode.md para las instrucciones de los roles. La habilidad crea cuatro roles secuenciales — Narrador → Editor → Compositor → Supervisor — que comparten selection.json como estado. Cada rol lee el JSON actual y escribe sus actualizaciones. Úsalo cuando el usuario solicite "un proceso más guiado" o "guíame como un productor".

Generación de música (opcional)

Si el usuario eligió "generar mediante Suno", delega el paso de música al sub-agente Song-Builder definido en references/song_builder_agent.md. Ese sub-agente:

1. Pregunta al usuario por género, estado de ánimo, rango de BPM, estructura de secciones, activación/desactivación instrumental y toma la duración del vídeo.
2. Formula un prompt de Suno + etiquetas de estilo.
3. Llama a scripts/music.generate_song(spec) — proporciona takes > 1 si el usuario quiere opciones para comparar.
4. Recorta y funde la toma elegida a la duración del vídeo.
5. Escribe la ruta final del mp3 en selection.json como audio.

Si el anfitrión proporciona un mecanismo de sub-agente (por ejemplo, la herramienta Agent de Claude Code), úasalo. De lo contrario, desempeña el rol inline en el mismo hilo.

Integración con Blender MCP (opcional)

Solo asistencia — esta habilidad no incluye una escena de Blender.

Si el usuario quiere una introducción o cierre renderizados con Blender, delega en el sub-agente Blender-Builder definido en references/blender_builder_agent.md. Este gestiona todo el flujo: verificación previa (comprobar que Blender + MCP sean realmente accesibles en este anfitrión), entrevista de diseño (dirección visual, colores, duración), construcción de la escena, vista previa iterativa, renderizado a MOV ProRes 4444 con canal alfa y entrega de la ruta del MOV en selection.json.

Si el anfitrión proporciona un mecanismo de sub-agente (por ejemplo, la herramienta Agent de Claude Code), inícialo. De lo contrario, desempeña el rol inline. El flujo de diálogo principal debe invocar al Blender-Builder cada vez que el usuario eligió "generado con Blender MCP" para introducción o cierre en el paso 5 del cuestionario.

La documentación de configuración (instalar Blender, instalar el servidor MCP, registrarlo con el anfitrión) se encuentra en references/blender_mcp.md. El sub-agente Blender-Builder la consulta cuando el usuario necesita configurar el stack por primera vez.

Recuperación de errores

• Si un clip falla en la normalización (caso extremo de códec/resolución), build.py sale con un código distinto de cero y un mensaje de stderr claro que señala el archivo problemático. Pregunta al usuario si desea omitir el clip o investigar.
• Si Suno devuelve un 4xx o se agota el tiempo, ofrece al usuario reintentar, cambiar a "archivo existente" o continuar sin música.
• Nunca omitas clips en silencio. Nunca sobrescribas un archivo de salida existente sin confirmación a menos que se pase --force.

Notas de estilo para esta habilidad

• Nunca asumas herramientas específicas del anfitrión. Todo el diálogo es chat simple.
• Muestra tu trabajo. Al recortar, informa al usuario qué puntos de señal decidiste antes de construir.
• Falla con claridad. Si falta ffmpeg, dilo y muestra el comando de instalación para la plataforma del usuario.