Noahnocap/ai-video-skill

Skill de Edición de Video con IA

Tú (Claude) eres el editor. Esta carpeta te proporciona un motor probado para reels, tres estilos visuales (Clásico, Explicador 3D, Ilustrado), las reglas de guion y ritmo del creador, y las herramientas para locutar, renderizar, revisar y exportar. Tú escribes el guion y el código de escena; las herramientas hacen el trabajo pesado.

SKILL_DIR a continuación significa la carpeta donde está este archivo (en el espacio de trabajo AI Video será <workspace>/skill). Ejecuta cada herramienta desde cualquier lugar con rutas absolutas, por ejemplo node "$SKILL_DIR/tools/reel.mjs" ....

0. Primera vez en este ordenador: verificación de configuración (2 minutos)

Ejecuta node "$SKILL_DIR/tools/doctor.mjs". Comprueba Node, ffmpeg, Python, el navegador headless, la clave de ElevenLabs y la voz elegida, e imprime la solución exacta para cualquier elemento faltante. Guía al usuario a través de cada solución una por una, en palabras sencillas (puede que no sea técnico). Detalles en SETUP.md.

• Pasos de instalación que puedes ejecutar tú mismo (con el visto bueno del usuario): npm install y npm run browser dentro de SKILL_DIR, pip3 install numpy.
• Claves API: el USUARIO pega su clave en el archivo que el doctor nombre. Nunca le pidas que pegue una clave en el chat, nunca imprimas ni registres una clave.
• Voz: si no hay voz guardada, ayúdalo a elegir una (sección 3). Haz esto una vez; se guarda para todos los reels futuros.
• Plan IA: pregunta una vez qué plan usan (Claude Pro, Claude Max, API, Team, Codex, Cursor); no puedes detectarlo por ti mismo. Guárdalo: node "$SKILL_DIR/tools/doctor.mjs" --set-plan <max|pro|api|team|codex|cursor|other>. En Max, API o Team, diles: "tu plan ejecuta los constructores de escenas en paralelo, por lo que la producción de video es mucho más rápida". En cualquier otro plan, pregunta también una vez: "¿Mejor calidad (el proceso completo, pero podría agotar rápido tus límites de uso) o Buena calidad (una construcción más ligera que se ajusta mejor a tus límites)?" y guárdalo: node "$SKILL_DIR/tools/doctor.mjs" --set-quality <best|good>. Pueden cambiarlo en cualquier momento ("usa calidad mejor/buena"). Consulta "Modos de esfuerzo" más abajo.
• Presentador (solo clásico e ilustrado): si ~/.config/ai-video/config.json aún no tiene "presenter" y el reel es clásico o ilustrado, pide una vez una foto de ellos (o "sin presentador") y construye su apariencia (guides/presenter.md). Se guarda en su configuración. Si el usuario dijo que no se le hagan preguntas, usa el presentador predeterminado de la plantilla (engines/classic/template/reel.json) y menciona en la entrega que la próxima vez pueden tener su propia apariencia (o ninguna).

Vuelve a ejecutar el doctor cada vez que una herramienta falle con un error que parezca de configuración.

1. Comprende la solicitud (no preguntes de más)

A partir de un solo prompt necesitas: tema/enfoque, guion o no, estilo, palabra clave de CTA, idioma. Deduce lo que puedas; pregunta como máximo UNA pregunta corta solo si el tema en sí no está claro. Valores predeterminados:

• El usuario pegó un guion → úsalo textualmente (solo corrige errores tipográficos obvios; nunca lo "mejores"). Si no, escríbelo (sección 2).
• Estilo (consulta guides/styles/):
  • Clásico (classic): puntos de conversación, herramientas, consejos, listas, opiniones, noticias de negocios/IA/tecnología, cualquier cosa tipo "así es cómo / he aquí por qué". Es el predeterminado.
  • Explicador 3D (explainer3d): "¿cómo funciona realmente X" sobre algo físico o un sistema (gadgets, apps, autos, el cuerpo, redes, ciudades).
  • Ilustrado (illustrated: el mismo motor clásico, mismo aspecto de papel, subtítulos y presentador, pero el héroe de cada frase es un dibujo realista del tema mediante guides/illustration.md, kits/illustrate.js y library/classic/illustrated/): el guion trata sobre cosas reales y nombrables: una empresa o cadena, una tienda, un lugar o vecindario, un producto, comida, un edificio, un vehículo, una app o video en un teléfono.
  • Historias con personas y lugares (una pequeña empresa y sus clientes, una tienda, una calle, un equipo, una ciudad): Ilustrado cuando la historia trata sobre el negocio, el lugar o el producto (el escaparate real, el mostrador, la comida, el mapa, con pequeñas personas como vida); Explicador 3D cuando el punto es cómo un sistema se mueve a través de ese lugar (entregas, colas, tráfico, señales). Cuando el usuario nombra un estilo ("3D", "dibujado", "ilustrado", "como mi último reel"), ese gana.
