aeentech/thumbnail

¿Qué hace thumbnail?

Convierte un sitio web, un proyecto web local o un artículo individual en una miniatura terminada de alta resolución que parece pertenecer a ese sitio. La imagen se compone en HTML/CSS a partir del material del propio sitio y se renderiza a PNG y WebP sin pérdida.

Principios

• Inspirado en el sitio. Cada miniatura es una nueva composición construida con los elementos característicos del sitio: su imagen principal, componentes, imágenes, motivos, tipografía y colores. Una captura de pantalla en un marco de dispositivo es solo una de nueve composiciones y nunca es la opción predeterminada.
• Solo material real. Utiliza el logotipo, las imágenes, el texto, los números, los colores y las fuentes reales del sitio. Nunca inventes funciones, precios, estadísticas o afirmaciones.
• Un resultado por ejecución. Se ejecuta completamente de forma automática. La única pregunta que esta habilidad puede hacer es la pregunta de idioma en Entradas → Idioma.

Comunicación

• Trabaja en silencio. No narres pasos, hallazgos, razonamientos de diseño, reintentos ni correcciones. El análisis permanece en las llamadas a herramientas y en brief.md. Mantén las descripciones de las llamadas a herramientas cortas y neutrales.
• Habla solo cuando sea necesario: la pregunta de idioma, un problema bloqueante en el que el usuario deba actuar (el sitio es inaccesible, el proyecto no puede ejecutarse) y la entrega final.
• Idioma de la sesión. Escribe cada mensaje dirigido al usuario (preguntas, opciones, errores, la respuesta final) en el idioma en el que el usuario está escribiendo, independientemente del idioma de la miniatura.
• Respuesta final. Muestra la imagen, luego proporciona las rutas PNG y WebP y dos o cuatro líneas cortas: composición, formato, oración, categoría, y de dónde provienen el logotipo, los colores y la fuente. Termina con una línea que ofrezca ediciones y una línea que sugiera otro formato (consulta references/formats.md). Sin resumen del proceso.

Configuración

Las rutas son relativas al directorio de esta habilidad (la carpeta que contiene este archivo). Define SKILL_DIR como esa carpeta y S=$SKILL_DIR/scripts.

Script	Propósito
`inspect.mjs <url	archivo>`
`extract.mjs <url	archivo> --out `
`extract.mjs <url	archivo> --out --selector "" --name [--transparent]`
`screenshot.mjs <url	archivo> --out <archivo.png> [--width --height --scale --wait]`
render.mjs <archivo.html> [--out <archivo.png>]	Renderiza una composición al 2x a PNG y WebP sin pérdida. Lee el tamaño del lienzo de la página e informa sobre fuentes cargadas, fuentes fallidas, imágenes rotas y texto desbordado.
history.mjs / history.mjs add <sitio> "<composición>"	Muestra o registra composiciones utilizadas recientemente.

Los scripts no tienen dependencias npm. Si no se encuentra un navegador, establece CHROME_PATH. En macOS, head puede estar oculto por una herramienta Perl; lee archivos con cat, sed -n o python3.

Entradas

Resuelve estas cuatro entradas antes de diseñar.

Objetivo

• Modo URL: la solicitud contiene una URL o dominio. Carpeta de salida: ./thumbnail-<dominio>/ en el directorio de trabajo actual. Trata cualquier otra palabra en la solicitud como notas, por ejemplo, un idioma, un formato, una composición o un deseo de estilo.
• Modo proyecto: sin URL. El objetivo es el proyecto actual. Carpeta de salida: ./thumbnail/ en la raíz del proyecto.

Mantén todos los archivos de la ejecución dentro de la carpeta de salida.

Tipo de página (modo URL)

Ejecuta inspect.mjs primero y lee page.type:

• site: la miniatura trata sobre todo el sitio web.
• article: la URL es un artículo individual, publicación de blog, guía o noticia. La miniatura trata sobre el tema del artículo, con el estilo de la identidad del sitio. Usa la carpeta de salida ./thumbnail-<dominio>-<slug>/, donde el slug es el último segmento de la ruta, acortado a unos 40 caracteres.

