imshaikot/app-preview-craft-skill

app-preview-craft — capturas para tiendas, tarjetas sociales y videos 3D de dispositivos

Todo lo que esta habilidad genera es una página (stage/stage.html) compuesta por un tema y capturada por Chrome headless: las imágenes fijas se capturan y finalizan con sharp, los videos se renderizan cuadro por cuadro y se envían a ffmpeg. La misma página alimenta el estudio de vista previa, por lo que lo que el usuario ve ahí es exactamente lo que la CLI exporta.

0. Encuentra la habilidad, configúrala una vez

Las rutas a continuación son relativas al directorio que contiene este SKILL.md. Resuélvelo una vez y antepone los comandos con él — $SKILL significa ese directorio en todo el documento:

SKILL=/ruta/absoluta/a/app-preview-craft        # la carpeta con SKILL.md, scripts/, stage/
# ¿No estás seguro de dónde se instaló? (carpetas de habilidades, luego el caché del plugin de Claude Code)
find ./.claude/skills ./.agents/skills ./.goose/skills ~/.claude/skills ~/.agents/skills \
     ~/.gemini/skills ~/.config/goose/skills ~/.claude/plugins \
     -path '*app-preview-craft*/scripts/cli.mjs' 2>/dev/null | head -1

Luego verifica la máquina. --fix ejecuta npm install dentro de la habilidad cuando faltan paquetes:

node "$SKILL/scripts/doctor.mjs" --fix

El doctor debe terminar con Ready. Si falta ffmpeg solo es una advertencia (las imágenes fijas aún funcionan). Si informa que no hay WebGL, los temas 3D no pueden renderizarse — díselo al usuario en lugar de cambiar silenciosamente a temas planos.

Las salidas van al directorio donde el usuario está trabajando (el cwd del shell) a menos que nombren otra carpeta con --out. Nunca escribas renderizados dentro de $SKILL. El estado temporal vive en $TMPDIR/app-preview-craft/ y se elimina después de cada ejecución.

1. Flujo de trabajo

1. Elige la categoría (el primer argumento de la CLI) de lo que el usuario solicitó:

   Categoría	Qué genera	Tamaño predeterminado
   app-store	Un conjunto: una captura por diapositiva, por tamaño, más overview.png	iphone-6.9 1320×2868
   social-card	Una tarjeta (o --all diapositivas) para og/X/LinkedIn/Instagram/story	og 1200×630
   screen-video	Animación 2D solo de las pantallas; acepta grabaciones de pantalla	reel 1080×1920
   device-video	Video de exhibición de dispositivo con three.js	reel 1080×1920
   device-mockup	Imagen fija 3D de héroe, opcionalmente transparente	mockup-landscape 2400×1600

2. Reúne el contenido. Capturas de pantalla (PNG/JPG/WebP) y/o grabaciones (MP4/MOV/WebM) del proyecto del usuario, una por diapositiva, en orden. Redacta el texto tú mismo a menos que el usuario lo haya proporcionado (ver §4). Sin pantallas, se utiliza la aplicación de muestra incluida "Tempo" — está bien para mostrar temas, nunca para un entregable.

3. Elige un tema. Gana el tema que nombre el usuario. Para conjuntos de App Store, empareja la categoría de la tienda de la aplicación con la tabla en §3 y di qué tema elegiste y por qué. Cuando el usuario está indeciso, muéstrale primero las opciones:

   node "$SKILL/scripts/cli.mjs" gallery app-store        # → ./gallery-app-store.png
   

   Lee la hoja de nuevo (para que se renderice para el usuario) y deja que elija. El estudio (§8) es la mejor respuesta cuando quieren explorar y ajustar visualmente.

4. Renderiza.

   node "$SKILL/scripts/cli.mjs" app-store shots/01.png shots/02.png shots/03.png \
     --theme ledger \
     --title "Cada euro, *contabilizado*" --title "Presupuestos que se *adaptan*" --title "Privado *por diseño*" \
     --subtitle "Beneficio en una línea…" --subtitle "…" --subtitle "…" \
     --size iphone-6.9,ipad-13 --set palette.accent=auto
   

5. Inspecciona antes de informar. Lee overview.png (conjuntos), la imagen fija, o extrae fotogramas de un video (--frames 1,4,mid,end renderiza fotogramas PNG en lugar de un video — económico para verificar movimiento). Busca titulares recortados, texto sobre el dispositivo, un dispositivo cubriendo decoraciones, pantallas vacías. Corrige con anulaciones --set/por diapositiva y vuelve a renderizar.

6. Informa las rutas de salida, el tema y el tamaño, y — cada vez que aparezca un dispositivo 3D — que se escribió CREDITS.txt y que el crédito CC-BY debe acompañar a las imágenes (§7).

2. Tamaños