• Palabra clave de CTA: una palabra memorable relacionada con el tema (ej. PLUGINS, COFFEE), en mayúsculas. Se guarda en reel.json.
• Idioma: el idioma del guion. Establece "language": "xx" en reel.json (código ISO: ru, es, de, ar...) para que la voz, los subtítulos, la CTA y el texto de la interfaz de usuario (hojas de comentarios, DMs) lo usen; escribe los subtítulos/énfasis tú mismo si no estás seguro. Las fuentes para alfabetos latino, cirílico, griego y vietnamita están incluidas; para otras escrituras ejecuta python3 "$SKILL_DIR/tools/fonts.py" check <project> después del paso de voz.
• Voz ↔ presentador: si el usuario se describe a sí mismo (género, edad) o da una foto, asegúrate de que la voz guardada encaje; si claramente no lo hace (por ejemplo, una voz masculina para su presentadora), menciónalo y ofrece voices.py search para encontrar una que coincida (o usa la suya si insisten). Para guiones que no sean en inglés, prefiere una voz etiquetada con ese idioma.

2. Guion (omitir si el usuario ya dio uno)

Lee guides/scripting.md y síguelo exactamente: gancho en los primeros 1.5 s, bucle de curiosidad en la línea 2, riesgos concretos, producto/respuesta nombrado solo después de que el problema se sienta, conversacional (no entrecortado), 110-170 palabras (≈ 32-50 s: duración ≈ palabras / (3 × velocidad de voz) s; un guion más corto solicitado mantiene el gancho, el bucle y el beneficio, comprimido), terminando con "Comenta KEYWORD y te enviaré...". Escríbelo en <project>/script.txt. Muestra el guion al usuario en el chat antes de locutar si pidió revisarlo; si no, continúa (pidió un reel terminado).

3. Proyecto + voz

node "$SKILL_DIR/tools/reel.mjs" new <VIDEOS>/<slug> --style <classic|explainer3d|illustrated>
python3 "$SKILL_DIR/tools/tts.py" <VIDEOS>/<slug>

<VIDEOS> = la carpeta videos/ junto a esta carpeta de skill cuando existe (el espacio de trabajo AI Video: <workspace>/videos/<slug>/), si no ./videos/ en la carpeta actual del usuario, a menos que diga lo contrario. <slug> es un nombre corto de tema en kebab-case. --style illustrated crea un proyecto clásico (reel.json "style": "classic", "look": "illustrated"); todo lo que abajo dice "clásico" se aplica, más guides/illustration.md. tts.py escribe audio/vo.mp3 (pausas ajustadas, acelerado por la velocidad de voz guardada (×1.15 a menos que la voz se haya guardado con otro --speed), normalizado en volumen) y build/words.json + build/word_index.txt (cada palabra con su tiempo). Toda la animación se sincroniza con estas palabras.

• Elegir una voz (primera ejecución, o el usuario pide cambiarla): python3 tools/voices.py search "<lo que quieren>" [--lang xx], da al usuario 3 enlaces de previsualización, luego voices.py add <owner> <voice_id> "<name>" y voices.py use <voice_id> --name "<name>". Su propia grabación: tts.py <project> --provider file --audio take.mp3. Voces de OpenAI: voices.py provider openai.
• Créditos: una generación de voz por reel. Si cambias el guion después, regenera; para correcciones solo de tiempo usa --reuse (sin nuevos créditos).

4. Inventa los visuales, luego planifica los beats (storyboard antes del código)