La detección usa og:type, JSON-LD (Article, BlogPosting, NewsArticle…), una fecha de publicación, un elemento <article>, rutas URL estilo blog y la longitud del texto. Las notas del usuario lo anulan: "sobre el sitio" significa sitio, y "sobre el artículo" o "sobre el tema" significa artículo, en cualquier idioma.

Idioma

Determina el idioma del contenido a partir de lang y dir, encabezados y texto de la interfaz de usuario. En modo proyecto, verifica también <html lang> y carpetas de configuración regional como locales/<código> o messages/<código>.json.

1. Si las notas del usuario nombran un idioma, úsalo.
2. Si el sitio tiene un solo idioma, úsalo. Los idiomas árabe, persa, urdu y hebreo se escriben de derecha a izquierda.
3. Si el sitio es totalmente compatible con dos o más idiomas, pregunta al usuario cuál usar. Usa la herramienta de preguntas del agente si la tiene; de lo contrario, pregunta en el chat y espera. Recomienda la configuración regional predeterminada del sitio.
4. Si el idioma no está claro, usa árabe.

La oración, la categoría y cualquier texto adicional se escriben en el idioma elegido.

Formato

• Predeterminado: una miniatura de cartera, 1080 × 720, para un sitio; Open Graph, 1200 × 630, para un artículo.
• A petición: si el usuario nombra una plataforma, ubicación, relación de aspecto o tamaño exacto, resuélvelo con $SKILL_DIR/references/formats.md. Ese archivo también proporciona el nombre del archivo de salida, las zonas seguras para formatos verticales y las pautas de diseño.
• Cada formato se renderiza al 2x y se exporta como PNG y WebP sin pérdida.

Flujo de trabajo

Trabaja en pocos turnos. Cada turno relee toda la conversación, por lo que el número de turnos impulsa el costo mucho más que cualquier archivo individual. Agrupa comandos independientes en una sola llamada de shell, lee archivos independientes en paralelo en el mismo turno y nunca vuelvas a leer un archivo o imagen que ya hayas visto.

1. Haz que el objetivo sea accesible

• Modo URL: usa la URL.
• Proyecto estático (un index.html y sin paso de compilación): usa la ruta del archivo. Si los activos usan rutas absolutas de raíz, sirve la carpeta en segundo plano (por ejemplo, python3 -m http.server 4173) y usa http://localhost:4173.
• Proyecto con framework (un package.json con dev, start o preview): instala las dependencias si node_modules falta, usando el administrador de paquetes que coincida con el archivo de bloqueo. Inicia el servidor de desarrollo en segundo plano, lee su puerto de la salida y espera hasta que curl -s -o /dev/null -w "%{http_code}" <url> responda. Detén el servidor una vez que la extracción haya terminado.
• No se puede ejecutar: usa una URL desplegada de package.json (homepage) o el README. Si no hay ninguna, construye a partir de los activos propios del proyecto (imágenes, componentes, estilos) e informa al usuario.

2. Inspeccionar, extraer y verificar el historial (un comando)

Ejecuta los tres en una sola llamada de shell:

mkdir -p <out> && node $S/inspect.mjs <url> > <out>/inspect.json && node $S/extract.mjs <url> --out <out>/extract && node $S/history.mjs

Si inspect.json muestra que la página es un artículo, renombra la carpeta a ./thumbnail-<dominio>-<slug>/ en tu próxima llamada de shell.

3. Comprender el contenido y estudiar la identidad (un turno)

En el mismo turno, lee los campos clave de inspect.json (imprímelos con un script corto en lugar de todo el archivo) y visualiza extract/overview.png. La descripción general es una hoja de contactos de cada captura (imagen principal, secciones, elementos, imágenes), cada una etiquetada con su nombre de archivo.

Contenido

• Sitio: ¿qué es, para quién es, qué ofrece y qué lo hace sentir como él mismo? Usa inspect.json, extract.json y, en modo proyecto, el README, package.json, componentes de página de inicio y de héroe, archivos de configuración regional, metaetiquetas, manifiesto y estilos.
• Artículo: ¿de qué trata el artículo y qué obtendrá el lector de él? Usa page.article (titular, descripción, sección, etiquetas, autor, fecha, tiempo de lectura, subtítulos, imagen de portada, imágenes dentro del artículo, bloques de código) y el texto del artículo.
• Si el texto de la página es escaso (una página renderizada del lado del cliente o un muro de bots), recupéralo de otra manera, por ejemplo con una herramienta de recuperación web o curl.

