jjietay/clayducation

Video explicativo

Creas un video que ayuda al usuario a aprender un concepto. Tienes una gran ventaja sobre una herramienta nueva: conoces esta conversación y este proyecto. Usa ese conocimiento.

El motor está en ~/.claude/skills/clayducation/engine/. En este archivo, make significa:

node ~/.claude/skills/clayducation/engine/make.mjs <comando> <directorio-proyecto>

Paso 0: preguntar primero (cada vez que la habilidad comienza)

Ya sea que el usuario haya escrito /clayducation o haya pedido un video en palabras, lo primero que haces es hacer las preguntas a continuación con AskUserQuestion, con opciones seleccionables. Omite cada pregunta que el mensaje del usuario o esta conversación ya respondan (por ejemplo, "como un noticiero" responde al estilo, y "con música lo-fi" responde a la música). Coloca la opción recomendada primero y márcala "(Recomendado)". Haz las cuatro preguntas en una sola llamada (la herramienta acepta hasta 4). Si el tema en sí no está claro y no se omite ninguna pregunta, pregunta primero sobre el tema, en su propia llamada.

Pregunta	Encabezado	Opciones (primera = predeterminada)
¿Qué estilo debe usar el video?	Estilo	Arcilla 3D: un estilo suave de arcilla, con la mascota silenciosa haciendo el trabajo · 2D clásico, mixto: un estilo 2D diferente para cada parte · 2D clásico, un estilo: el usuario lo nombra (noticiero, pizarra, ...)
¿Para quién es el video y cuánto dura?	Espectador	Revisión de examen, estándar: la notación de la clase, números trabajados, trampas de examen, 5 a 6 min · Revisión de examen, profundo: lo mismo, 8 a 9 min, cada paso de la derivación · Principiante, corto: intuición primero, menos símbolos, 2 a 4 min · (Otro: el usuario nombra un espectador y una duración, por ejemplo "actualización para expertos, corto")
¿Cuándo debo consultarte?	Punto de control	Una vez: regresa con el video terminado · Después del guion gráfico: muestra el plan y espera aprobación · Después del primer estilo: muestra los primeros fotogramas y espera
¿Qué música?	Música	Tranquila (current): pad suave, sin ritmo · Lo-fi (lofi): ritmo ligero, más energía · Ninguna

Coloca una opción recomendada primero cuando la conversación sugiera una (un examen la próxima semana: Revisión de examen, profundo). Si el mensaje responde solo a la mitad de la pregunta del Espectador (por ejemplo "para mi examen"), mantén la pregunta y ofrece solo las opciones que concuerden con esa mitad. Los espectadores son revisión de examen, principiante y actualización para expertos (rápido y denso); las duraciones son corto (2 a 4 min), estándar (5 a 6 min) y profundo (8 a 9 min). Escribe las respuestas en video.json en el paso 4: "_look" (clay o classic), "_brief": { "viewer": ..., "length": ..., "checkpoint": ..., "style": ... } y "_render": { "music": "current" | "lofi" | false }. Cada paso posterior, y una reconstrucción, los lee allí y no vuelve a preguntar. Si el usuario descarta las preguntas, usa la primera opción de cada una.

Una vez, a menos que el usuario haya elegido un punto de control

Después del paso 0, haz cada paso a continuación sin detenerte, y regresa solo con el video terminado y verificado. No preguntes "¿debo continuar?", no muestres borradores, no esperes entre pasos. Cada verificación a continuación es tuya para ejecutar y actuar. Las únicas paradas son el punto de control que el usuario eligió: "Después del guion gráfico" se detiene después del paso 7 (muestra el guion gráfico y el veredicto del agente de guion, luego espera), y "Después del primer estilo" se detiene en el primer make look del paso 9 (muestra sus imágenes, luego espera).

El estilo que el usuario quiere (leer antes del paso 6)

Arcilla para cosas que actúan, Manim para gráficos, y la mascota está en cada video. Lee styles/clay.md. El usuario eligió el estilo de arcilla sobre la mezcla de estilos antigua para consistencia entre videos. Los estilos 2D son un estilo clásico opcional; consulta la sección a continuación.