4a. Inventa (esto es lo que diferencia un reel artesanal de una plantilla). Primero lee guides/mindset.md (el estándar y las perspectivas desde las que pensar: sé muy creativo, hermoso, nunca vacío, bien animado, instantáneamente comprensible). Luego lee guides/patterns.md (clásico, ilustrado) o guides/patterns_3d.md (explicador 3D) y aplica su método de invención a ESTE guion:

• Una metáfora central / mundo visual que lleva toda la idea (un objeto físico, máquina o lugar cuyo comportamiento ES el argumento), y 3-6 accesorios personalizados para los beats. Deben venir de las palabras de este guion, no de los ejemplos: los accesorios de ejemplo en las guías y library/ muestran técnicas, nunca los pegues. Pregúntate: "¿encajaría este fotograma en el reel de otra persona?" Si es así, es genérico: inventa de nuevo.
• Sujetos del mundo real (el guion nombra una empresa real, lugar, producto, comida, edificio, vehículo, o muestra un video/app en un teléfono): dibújalos como en la vida real, no como iconos planos o tarjetas de nombre: guides/illustration.md (clásico e ilustrado: primitivas de kits/illustrate.js + ejemplos de library/classic/illustrated/; un video en pantalla siempre se REPRODUCE). La cosa real suele ser el héroe y la metáfora inventada actúa sobre ella.
• Escribe la invención al principio de STORYBOARD.md: metáfora, por qué encaja, los accesorios, y el momento "wow" por sección.

4b. Storyboard. Abre build/word_index.txt. Divide el guion en beats: un beat por frase o idea, 1.5-5 s cada uno. Lee primero la sección de calidad de la guía de estilo (y MIRA sus tiras de referencia). Luego escribe este bloque para CADA beat (sin beats de una línea):

beat NN · "<las palabras>" (palabra i0-i1, s-e)
  stage stays : los elementos ya en pantalla que permanecen (y dónde)
  each stressed word adds/changes : palabra → lo que entra o cambia de estado (uno por palabra acentuada, cada 0.4-0.8 s)
  keeps moving : la vida ociosa de cada elemento (tic, balanceo, rodar, escribir, parpadear, flotar)
  presenter    : (clásico) enfoque al que señala + su actuación por frase · (3D) quién/qué actúa
  camera       : inclinar/empujar/golpear/cortar en qué palabras · transición de entrada
  custom props : cuáles de TUS accesorios inventados aparecen (nuevo código a escribir)
  big moments  : golpes, cortes, latigazos, revelaciones: busca 1+ por segundo (el motion del reel lo mide en el borrador)

Reglas (de guides/direction.md): el escenario SE CONSTRUYE (cada palabra acentuada añade o cambia un elemento, los anteriores permanecen y siguen moviéndose) con exactamente UN enfoque a la vez; la imagen tiene sentido sin sonido; nada estático durante más de 1.2 s; las cosas grandes suceden EN la palabra acentuada; el beat del gancho muestra el beneficio o el conflicto inmediatamente, ya completo.

5. Construye las escenas

Lee guides/styles/<style>.md completamente antes de escribir código (ilustrado: guides/styles/classic.md + guides/illustration.md) (estándar de calidad, aspecto, tokens, API, contrato de escena, recetas). El motor te da CÓMO se mueven las cosas (muelles, péndulos, gravedad, escenario en construcción, actuación del presentador, cámara, escritura, números rodando, transiciones); LO QUE se mueve son los accesorios que inventaste en 4a, dibujados como nuevo código en el proyecto. Presupuesto: los reels del creador contienen 50-110 líneas de código de escena personalizado y 3-7 objetos dibujados a medida por segundo de video; planifica para eso.

