/breakdown: tu producto, desarmado, cada pieza etiquetada
El usuario adjunta una foto de producto y/o nombra un producto. Tú determinas de qué está hecho, lo describes como piezas 3D simples (tamaños en milímetros), verificas dos fotogramas, lo renderizas girando, desarmándose y etiquetándose, y entregas un MP4 silencioso (de unos 6 segundos).
${CLAUDE_SKILL_DIR} abajo es la carpeta de esta skill (aquella donde está este SKILL.md). Si tu entorno no la rellena, usa la ruta de esa carpeta. Guarda todo en la carpeta actual del usuario, o en la carpeta que nombre. La página 3D carga three.js desde internet, por lo que necesita conexión.
0. Verificación de configuración
python3 "${CLAUDE_SKILL_DIR}/scripts/render.py" --check
Tarda unos segundos; ejecútalo si no estás seguro de que este computador esté configurado. "ready": true significa que puedes continuar. De lo contrario, ejecuta los comandos que se listan bajo "fix", informando al usuario que es una instalación única: python3 -m pip install playwright (el controlador del navegador), python3 -m playwright install chromium (solo si Google Chrome o Edge no está instalado, unos 150 MB) y python3 -m pip install imageio-ffmpeg (solo si falta ffmpeg). Si pip se niega con "externally managed environment", crea un entorno privado una vez y usa su Python para todos los comandos: python3 -m venv ~/.animate-skills && ~/.animate-skills/bin/pip install playwright imageio-ffmpeg, luego ~/.animate-skills/bin/python -m playwright install chromium si es necesario. En Windows, usa py en lugar de python3. ¿No es posible usar un navegador aquí (por ejemplo, el sandbox de la app de Claude)? Ve al final de este archivo.
1. Determinar el producto
- A partir de la foto: forma general, proporciones, colores y acabados (vidrio brillante, metal cepillado, plástico mate, tela), y la disposición de los detalles visibles (lentes de cámara, botones, puertos). No reproduzcas logotipos de marca.
- Sus partes reales principales, en orden de ensamblaje de un lado al otro: de 5 a 9 piezas que valga la pena etiquetar (cubierta, pantalla, marco, batería, placa, chip, altavoz, driver, almohadilla...). Usa lo que realmente contiene este tipo de producto; si no estás seguro de un modelo específico, usa las partes que su categoría siempre tiene y no inventes piezas exóticas.
- El kit construye productos a partir de formas simples, por lo que funciona bien en objetos hechos de capas y piezas duras (teléfonos, teclados, auriculares, altavoces, controles, relojes, cámaras, electrodomésticos). Los productos blandos y orgánicos (zapatos, ropa, comida) resultan con aspecto de juguete: díselo al usuario si pide uno.
- Tamaños reales aproximados en mm (un teléfono mide ~72 x 150 mm y 8 mm de grosor; un teclado completo ~440 x 130 mm).
2. Escribir la especificación
Guarda breakdown-<producto>.json. Cada parte es una forma simple colocada donde se ubica en el producto ensamblado; level indica qué tanto se desplaza cuando el producto se desarma (0 se queda quieto, 1 se mueve un paso, 2 dos pasos; las partes con el mismo nivel se mueven juntas; mitades como 3.5 funcionan, y los niveles negativos mueven en la otra dirección). Ejemplo (examples/smartphone.json, abreviado):
{
"title": "Inside a smartphone",
"theme": "dark",
"parts": [
{"name": "Cover glass", "shape": "slab", "size": [72, 0.7, 150], "radius": 10.5, "material": "glass", "y": 0, "level": 0},
{"name": "Display", "shape": "slab", "size": [69, 0.7, 147], "radius": 9, "material": "black", "color": "#232428", "y": 0.8, "level": 1},
{"name": "Frame", "shape": "frame", "size": [72, 7.4, 150], "radius": 10.5, "wall": 2.5, "material": "aluminum", "y": 0.9, "level": 2},
{"name": "Battery", "shape": "slab", "size": [62, 4, 86], "radius": 5, "material": "battery", "text": "Li-ion|5,000 mAh", "pos": [0, 2, 24], "level": 3},
{"name": "Logic board", "shape": "slab", "size": [62, 1, 44], "radius": 4, "material": "pcb", "pos": [0, 2, -48], "level": 3},
{"name": "Cameras", "shape": "lens", "radius": 4.6, "size": [9.2, 4.2, 9.2], "copies": [[-23.2, -62.2], [-23.2, -45.5], [-8, -53.8]], "y": 6.6, "level": 4},
{"name": "Back glass", "shape": "slab", "size": [72, 0.9, 150], "radius": 10.5, "material": "glass-tint", "color": "#3d5571", "y": 8.4, "level": 5}
]
}
Coordenadas: size es [ancho x, alto y, profundidad z] en mm; y es hacia arriba. pos: [x, y, z] (o solo "y") es la posición del centro inferior de la pieza en el producto ensamblado. Las piezas pueden superponerse ligeramente; eso está bien.
Formas: slab (placa rectangular redondeada; radius = radio de esquina), frame (una losa con un agujero; espesor wall), box (esquinas afiladas), cylinder/disc (radius, altura = size[1]), ring (radius, inner), lens (un lente de cámara con su anillo metálico), sphere (escalado por size), capsule, cone (radiusTop), torus/cushion (radius, tube; queda plano con su agujero hacia arriba: almohadillas de oreja, anillos O, neumáticos), band (radius, tube, arc: un arco vertical sobre la parte superior: diademas, asas, agarre de una tetera), tube (una varilla desde from: [x, y, z] hasta to: [x, y, z], con radius y radiusTo opcional: tubos de marco, patas de sillas y mesas, puntales, pajitas), lathe (profile: [[radio, y], ...] girado alrededor del eje vertical: botellas, tazas, perillas, conos de altavoz, domos; ambos lados se dibujan, por lo que el orden de los puntos no importa). arc (grados, por defecto 360) hace un ring, torus, band o lathe parcial (comienza en el lado +x; gíralo con rot). spokes: n en un ring o torus agrega n radios y un cubo (ruedas, ventiladores). stretch: [x, y, z] escala una pieza (una almohadilla ovalada: [0.85, 1, 1.15]). rot: [x, y, z] grados gira una pieza alrededor de su centro inferior ([90, 0, 0] pone un cilindro de lado, [0, 90, 0] gira una losa para que su texto impreso se lea a lo largo del otro lado).
Repeticiones: copies: [[x, z], ...] (o [x, y, z]) coloca la misma pieza varias veces (cámaras, tornillos, botones); una copia también puede ser {"pos": [x, y, z], "rot": [x, y, z]} para girar cada una (almohadillas de oreja izquierda y derecha mirando hacia afuera). grid: {"nx": 14, "nz": 5, "pitch": 19} distribuye una rejilla (teclas, celdas, LED). El punto de la etiqueta va en la primera copia.
Materiales: glass (transparente), glass-tint (vidrio de color), aluminum, steel, gold, copper, black, white, plastic (cualquier color), ceramic, rubber, foam, fabric (rejilla de malla), wood, leather, pcb (placa de circuito verde), chip, battery (celda oscura; text se imprime en ella, | para nuevas líneas), coil (bobina de carga inalámbrica de cobre), lens, screen (pantalla iluminada), magnet, emissive (brilla). color (hex) tiñe la mayoría de ellos. text imprime una etiqueta en la cara superior de una losa. La iluminación de estudio aclara un poco los colores: compara el primer fotograma de verificación con la foto y oscurece el color si se ve desteñido. Para metal oscuro usa steel o black (aluminum es para tonos plateados), y para un producto mayormente negro usa el tema claro para que sus piezas no se pierdan en el fondo oscuro.
La foto del usuario: úsala para obtener la forma, colores y disposición correctos. Si muestra una cara plana de frente (la parte trasera o la pantalla de un teléfono, una tarjeta, una tapa), también puedes mapearla sobre esa pieza: "photo": "ruta/a/la/foto.jpg" en el nivel superior, luego "texture": "photo" en la pieza, con "crop": [x0, y0, x1, y1] (fracciones 0-1 de la foto) alrededor de esa cara. Para una foto en ángulo o en perspectiva, usa solo colores y disposición.
Etiquetas: cada pieza se etiqueta con su name (mantén los nombres cortos: hasta ~14 caracteres se mantienen en tamaño completo); "label": "Other text" lo cambia, "label": false lo oculta (úselo para piezas decorativas pequeñas, de modo que solo se muestren de 5 a 9 etiquetas).
La vista: el producto gira sobre un plato giratorio: su ángulo en radianes es spin - spinSpeed × segundos (por defecto 0.95 y 0.07, por lo que termina alrededor de una vista de tres cuartos). El ángulo 0 mira directamente al lado +z del producto; los ángulos positivos lo giran para que veas más de su lado −x (1.57 mira hacia el extremo −x). Para objetos largos y planos donde las piezas se ocultan entre sí, termina de lado: por ejemplo, "spin": 1.9, "spinSpeed": 0.06. elevation0/elevation1 son la altura de la cámara en grados (38 → 24 por defecto). zoom (por defecto 1, por ejemplo, 1.2) agranda el producto si se ve pequeño. Productos largos o anchos (una bicicleta, un sofá, un zapato plano) salen pequeños en un video vertical: usa "size": "1080x1080" o "1920x1080", o zoom. Las etiquetas mantienen un orden (el orden de las piezas en la vista explosionada final).
Productos que no son una pila (auriculares, una tetera, un control): desarmar hacia arriba llena mejor un video vertical, por lo que coloca el producto de manera que sus capas se apilen verticalmente. Para auriculares de diadema, apóyalos de lado (el eje de las copas en posición vertical) y separa las capas de una copa hacia arriba (almohadilla, malla, driver, placa, batería, carcasa) mientras que la diadema y la otra copa permanecen ensambladas; usa explode: [x, y, z] por pieza para un desplazamiento exacto.
Otros campos: title (por ejemplo, "Inside a ..."), subtitle, theme (dark por defecto, light), axis ("y" separa hacia arriba, por defecto; "x" o "z" separa hacia los lados, para objetos largos y delgados como bolígrafos o una botella de lado; de lado sale más pequeño en un marco vertical), gap (mm entre niveles; por defecto ~19% del tamaño del producto), explode: [x, y, z] en una pieza (su propio desplazamiento en mm, en lugar de su nivel), apartAt (segundos; por defecto 1.5), size, duration (por defecto ~6-7 s, suficiente para leer las etiquetas), fps. Un segundo ejemplo: examples/mechanical-keyboard.json.
3. Verificar dos fotogramas
python3 "${CLAUDE_SKILL_DIR}/scripts/render.py" breakdown-<producto>.json --still 0.5 --out breakdown-<producto>-check1.png
python3 "${CLAUDE_SKILL_DIR}/scripts/render.py" breakdown-<producto>.json --still end --out breakdown-<producto>-check2.png
--still toma segundos, o end (agrega un tercero a aproximadamente 3.5 s, cuando llegan las etiquetas, si las piezas están muy juntas). El primero es el producto ensamblado: ¿se parece al producto (forma, proporciones, colores)? El segundo es la vista explosionada con etiquetas: piezas en un orden sensato, nada oculto dentro de otra cosa, el punto de cada etiqueta sobre su pieza, etiquetas legibles. Corrige tamaños, posiciones, niveles o la vista y vuelve a verificar (dos o tres rondas es normal).
4. Renderizar el video
python3 "${CLAUDE_SKILL_DIR}/scripts/render.py" breakdown-<producto>.json --out breakdown-<producto>.mp4
Aproximadamente 10-20 segundos. Si un render 3D sale negro, agrega --no-gpu. Elimina las imágenes de verificación.
5. Entregar
Proporciona al usuario la ruta del MP4 (muéstralo si tu entorno puede mostrar archivos). No tiene sonido. Di en una línea que las piezas son un modelo simplificado de su producto y ofrece una variación (el tema claro, una pieza renombrada).
¿Sin navegador aquí? (por ejemplo, el sandbox de la app de Claude)
Si la verificación de configuración no puede ejecutar un navegador, escribe la animación como una página en su lugar: python3 "${CLAUDE_SKILL_DIR}/scripts/render.py" breakdown-<producto>.json --html breakdown-<producto>.html. La página se reproduce en cualquier navegador (muéstrala como un artefacto si puedes). Indica al usuario que el MP4 necesita Claude Code en un computador, o una grabación de pantalla de la página.