• No fuerces un gráfico en arcilla (el usuario lo pidió). Cuando una imagen 2D de Manim ayuda al espectador a entender más que la arcilla (una curva, una distribución, un contorno, una proyección u otra geometría en un plano), haz esa parte una parte de Manim, sobre el fondo oscuro de Manim (styles/math-manim.md). Nunca construyas un modelo de arcilla que copie una curva matemática: el usuario hizo que esas se eliminaran. Los objetos que actúan, y el trabajo físico de la mascota, permanecen en arcilla. Un video puede ir de una parte de arcilla a una parte de Manim y viceversa, con el mismo color para la misma cosa.

• Un estilo, muchas partes. El video se divide en partes de aproximadamente 15 a 40 s (gancho, cada idea, tu caso, cierre). Cada parte tiene su propio fondo, cámara y escenario. Una al lado de la otra, dos partes nunca comparten un fondo.

• La mascota hace el trabajo. Es silencioso, sin sincronización de labios, y el narrador es una voz en off. Él camina, tira, empuja, carga y apaga cosas con sus propias manos, por lo que una fuerza en el guion es algo que el espectador lo ve hacer. El usuario pidió esto después de un video donde solo se paró y miró. Por defecto, se mantiene inexpresivo, y make check ADVIERTE cuando se queda en un solo lugar. Varía el trabajo: usa un ayudante de acción diferente en cada parte (carry, knock, press, grip, pointAt, pushOn; consulta "Usa una acción diferente" en styles/clay.md). El usuario lo encontró empujando en cada parte.

• Las cosas deben conectarse. Un resorte llega a su pared, un alfiler toca su mapa, una mano toca lo que sostiene. El usuario encontró un resorte que no llegaba a su pared después de que todas las verificaciones hubieran pasado. make bake mide cada unión en models.js (JOINS), así que agrega nuevas uniones allí, y busca contacto en las imágenes fijas.

• Solo nuestros propios modelos. Usa el kit en styles/library/clay. Nunca descargues un modelo. Si un video necesita un nuevo objeto, agrégalo al kit con el mismo estilo.

• Cada parte es una sola toma continua. Dentro de una parte no hay cortes ni nuevas diapositivas: los objetos llegan, se mueven y se unen mientras la voz habla, y la cámara se mueve lentamente. Una parte termina en el estado del que comienza la siguiente parte, o con un fundido en el fondo de la siguiente parte.

• La imagen explica; el texto solo nombra. El texto permanece plano y nítido, en HTML sobre el 3D. Por fotograma: un antetítulo (mayúsculas pequeñas, la parte y una fuente), un título de máximo 8 palabras, algunas etiquetas de 1 a 4 palabras cada una con líneas guía delgadas, y como máximo una línea de leyenda en la parte inferior. Nunca una columna de oraciones, nunca una lista con viñetas, nunca una leyenda de lo que significan los colores. Máximo alrededor de 15 palabras en pantalla.

• Las fórmulas actúan la voz (el usuario pidió esto). Una fórmula fija no es mejor que leer notas. Construye cada una con eqn(): los términos llegan mientras se dicen, se mueven cuando la voz los mueve, golpean y estallan cuando dice cancelar, y rebotan solo cuando nombra algo importante. make look da una falla para una fórmula que se queda quieta, y para una oración de "cancela" sin cancelación en pantalla. Consulta styles/clay.md.

• Movimiento físico. Las cosas se mueven como objetos: un brazo alcanza, una pelota cae y rebota, un bloque cae y se asienta, un pulso viaja. Sin acumulación de cajas estáticas.

• El mismo objeto mantiene su color en cada video (el robot siempre es naranja, el mapa siempre amarillo).

Si un guion gráfico rompe uno de estos, cambia el guion gráfico antes de escribir código.

Reglas estrictas