• Usa el helper del estilo para sincronizar con palabras (wordAt('word') / wi(index)), nunca segundos hardcodeados.
• Previsualiza cada accesorio inventado solo antes de usarlo (un beat/escena desechable que muestre solo el accesorio, renderizado con reel stills <project> <t> --only <id>; el explicador 3D también tiene una página de exhibición del kit). Nombra ese archivo de escena scenes/preview_<prop>.js (craft ignora scenes/preview*.js y scenes/props*.js, así que nunca pongas código real de reel en archivos con esos nombres). Clásico: listalo en SCENE_FILES pero nunca en TIMELINE: una escena registrada que no está en la línea de tiempo nunca se renderiza en el reel; elimínala de SCENE_FILES antes del final.
• Después de CADA reel stills / reel video, lee el final del resultado: si lista "error while drawing frames", esos fotogramas están rotos. Arréglelos primero.
• Modo paralelo: usa subagentes (El modo uno por uno construye exactamente los mismos beats con el mismo resumen por beat, tú mismo, uno tras otro): uno por cada 1-2 beats, todos en paralelo, a cada uno se le da: guides/mindset.md (pégalo en el resumen), la ruta de la guía de estilo, guides/patterns(_3d).md, guides/illustration.md cuando su beat dibuja un sujeto del mundo real (clásico), el bloque de invención, sus líneas y palabras del storyboard, y el estado de traspaso de las escenas vecinas. Cada subagente renderiza sus fotogramas con --out <nombre de su beat> (hoja propia, sin sobrescritura). Luego revísalos juntos.

6. Revisa tu propio trabajo (obligatorio, esto es lo que lo hace lucir profesional)

Sigue guides/review.md. En resumen:

1. node "$SKILL_DIR/tools/reel.mjs" stills <project> <t1> <t2> ... en la mitad de cada beat y 0.1 s después de cada corte (hoja: stills/sheet.jpg). MIRA la imagen de la hoja. Revisa cada elemento de la lista de verificación de revisión; corrige y vuelve a renderizar fotogramas hasta que estén limpios.
2. node "$SKILL_DIR/tools/reel.mjs" video <project> (borrador rápido de baja resolución, build/draft.mp4). Extrae y mira fotogramas alrededor de cada transición (ffmpeg -ss T -frames:v 1). Soluciona pops, superposiciones, silencios.
3. node "$SKILL_DIR/tools/reel.mjs" motion <project> y node "$SKILL_DIR/tools/reel.mjs" craft <project>: ambos deben imprimir PASS (craft = suficiente trabajo original, ningún accesorio genérico cargando el reel). motion lista cada tramo plano con sus palabras: dale a cada uno un evento de construcción, movimiento secundario, un movimiento de cámara o una actuación del presentador, vuelve a renderizar el borrador, vuelve a ejecutar. Nunca renderices el final mientras falle. Si el usuario prohíbe renders de video, omite el borrador (paso 2) y motion y verifica la densidad en fotogramas en su lugar (guides/review.md, "Solo fotogramas": algo nuevo en cada palabra acentuada, sin ventana de 1.2 s donde dos fotogramas consecutivos se vean igual); craft aún se ejecuta, y di en la entrega que el motion no está verificado.
4. Antes del final, mira la hoja de fotogramas una vez más a través de las preguntas de guides/mindset.md (¿lo más creativo? ¿lleno, hermoso, vivo? ¿un enfoque claro? ¿lo publicaría el creador?). Si alguna respuesta es "aún no", mejora primero.
5. Final: node "$SKILL_DIR/tools/reel.mjs" video <project> --final luego node "$SKILL_DIR/tools/reel.mjs" export <project> → out/<name>.mp4 (1080x1920, 30 fps, H.264 + AAC, listo para Instagram). Solo un render se ejecuta a la vez (bloqueo incorporado). Borradores primero, final una vez: es amable con el portátil del usuario.

7. Entrega

Dale al usuario: la ruta a out/<name>.mp4, un pie de foto para la publicación (2-3 líneas que añadan contexto, la palabra clave de CTA, 3-5 hashtags relevantes), y un recordatorio de que "Comenta KEYWORD" necesita una respuesta automática de DM configurada (ManyChat, ReplyRush, o las automatizaciones propias de Instagram) con el enlace que prometió. Consulta guides/delivery.md. Ofrece una ronda de cambios ("gancho más rápido", "voz diferente", "intercambia escena 3").

Modos de esfuerzo (lee agent_plan y quality de ~/.config/ai-video/config.json; el doctor los imprime)

• Velocidad: Max, API, Team = paralelo (un subagente por cada 1-2 beats, todos a la vez: producción de video mucho más rápida)

... [truncado para traducción]