node "$SKILL/scripts/cli.mjs" list sizes --category app-store imprime la tabla. Cualquier WxH también funciona. Varios a la vez: --size iphone-6.9,iphone-6.5,ipad-13.

• App Store Connect requiere el conjunto de 6.9" (iphone-6.9) para aplicaciones de iPhone y ipad-13 para aplicaciones de iPad; otros tamaños son opcionales. La salida PNG se aplana (Apple rechaza el canal alfa).
• Tamaños de tableta cambian automáticamente el teléfono por un marco de tableta plano a menos que el tema sea sin marco. Proporciona capturas de iPad para esas diapositivas cuando la aplicación las tenga.
• Videos de vista previa de la aplicación: --size app-preview (886×1920) o app-preview-ipad, 15–30 s, 30 fps. Se agrega automáticamente una pista AAC estéreo silenciosa (Connect espera audio).
• Google Play: play-phone, play-tablet y play-feature (1024×500, tarjeta social).

3. Temas

list themes --category <c> imprime estos con sus diseños. Cada categoría tiene ≥ 5.

app-store — cada uno modelado según una categoría popular de aplicación

Tema	Categoría de aplicación	Inspirado en	Aspecto
stride	Salud y Fitness	Strava, Nike Run Club	naranja intenso, píldoras en mayúsculas condensadas, rayas de velocidad, teléfono inclinado
ledger	Finanzas	Revolut, Monzo, Robinhood	malla oscura, palabras con degradado menta→cian, orbes cromados
serene	Salud y Atención Plena	Calm, Headspace	aurora pastel, acentos serif en cursiva, pantalla sin marco sobre una burbuja suave
canvas	Productividad	Notion, Things, Linear	papel cálido, cuadrícula de cuaderno, serif grande, teléfono de tinta plana
sizzle	Comida y Bebida	DoorDash, Uber Eats, Deliveroo	amarillo soleado, lunares, marcas rojas de rotulador, teléfono inclinado
wander	Viajes	Airbnb, Hopper, Booking	degradado al atardecer con un sol retro que recorre todo el conjunto (panorámica)
mixtape	Música y Audio	Spotify, Apple Music	tu pantalla difuminada en un fondo brillante, palabra gigante delineada
arcade	Juegos	Apple Arcade, arte de lanzamiento de juegos móviles	cuadrícula synthwave, bordes neón, juguetes 3D brillantes
snapshot	Foto y Social	Instagram, BeReal, VSCO	tres tomas sin marco dispuestas como impresiones, malla de película cálida
pulse	Datos de salud y Wearables	Oura, WHOOP, Apple Health	negro clínico, resplandor carmesí, titular debajo de un Pro Max frontal

Los temas toman prestado un ambiente, nunca una marca: no aparecen logotipos, nombres ni obras de arte de esas aplicaciones.

social-card

launch (aurora + teléfono inclinado), spotlight (haz + suelo de espejo), pastel-fan (tres pantallas dispuestas en abanico), bento (cuadrícula de recortes de pantalla), neon-grid (synthwave), editorial (papel, serif, pantalla bitono), duo (MacBook + teléfono — pasa una pantalla de desktop para el portátil).

screen-video (2D)

carousel, stack (las tarjetas se van), scroll (las capturas largas se desplazan dentro del teléfono), zoom-tour (Ken Burns a pantalla completa hacia el focus de cada diapositiva), wall (muro de pantallas inclinadas), store-preview (estilo de vista previa de App Store — usa --size app-preview), grid-reveal.

device-video (3D)

turntable, orbit (la cámara se mueve en arco), float (repetible), rise (la cámara se acerca), flip (revelación de atrás → frente), trio (tres modelos se extienden en abanico), desk (la tapa del MacBook se abre, el teléfono se desliza a su lado; ambos sobre scene.floor), spotlight (360° en un espejo), synthwave, keyframes (tu propio movimiento de dispositivo y cámara, desde motion.keys — ver §5).

device-mockup (imágenes fijas 3D)

studio, noir, pedestal, levitate, lineup (cada modelo de teléfono), flatlay, desk-duo. Agrega --transparent para un PNG recortado.

4. Texto

• Titular por diapositiva: ≤ 6 palabras, un beneficio, no una característica. Encierra 1–2 palabras en *asteriscos* para resaltarlas en el estilo del tema; " | " fuerza un salto de línea.
• Subtítulo: una oración corta. Kicker (opcional): una etiqueta de una palabra arriba.
• Las dos primeras diapositivas llevan el mensaje principal — la mayoría de los compradores nunca se desplazan más allá.
• Nunca inventes calificaciones, recuentos de descargas, premios o citas de prensa. Decoraciones como rating y laurels son para cifras reales que el usuario te da; pregunta cuando no estés seguro.
• No menciones competidores ni uses marcas comerciales de Apple/Google en el texto más allá de lo que permiten las pautas de la tienda.