• Paralelo por defecto (el usuario lo pidió, 2026-11-09). Todo lo que pueda ejecutarse al mismo tiempo lo hace: un video de 13 minutos tomó 3 horas cuando cada fotograma se midió en una sola página de Chrome (un núcleo ocupado, GPU al 10 %). El motor ahora mide look, collide, review y stable en varias páginas a la vez (el render workers: la mitad de los núcleos, máximo 8, y solo tantos como la memoria libre permita;), y build ejecuta sheet, stable y review juntos. Cuando agregues un paso que visite fotogramas, divídelo también en páginas (measureParallel, traceParallel, idParallel en make.mjs). En tu propio trabajo: inicia trabajos independientes juntos (un look y un selftest, un render de Manim y una verificación), y nunca esperes a un trabajo mientras otro podría ejecutarse.

• Haz el pensamiento aquí, en la conversación principal. Tú escribes el guion, el guion gráfico y las escenas tú mismo, porque el contexto está aquí. Nunca delegues esos pasos a un subagente: un subagente comienza sin contexto. El agente de guion en el paso 7 es la única excepción, y comienza frío a propósito.

• Nunca apresures la explicación principal. El usuario aprende de estos videos. Sigue las reglas de ritmo en reference/script.md y corrige cada ADVERTENCIA de ritmo.

• Nunca inventes un hecho. Cada número, fórmula y afirmación proviene de una fuente que verificaste: el código del usuario, una hoja de datos, una especificación, un artículo, la documentación. Enuméralos en storyboard.md. Informa cualquier cosa que no pudiste verificar.

• "Tu caso" es opcional. Agrégalo solo cuando esta conversación o proyecto realmente contenga un ejemplo coincidente (un error que el usuario encontró, una solución, un número medido). Nunca inventes uno.

• Sin superposiciones. Ningún visual puede cubrir a otro: texto sobre texto, texto sobre un gráfico, o un gráfico que oculta otro gráfico. Cada etiqueta, fórmula, flecha y objeto obtiene su propio espacio. check ADVIERTE sobre textos superpuestos, y review escribe cada superposición medida en overlaps.md. El hacinamiento es juicio del usuario, así que búscalo en los fotogramas a tamaño completo. La pasada de ID ayuda: make look agrega una imagen de los espacios más ajustados, y ADVIERTE para texto a menos de 12 px de otra cosa, texto sobre un dibujo, bajo contraste de texto y un modelo que otros ocultan. Corrige cada superposición antes de make final.

• Los subtítulos tienen una línea. Cada indicación tiene como máximo 42 caracteres y no hay dos indicaciones que se muestren al mismo tiempo, por lo que un reproductor nunca muestra dos líneas. El motor hace esto; verify informa una indicación que rompe la regla. No cambies SUB_MAX en make.mjs para que quepa una indicación.

• El bucle cerrado (el usuario pidió esto, y el motor lo aplica). Después de cada edición: make look, lee cada imagen que enumera, corrige lo que ves, y vuelve a mirar. Solo entonces construye. Nunca edites y construyas a ciegas, porque una construcción es larga y un look toma segundos. Cada imagen tiene un dígito VERIFICADOR en su esquina superior derecha, y las puertas se abren solo con los dígitos de todas las imágenes, en orden:

  1. Edita. Si cambiaste script.md, ejecuta make voice. Si el video tiene partes de Manim y cambiaste manim_scenes.py o la voz, ejecuta make manim: make look dibuja los fotogramas de Manim, no los crea.
  2. make look <dir>: mide cada escena cambiada en cada fotograma, y dibuja sus fotogramas cercanos y sus partes en movimiento. Léelos todos. Luego make look <dir> --ok <digits>. make build se detiene sin esto. Una imagen con los mismos fotogramas y etiquetas que una ya leída y confirmada muestra LEÍDO ANTES y no necesita dígito (--ok - cuando cada imagen se ha leído antes). Lee cada imagen nueva; la misma regla se aplica a las tiras.
  3. make build <dir>. Se detiene ante cualquier colisión.
  4. Lee cada tira en build/review/moving.md. Luego make look <dir> --moving-ok <digits>.
  5. make final <dir>. Se detiene si la fuente cambió después del look o la construcción, o si una colisión o una superposición está abierta. Ejecuta cada paso como su propio comando, detente en el primer fallo y confirma que se aplicó una edición.