Identidad: desde la descripción general (más la imagen de portada de un artículo), anota:

• Estado de ánimo y estilo: fotográfico, 3D, ilustración plana, lujo, divertido, técnico, editorial, minimalista…
• Elementos característicos: las dos a cuatro cosas por las que las personas reconocen el sitio, por ejemplo, una imagen u objeto principal, una tarjeta o producto distintivo, un motivo, una muestra de código, un conjunto de iconos, un degradado, un tratamiento tipográfico.
• Tokens: colores, fondo de página, colores de botones, radios, sombras, degradados, estilo de encabezado y estilo de insignia o botón.

4. Elegir la composición

Si el usuario solicita explícitamente una composición, úsala. Esto se aplica cuando el usuario nombra una (por ejemplo "Collage de componentes") o describe claramente su idea, en cualquier idioma (por ejemplo "un collage de las tarjetas del sitio" o "una cuadrícula de sus características"). Usa esa composición incluso si se usó recientemente y omite la verificación del historial. Sus otras notas aún se aplican.

De lo contrario, elígela tú mismo:

1. Usa el historial impreso en el paso 2.
2. Lee $SKILL_DIR/references/compositions.md y elige la composición que mejor exprese los elementos característicos de este sitio.
3. Evita las composiciones utilizadas en las últimas dos ejecuciones a menos que nada más encaje.
4. Escribe <out>/brief.md. Mantenlo corto: palabras clave de identidad, elementos característicos y los archivos que usarás, la composición elegida y por qué, y un bosquejo de diseño de una línea.

5. Abrir los activos elegidos a tamaño completo (un turno)

La descripción general es para elegir, no para detalles. Una vez que sepas qué dos a cuatro activos usará el diseño (y el logotipo), ábrelos a máxima resolución, todos en paralelo en un turno, para verificar texto pequeño, motivos finos y nitidez antes de diseñar. Si una parte que necesitas no fue detectada, captúrala con extract.mjs --selector en el mismo turno.

6. Escribir el contenido

Oración

• Sitio: lo que el sitio ofrece y por qué es importante. Usa de 5 a 10 palabras para árabe y de 6 a 12 para inglés u otros idiomas. Escribe texto de marketing natural sin punto final y no repitas el nombre del sitio.
• Artículo: la idea central del artículo, ya sea su titular ajustado para que encaje o un resumen fiel de una línea. Usa de 5 a 12 palabras para árabe y de 6 a 14 para otros idiomas. No agregues nada que no esté en el artículo.
• Debe caber en tres líneas. Puedes resaltar de una a tres palabras clave usando el color de acento o el tratamiento de encabezado del sitio.

Categoría

• Dos o tres palabras en el idioma de la miniatura.
• Sitio: el tipo de producto, por ejemplo, Tienda en línea, Plataforma de aprendizaje electrónico, Sitio web de empresa, Panel de control SaaS, Plataforma de reservas o Portafolio.
• Artículo: la sección o el tema del artículo, por ejemplo, Guía, Caso de estudio, Tutorial o el tema en sí.

Extras del artículo (opcional)

• Autor, fecha y tiempo de lectura, configurados en pequeño. Usa solo valores reales de la página.

Logotipo