5. Configuración de cualquier cosa

Orden de resolución, gana el último: base incorporada → valores predeterminados del diseño → tema (y su cadena extends) → archivo de tema personalizado → themeOverrides del proyecto → atajos de CLI → --set → theme por diapositiva.

• Atajos: --layout --device --finish --pose --font --body-font --bg --bg2 --bg3 --ink --sub --accent --accent2 --background --pattern --background-image --clean-status-bar --no-decor --duration --fps --speed --intro --outro.
• --set ruta=valor alcanza cualquier clave del tema (repetible). list options imprime las rutas documentadas con tipos y rangos. Los valores se convierten automáticamente; JSON funciona para listas/objetos: --set device.pose=5,-15,4 --set 'decor=[{"kind":"sparkles","count":8}]'.
• device.pose son grados x,y,z. Los temas se mantienen aproximadamente dentro de ±20° de guiñada y ±6° de balanceo para que la pantalla aún sea legible en tamaño de miniatura de tienda; poses más pronunciadas funcionan pero afectan la legibilidad.
• Los colores aceptan auto = el color más vívido en la primera captura de pantalla: --accent auto.
• --device iphone-17-pro | iphone-17-pro-max | iphone-12-pro | galaxy-s21-ultra | macbook-pro-16 | flat[:phone|phone-android|tablet|browser] | frameless | none, o el ID del modelo propio del usuario (§7).
• Los diseños son intercambiables dentro de un tipo (list layouts): imágenes fijas — hero-top, hero-bottom, tilt, duo, fan, split, big-type, callout, bento, laptop-phone, showcase, pedestal, lineup, flatlay; videos — carousel, stack, scroll, zoom-tour, wall, phone-swap, grid-reveal, turntable, orbit, float, rise, flip, trio, desk, spotlight, keyframes.
• Tu propio movimiento: el diseño keyframes mueve un dispositivo 3D y la cámara a través de motion.keys, una lista de { "at": 0..1, "x", "y", "size", "pose": [rx, ry, rz], "cam": { "yaw", "pitch", "dist" }, "ease" }. at es una fracción de todo el video; un valor que una clave omite mantiene el de la clave anterior; la primera clave comienza desde la pose del propio tema. Eases: linear inOutCubic inOutSine outCubic outQuart outBack inOutQuart outExpo. --theme keyframes --set 'motion.keys=[{"at":0,"y":1.4,"pose":[0,70,0]},{"at":0.3,"y":0.62,"pose":[4,-20,3],"ease":"outQuart"},{"at":1,"pose":[0,15,0],"cam":{"dist":0.9}}]'. No se utiliza ninguna biblioteca de animación: cada fotograma es una función pura de su tiempo, que es lo que permite que los fotogramas se rendericen fuera de orden. Verifica un movimiento con --frames 0,2,mid,end.

Temas personalizados son archivos JSON (o .mjs) con cualquier subconjunto de claves del tema más extends:

{ "extends": "app-store/ledger", "name": "Acme", "palette": { "accent": "#ff5a1f" },
  "type": { "display": "bricolage", "weight": 800 }, "device": { "finish": "#1c1f24" } }

Pasa --theme ruta/a/acme.json, o colócalo en ./.app-preview-craft/themes/ (o ~/.app-preview-craft/themes/) y usa --theme acme. list themes muestra los personalizados.

Configuración del proyecto. node "$SKILL/scripts/cli.mjs" init app-store escribe app-preview-craft.json; después node "$SKILL/scripts/cli.mjs" (sin argumentos) lo renderiza, y las banderas aún lo anulan. $SKILL/examples/app-preview-craft.json es un ejemplo completo y funcional: texto por diapositiva, decoraciones y anulaciones de tema, un archivo de tema personalizado, una pantalla de escritorio y una lista jobs que renderiza un conjunto de App Store, una tarjeta social, una maqueta y un video en un solo comando. Las rutas en una configuración se resuelven relativas al archivo de configuración.

Claves por diapositiva: screen, desktop (pantalla de portátil), title, subtitle, kicker, theme (anulaciones solo para esa diapositiva), decor (reemplaza la decoración del tema para esa diapositiva), focus: [x, y, zoom] (destino de zoom-tour), hold (segundos en un video), trim: [inicio, fin] y at (qué segundo de una grabación usa una imagen fija), bigWord (diseño big-type).

Elementos de decoración son {kind, x, y, scale, rotate, style, layer, delay, …} con x/y como fracciones de página y style uno de glass | solid | light | dark | outline:

kind	Claves adicionales
badge	text, icon (estrella rayo corazón check chispa trofeo hoja candado música pin llama campana escudo globo play)
rating	score, label, starColor
laurels	top, text, bottom
chips	items[], icons[], width, lead
notification	app, title, body, time, icon (ruta de imagen) o glyph, width
stat	label, value, trend, trendColor
callout	rect: [x, y, w, h] de la captura de pantalla a ampliar, w, border, radius
arrow	w, h, text (nota manuscrita), flip, stroke
logo	name, src (ruta del icono de la aplicación)
store-badge	top, text, o src para la obra de arte oficial de la insignia
sparkles confetti	count, colors[], area: [x0, y0, x1, y1], seed
blob	size, color, opacity (se sitúa detrás del dispositivo)
orbs rings shapes	Primitivas 3D: count, shapes[], finish (glossy chrome matte glass iridescent), area, items[]
credit	text (predeterminado a la línea de crédito del modelo)

6. Pantallas y tratamientos

• sharp prepara cada captura de pantalla antes de que Chrome se inicie: screen.cleanStatusBar (redibuja una barra de estado de iOS 9:41 / batería completa — solo capturas con forma de teléfono), tint + tintAmount, duotone: "#oscuro,#claro", saturate, brightness, sharpen y un fondo pre-difuminado para fondos blur-shot.
• En los modelos de iPhone, la Isla Dinámica se dibuja como una sola píldora negra fusionada sobre los recortes de píldora y cámara del modelo, coincidiendo con lo que muestra iOS. Proporciona capturas de pantalla con el área de la isla clara (cualquier captura normal de iOS lo es); cleanStatusBar mantiene la hora y los iconos a cada lado.
• Una captura más alta que la pantalla se desplaza en videos (tema scroll) y muestra su parte superior en imágenes fijas (screen.fit=top).
• Las grabaciones se dividen en fotogramas por ffmpeg a la velocidad de fotogramas de salida; en los videos, cada diapositiva de grabación dura tanto como el clip (anula con hold, corta con trim). Las imágenes fijas usan un fotograma (at, predeterminado: el central).
• Las pantallas de portátil colocan en letterbox una captura de teléfono sobre una copia difuminada a menos que la diapositiva tenga una pantalla desktop. desktop también acepta una grabación. En el video desk, el MacBook muestra la pantalla de desktop si está presente o, de lo contrario, la primera diapositiva de screen.

7. Modelos de dispositivo 3D

Los modelos de dispositivo son archivos GLB bajo $SKILL/assets/devices/. Los modelos de terceros están bajo licencia CC-BY; se escribe un CREDITS.txt con el contenido de la licencia cada vez que se renderiza un dispositivo 3D.

Lista de modelos disponibles (list devices):

node "$SKILL/scripts/cli.mjs" list devices

Añadir tu propio modelo: coloca un archivo GLB/GLTF en el directorio de trabajo o en ~/.app-preview-craft/devices/. Pasa el nombre del archivo (sin extensión) como --device y finish como --finish (the glossy, matte, chrome, glass, iridescent). Si el modelo no coincide con las dimensiones estándar, usa --set device.modelScale=1.2 para escalarlo.

8. Estudio de vista previa

node "$SKILL/scripts/cli.mjs" studio

Inicia un servidor de vista previa en vivo que recarga automáticamente cualquier cambio. Es la mejor manera de que los usuarios exploren temas, ajusten el diseño de la decoración y depuren problemas. El estudio renderiza exactamente el mismo código que la CLI, por lo que siempre hay una correspondencia 1:1.

9. Trabajar con la salida

• Conjuntos de App Store: overview.png es una hoja de estilo de comparación con todas las diapositivas y tamaños. Es la forma más rápida de verificar un conjunto completo.
• Vistas previas de video: --frames middle,1,4,end genera imágenes PNG en lugar de un video. Útil para verificar el encuadre y el movimiento sin esperar una renderización completa del video.
• Imágenes fijas individuales: la CLI genera un PNG por diapositiva en el directorio de salida.

10. Notas técnicas

• El motor de renderizado es una página HTML única (stage/stage.html) que utiliza three.js para escenas 3D y Canvas 2D para diseños 2D. La misma página se abre en el navegador cuando el usuario ejecuta studio.
• Chrome headless debe estar disponible en el PATH. La habilidad verifica esto durante la ejecución de doctor.mjs.
• ffmpeg es necesario solo para la salida de video. Si falta, la habilidad todavía puede generar imágenes fijas y conjuntos de App Store.
• Todas las rutas temporales se escriben en $TMPDIR/app-preview-craft/ y se limpian después de cada ejecución exitosa.
• Las imágenes de salida son PNG (con pérdida para videos) a menos que se especifique lo contrario. App Store Connect espera PNG aplanado (sin canal alfa).

Créditos: Los modelos de dispositivo 3D se utilizan bajo licencia Creative Commons Attribution (CC-BY). Consulta CREDITS.txt generado en el directorio de salida para conocer los detalles de atribución.