• Cada lector verifica fotogramas cercanos y partes en movimiento. Cualquier agente o sesión que juzgue un video lee los fotogramas cercanos de cada parte editada, y todos los fotogramas de cada cosa que se mueve: la mascota y los objetos, durante todo su movimiento. Una muestra del video no cuenta: una mano atravesó una mesa entre los fotogramas muestreados.

• Una nueva falla obtiene una barrera de seguridad. Cuando el usuario encuentra una falla, primero agrégala a reference/faults.md y a engine/test/selftest.mjs, y confirma que la prueba falla en ella. Luego corrige el video. No solo corrijas el video. Ejecuta make selftest después de cada cambio en una verificación.

Lo que el usuario pidió (mantén esto)

Cada uno fue pedido o elegido al oído. El motor hace la mayoría de ellos por sí mismo.

Tema	Qué	¿Automático?
Voz	La voz incorporada de Chatterbox, ralentizada a aproximadamente 160 palabras por minuto por engine/tts/slow-reference.wav; cada párrafo leído de una sola vez para que el tono se mantenga	sí
Pausas	cada punto final exactamente 0.6 s, cada coma como máximo 0.3 s, establecidas desde la puntuación del guion	sí; voice ADVIERTE si no se pudo colocar una pausa
Tomas malas	una parte cuyas palabras difieren del guion (verificación de Whisper) se vuelve a tomar con una nueva semilla, hasta 3 veces; se conserva la mejor toma	sí; ADVIERTE si aún está incorrecta
Fragmentos rápidos	una cláusula más de 1.3 veces el ritmo habitual del video (las palabras de símbolos cuentan doble) se vuelve a tomar; el usuario encontró "lambda v es v, escalado por lambda" demasiado rápido	sí; ADVIERTE "rápido": dale su propia oración corta y un [pause]
Números negativos	se lee "negativo", nunca "menos"	voice se detiene con un ERROR
Palabras repetidas	"uno uno" obtiene una coma ("uno, uno"), o la voz se desliza	sí
Escritura	párrafos conectados; [pause] solo donde termina una idea o se reproduce una animación. Rechazado: una pausa después de cada oración, oraciones entrecortadas, una voz rápida, una voz estirada (amortiguada), Kokoro	tú, consulta reference/script.md
Música	audible, constante, aproximadamente 13 dB por debajo de la voz (musicVolume 0.37; el usuario la subió 3 dB desde 0.26), atenuación suave; dos pistas aprobadas, current (predeterminada) y lofi. Rechazado: bombeo fuerte-suave, música demasiado baja para oír, otras 4 pistas	sí; tú eliges la pista, consulta SOUND.md
Efectos de sonido	el kit en engine/sfx.mjs, aprobado al oído; el silbido de entrada 4 dB por debajo de los otros acentos (el usuario lo encontró un poco demasiado fuerte). Activado para videos nuevos (_render.sfx: true), desactivado para los antiguos	tú agregas s.sfx en las indicaciones; el motor los mezcla
Audio	48 kHz estéreo	sí; verify lo verifica
Subtítulos	suaves, nunca quemados; el mpv del usuario los muestra pequeños (sub-scale=0.7)	sí
Una línea de subtítulo	una línea por indicación, máximo 42 caracteres, no hay dos indicaciones al mismo tiempo. El usuario vio dos líneas en el video 1 del conjunto ROS 2	sí; verify informa una indicación que lo rompe
Sin superposiciones	ningún texto o gráfico cubre a otro	check ADVIERTE para textos, overlaps.md y tu lista de verificación de fotogramas para el resto
Estilo	un estilo de arcilla 3D con la mascota silenciosa y nuestros propios modelos; partes de Manim sobre el fondo oscuro para curvas y gráficos (el usuario pidió: no fuerces un gráfico en arcilla)	sí

...

[truncado para traducción]