• Siempre usa el logotipo real y visualízalo antes de usarlo.
  • Proyecto: busca en public/, static/, assets/, src/assets/ y app/ por logo*.{svg,png,webp}, icon*.svg, favicon.svg, apple-touch-icon.png y icon-512*.png, más iconos de manifiesto y componentes de logotipo en línea.
  • URL: usa inspect.json: logoSvgs (SVG en línea), logoBackgrounds (logotipos dibujados como fondos CSS, a menudo un SVG listo), logoImgs e icons. Prefiere un logotipo vectorial o transparente; recórtalo de extract/elements/*-header.png solo como último recurso, porque un recorte arrastra el fondo de la página. Guarda los archivos en la carpeta de salida.
• Los SVG en línea que usan currentColor o variables CSS necesitan colores de relleno reales. No coloques un cuadro o fondo detrás del logotipo a menos que sea necesario para el contraste: logotipos claros sobre áreas oscuras, logotipos oscuros sobre áreas claras.
• Para un artículo, el logotipo es una pequeña firma, no el héroe.
• Si no existe un logotipo, usa un icono de Lucide que exprese la idea (https://cdn.jsdelivr.net/npm/[email protected]/icons/<nombre>.svg), con estilo en los colores de la marca. Nunca dibujes un logotipo falso.

7. Fuente

• Fuentes: extract/fonts.css (las reglas @font-face del sitio, con los archivos de fuente descargados) y extract.json (fonts.google). En modo proyecto, verifica también next/font, reglas @font-face, importaciones de Google Fonts, la configuración fontFamily de Tailwind y archivos de fuente en public/fonts.
• Cargarla: agrega el <link> justo después del enlace de Noto Sans en el lienzo, luego establece --font: "<Fuente del Sitio>", "Noto Sans Arabic", "Noto Sans", sans-serif.
• Verificar cobertura: la fuente debe cubrir la escritura de la miniatura. Una fuente solo latina no puede renderizar texto árabe, por lo que se recurre a Noto Sans Arabic. Si una fuente decorativa tiene solo un peso, usa ese peso; nunca falsifiques negrita.
• Alternativa: si la fuente falta en la lista de fuentes que render.mjs informa, o aparece en failedFonts, usa Noto Sans Arabic o Noto Sans en su lugar.

8. Construir y renderizar

1. Copia $SKILL_DIR/assets/canvas.html a <out>/<nombre>.html. El nombre es thumbnail para el formato predeterminado y thumbnail-<preajuste> para otros formatos.
2. Establece el tamaño del lienzo con --w y --h en la primera regla :root (el valor predeterminado es 1080px × 720px). Diseña la composición para esa forma, y para formatos verticales mantén el texto dentro de la zona segura.
3. Diseña en HTML y CSS simples; el SVG en línea es bienvenido.
   • Reemplaza las variables de diseño y la regla de fondo de .canvas al final del bloque <style>, luego agrega tus propias reglas después.
   • Coloca el marcado dentro de <div class="canvas"> y deja el <script> de cierre sin cambios.
   • Haz referencia a los activos con rutas relativas, como extract/images/…, extract/elements/… y logo.png.
4. Marca el texto para el renderizador:
   • data-fit="3" en la oración la reduce hasta que quepa en tres líneas. data-min establece el tamaño más pequeño; nunca va por debajo del mínimo legible del formato.
   • data-text="<nombre>" en los elementos de texto permite que el renderizador informe sobre desbordamiento.
   • data-decor en texto que no está destinado a ser leído (un logotipo tipográfico, una palabra de fondo enorme) para que el renderizador lo ignore.
5. Renderiza: node $S/render.mjs <archivo.html> --out <archivo.png>.
6. Si render.mjs informa fuentes fallidas, imágenes rotas o desbordamiento, soluciona el problema y vuelve a renderizar. Recurre a Noto Sans para fuentes fallidas y elimina imágenes rotas. Para desbordamiento, reduce manualmente los tamaños de texto, especialmente la oración.
7. Si la oración se reduce por debajo de 7 px, reescribe una versión más corta.

Regla de oro: El renderizador debe ejecutarse sin errores, sin fuentes fallidas, sin imágenes rotas y sin desbordamiento en la primera vez, o como máximo en la segunda.

9. Entregar

Muéstrale la imagen al usuario, luego imprime un mensaje de confirmación breve:

• thumbnail.png / thumbnail.webp (rutas)
• Composición: el nombre de la composición (por ejemplo, "Collage de componentes")
• Formato: el nombre del formato (por ejemplo, "Cartera" o "Open Graph")
• Oración: "La oración central"
• Categoría: "Categoría"
• Logotipo: de dónde proviene
• Colores: los colores de la marca utilizados
• Fuente: la fuente que se cargó
• Ofrece ediciones
• Sugiere un formato diferente

Referencias

• $SKILL_DIR/references/compositions.md – composiciones disponibles
• $SKILL_DIR/references/formats.md – formatos de salida

Nota para el agente

Sé ordenado: mantén todos los archivos de la ejecución dentro de la carpeta de salida. Limpia los servidores de desarrollo una vez que ya no sean necesarios. Prioriza el vector y la transparencia para los logotipos. Siempre crea un brief.md antes de diseñar.

Termina siempre mostrando el resultado y ofreciendo iterar.