mohitagw15856/thumbnail-creator

Habilidad Creador de Miniaturas (vía Gemini)

Genera candidatos para miniaturas de artículos y newsletters actuando como un agente de generación de imágenes dentro de Claude Code. En lugar de cambiar entre herramientas y usar la interfaz web de Gemini una imagen a la vez, esta habilidad hace que Claude realice el ciclo completo: leer el texto, proponer composiciones, escribir prompts adaptados, llamar a la API de Gemini, evaluar los resultados y devolver resultados clasificados con una breve justificación.

El resultado son candidatos de miniatura listos para producción que puedes insertar directamente en tu CMS, herramienta de newsletter o programador de redes sociales.

---

Requisitos Previos

Ambos deben estar en su lugar antes de que la habilidad pueda generar imágenes:

1. Clave API de Gemini

Obtén una clave gratuita en Google AI Studio.

Establécela como variable de entorno:

export GEMINI_API_KEY=<tu-clave>

Para mantenerla entre sesiones, agrégala a tu perfil de shell (~/.zshrc o ~/.bashrc):

echo 'export GEMINI_API_KEY=<tu-clave>' >> ~/.zshrc
source ~/.zshrc

Verifica que esté configurada:

echo $GEMINI_API_KEY

2. Script generate_image.py

Este script debe existir en ./generate_image.py en la raíz del proyecto. La plantilla completa está en la sección Plantilla del Script a continuación. Claude lo verificará y se ofrecerá a crearlo si falta.

Dependencias de Python:

pip install google-generativeai Pillow requests

O con uv:

uv pip install google-generativeai Pillow requests

---

Entradas Requeridas

Claude solicitará estos datos si no se proporcionan:

Entrada	Requerida	Notas
Texto del artículo o URL	Sí	Pega el texto completo del artículo o proporciona una URL para obtenerlo. Se usa para extraer temas, ganchos y puntos clave para la composición.
Colores de marca	Recomendado	Códigos hexadecimales o nombres descriptivos. Ej. #1A1A2E (azul marino), #E94560 (coral). Si no se proporcionan, Claude usa valores neutros predeterminados limpios.
Fuentes / estilo tipográfico	Recomendado	Ej. "sans-serif negrita", "serif editorial", "Neue Haas Grotesk". Se usa en el prompt para guiar el tratamiento del texto.
Descripción de referencia de estilo	Recomendado	Ej. "ilustración plana, minimalista, como el sitio de marketing de Stripe" o "fotorrealista, fondo oscuro, alto contraste". También se puede proporcionar una URL de imagen de estilo.
Dimensiones de salida	No	Predeterminado: 1792x1024 (apaisado, miniatura de artículo estándar). Opciones: 1024x1024 (cuadrado), 1024x1792 (retrato/móvil).
Número de candidatos	No	Predeterminado: 4. Mínimo 1, máximo 8 (límites de API y coste).
Título del artículo (si es diferente del H1)	No	Se usa como elemento de texto principal en los prompts de imágenes.
Selección de candidatos	No	Después de proponer composiciones, Claude pregunta cuáles generar. El usuario puede decir "todos" o elegir por número.

---

Estructura de Salida

Fase 1 — Propuestas de Composición (texto, antes de cualquier llamada a la API)

Claude presenta 3-4 conceptos de composición para aprobación del usuario. Formato:

Conceptos de Composición para: "[Título del Artículo]"

1. AFIRMACIÓN AUDÁZ
   Diseño:     Fondo oscuro a sangre, título grande blanco centrado,
               un solo dato de acento (ej. "3x más rápido") en color de marca debajo
   Ambiente:   Alta autoridad, estilo newsletter
   Ideal para: LinkedIn, encabezados de Substack
   Justificación: La afirmación central del artículo ("X supera a Y por 3x") es lo suficientemente
                  específica como para anclar el visual: los lectores se detienen en los datos.

2. OBJETO CONCEPTUAL
   Diseño:     Ilustración central de objeto (ej. un reloj roto para un artículo sobre pérdida de tiempo),
               título en el tercio superior, fondo de textura mínima
   Ambiente:   Editorial, estilo Medium
   Ideal para: Encabezado de blog, portada de Medium, preencabezado de correo
   Justificación: Da flexibilidad de metáfora visual a los directores de arte; funciona en todos los tamaños.

3. DIVISIÓN DE CONTRASTE
   Diseño:     Mitad izquierda color de marca, mitad derecha blanca o con imagen,
               título en el lado de color, texto secundario en el lado blanco
   Ambiente:   Limpio, profesional, sensación de marca startup
   Ideal para: Newsletter, primera diapositiva de carrusel de LinkedIn
   Justificación: El diseño dividido funciona consistentemente en pruebas A/B de newsletters;
                  el texto es legible en tamaños pequeños.

4. SOLO TIPOGRÁFICO
   Diseño:     Sin ilustración, tratamiento de título sobredimensionado,
               nombre del autor en mayúsculas pequeñas en la parte inferior, separador de regla fina
   Ambiente:   Premium, seguro, editorial
   Ideal para: Substack, Ghost, listas de correo de alta densidad
   Justificación: Funciona cuando la marca tiene una identidad tipográfica fuerte. El más rápido de producir.

¿Qué composiciones deseas que se generen? (Responde con números, ej. "1, 3" o "todos")

Fase 2 — Archivos de Imagen Generados

Después de la generación, Claude guarda los archivos en ./thumbnails/[slug-del-artículo]/:

thumbnails/
└── slug-del-artículo-desde-el-título/
    ├── candidate_01_afirmacion_audaz.png
    ├── candidate_02_objeto_conceptual.png
    ├── candidate_03_division_contraste.png
    ├── candidate_04_tipografico.png
    └── evaluation_report.md

Fase 3 — Tabla Resumen de Evaluación

Claude evalúa cada imagen devuelta mediante visión por computadora y produce:

Evaluación de Miniatura — "[Título del Artículo]"
Generado: 2026-05-27  |  Modelo: Gemini Imagen  |  Dimensiones: 1792x1024

| # | Candidato | Composición | Ajuste a Marca /10 | Legibilidad de Texto /10 | Recomendación |
|---|---|---|---|---|---|
| 1 | candidate_01_afirmacion_audaz.png | Afirmación Audaz | 9 | 8 | ★ Mejor opción — ancla de datos sólida, colores de marca correctos, título legible a 200 px de ancho |
| 2 | candidate_02_objeto_conceptual.png | Objeto Conceptual | 7 | 9 | Buen respaldo — legible, limpio, pero el estilo de ilustración se desvió ligeramente de la marca |
| 3 | candidate_03_division_contraste.png | División de Contraste | 8 | 7 | Funciona bien a tamaño completo; probar a tamaño de miniatura antes de publicar — el texto del lado derecho se aprieta |
| 4 | candidate_04_tipografico.png | Tipográfico | 9 | 10 | El más fuerte para correo — riesgo cero de desviación de marca, completamente basado en texto |

Recomendado para web:          candidate_01_afirmacion_audaz.png
Recomendado para correo/móvil: candidate_04_tipografico.png
Recomendado para redes:       candidate_03_division_contraste.png

Archivos guardados en: ./thumbnails/slug-del-artículo-desde-el-título/

---

Cómo Debe Ejecutar Claude Esta Habilidad

Paso 1 — Ingerir y analizar el artículo

Aceptar el texto del artículo como texto pegado o una URL.

Si se proporciona una URL, obtener la página y extraer:

• El título H1
• Los primeros 3-5 párrafos (el gancho, la afirmación central y los puntos clave)
• Cualquier estadística notable o marcos nombrados mencionados
• El nombre del autor (para composiciones tipográficas)

Si se pega texto, leerlo directamente. Centrarse en:

• El gancho: ¿Cuál es la afirmación inicial o la tensión?
• La tesis central: ¿Cuál es la única cosa que el artículo argumenta o enseña?
• Detalles clave: Cualquier número, marco nombrado o ejemplo concreto que pueda anclar un visual
• Tono: ¿Es formal/autoritario, conversacional/accesible, provocador/basado en desafíos?

Resumir estos hallazgos internamente antes de proponer composiciones: las propuestas deben sentirse adaptadas a este artículo específico, no genéricas.

Paso 2 — Recopilar especificaciones de marca

Preguntar al usuario por las especificaciones de marca si no se proporcionan:

Para generar miniaturas acordes a la marca, necesito algunos detalles:

1. Colores de marca (códigos hex o descripciones) — ej. #1A1A2E, #E94560
2. Preferencia de estilo de fuente — ej. "sans-serif negrita", "serif editorial", "geométrica"
3. Estilo visual — ej. "minimalista plano", "fotorrealista", "ilustrado", "solo tipográfico"
4. Referencias de estilo — describe una marca o publicación cuya estética quieras igualar,
   o comparte una URL de imagen

Si aún no tienes especificaciones de marca, di "usa valores predeterminados limpios" y usaré un estilo
editorial profesional oscuro-sobre-blanco.

Si el usuario dice "usa valores predeterminados limpios", aplicar:

• Fondo: #FFFFFF o #0F0F0F (modo oscuro predeterminado)
• Acento: #2563EB (azul)
• Estilo de fuente: sans-serif geométrico negrita
• Estilo: minimalista plano, sin texturas, alto contraste

Paso 3 — Proponer conceptos de composición

Escribir 3-4 conceptos de composición adaptados al tono y contenido del artículo. Cada concepto debe:

• Tener un nombre (etiqueta corta y memorable)
• Describir el diseño con precisión (dónde va el título, qué elemento visual lo ancla, tratamiento del fondo)
• Indicar el ambiente y el caso de uso para el que es más adecuado
• Incluir una frase de justificación que explique por qué esta composición se ajusta a este artículo específico

Después de presentar los conceptos, preguntar cuáles generar. Esperar la confirmación del usuario antes de realizar cualquier llamada a la API.

Paso 4 — Escribir prompts de generación de imágenes de Gemini

Para cada composición seleccionada, escribir un prompt de generación de imágenes detallado. Los prompts de generación de imágenes siguen una gramática diferente a los prompts de texto: son descriptivos, no instructivos.

Estructura del prompt:

[Sujeto/composición] + [Estilo] + [Paleta de colores] + [Ambiente/iluminación] +
[Tratamiento del texto si lo hay] + [Qué evitar]

Ejemplo de prompt para composición Afirmación Audaz:

Imagen de miniatura de artículo. Texto de título grande y blanco en sans-serif negrita que dice "3x Más Rápido Que
Los Métodos Tradicionales" centrado sobre un fondo azul marino oscuro (#1A1A2E). Pequeño texto de acento coral
(#E94560) debajo leyendo el subtítulo. Diseño plano minimalista, sin degradados, sin elementos de stock,
sin personas. Estilo editorial profesional limpio, alto contraste, formato de encabezado de newsletter,
orientación apaisada 16:9. La composición es tipográfica — el texto es el héroe,
no se requiere ilustración. Evitar: clip art, sombras paralelas, bajo contraste, diseño abarrotado.

Reglas del prompt:

• Incluir códigos hex exactos cuando se proporcionen colores de marca
• Especificar el texto exacto del título que debe aparecer en la imagen
• Nombrar el estilo explícitamente ("diseño plano", "editorial", "fotorrealista") — Gemini responde bien a los nombres de categorías de estilo
• Agregar un prompt negativo ("Evitar: ...") al final para reducir la desviación del estilo de marca
• Mantener los prompts por debajo de 300 palabras — los prompts más largos no producen resultados mejores de manera confiable

Paso 5 — Verificar requisitos previos y ejecutar el script de generación

Antes de llamar a la API, verificar:

# Verificar que la clave API esté configurada
echo $GEMINI_API_KEY

# Verificar que el script exista
ls -la ./generate_image.py

# Verificar dependencias
python3 -c "import google.generativeai, PIL, requests; print('Dependencias OK')"

Si el script falta, ofrecerse a crearlo usando la plantilla en la sección Plantilla del Script a continuación.

Ejecutar el script de generación para cada prompt:

python3 generate_image.py \
  --prompt "tu prompt completo aquí" \
  --output "./thumbnails/slug-del-artículo/candidate_01_afirmacion_audaz.png" \
  --width 1792 \
  --height 1024

O pasar todos los prompts en un archivo de configuración por lotes:

python3 generate_image.py --config ./thumbnails/slug-del-artículo/prompts.json

Paso 6 — Evaluar imágenes generadas

Después de que cada imagen se guarde, examinarla usando visión por computadora. Evaluar en dos dimensiones:

Ajuste a Marca (puntuación /10):

• ¿Son correctos los colores de marca? (1-2 puntos cada uno)
• ¿Coincide el estilo con la estética solicitada? (2 puntos)
• ¿Es el diseño coherente con el resumen de composición? (2 puntos)
• ¿Hay artefactos de IA, texto distorsionado o elementos no deseados? (-1 por problema)

Legibilidad del Texto (puntuación /10):

• ¿Es legible el texto del título a resolución completa? (3 puntos)
• ¿Es legible el texto del título cuando la imagen se escala a 300 px de ancho (tamaño de miniatura)? (3 puntos)
• ¿Hay suficiente contraste entre el texto y el fondo? (2 puntos)
• ¿Está la colocación del texto dentro de las zonas seguras (no cortado en los bordes)? (2 puntos)

Nota: Gemini Imagen a veces renderiza texto con errores ortográficos o formas de letras distorsionadas. Si esto ocurre, anotarlo en la evaluación y sugerir al usuario agregar la superposición de texto manualmente en Canva o Figma.

Paso 7 — Producir el informe de evaluación

Escribir la tabla resumen de evaluación (formato mostrado en la sección Estructura de Salida) y guardarla como evaluation_report.md en la carpeta de salida.

Incluir:

• Una justificación de una línea para cada puntuación
• Una recomendación de mejor opción por caso de uso (web, correo/móvil, redes sociales)
• Cualquier nota de producción (ej. "la representación del texto es imperfecta en candidate_02 — superponer texto manualmente")
• Los prompts completos utilizados, para que el usuario pueda iterar directamente en AI Studio si es necesario

Paso 8 — Ofrecer iteración

Después de entregar los candidatos, ofrecer una ronda de iteración:

¿Quieres iterar sobre alguno de estos?

Opciones:
- Ajustar colores o estilo en un candidato específico
- Probar un concepto de composición diferente
- Cambiar el texto del título
- Re-ejecutar con diferentes parámetros de Gemini (temperatura/semilla diferente)
- Generar variantes adicionales de la mejor opción

Solo dime qué cambiar.

---

Plantilla del Script

Claude debe ofrecerse a escribir este archivo si generate_image.py no está presente. Esta es la plantilla canónica a usar.

#!/usr/bin/env python3
"""
generate_image.py — Envoltorio de Gemini Imagen para la habilidad Creador de Miniaturas.

Uso:
    python3 generate_image.py --prompt "..." --output "./out.png" [--width 1792] [--height 1024]
    python3 generate_image.py --config ./prompts.json

Formato JSON de configuración:
    [
      {
        "prompt": "...",
        "output": "./thumbnails/slug/candidate_01.png",
        "width": 1792,
        "height": 1024
      }
    ]

Requisitos:
    pip install google-generativeai Pillow
"""

import os
import sys
import json
import argparse
import base64
from pathlib import Path

try:
    import google.generativeai as genai
    from google.generativeai import types as genai_types
except ImportError:
    print("ERROR: google-generativeai no está instalado. Ejecuta: pip install google-generativeai")
    sys.exit(1)

try:
    from PIL import Image
    import io
except ImportError:
    print("ERROR: Pillow no está instalado. Ejecuta: pip install Pillow")
    sys.exit(1)


def get_api_key() -> str:
    key = os.environ.get("GEMINI_API_KEY", "")
    if not key:
        print("ERROR: La variable de entorno GEMINI_API_KEY no está configurada.")
        print("Obtén una clave en: https://aistudio.google.com/app/apikey")
        print("Luego ejecuta: export GEMINI_API_KEY=<tu-clave>")
        sys.exit(1)
    return key


def generate_image(
    prompt: str,
    output_path: str,
    width: int = 1792,
    height: int = 1024,
) -> bool:
    """
    Llama a Gemini Imagen para generar una sola imagen y guardarla en output_path.
    Retorna Verdadero si tiene éxito, Falso en caso contrario.
    """
    try:
        api_key = get_api_key()
        genai.configure(api_key=api_key)

        model = genai.GenerativeModel(
            model_name="models/imagen-3.0-generate-001"
        )

        response = model.generate_content(
            prompt,
            generation_config=genai_types.GenerationConfig(
                temperature=1.0,
            ),
        )

        if not response.candidates:
            print(f"ERROR: No se generaron candidatos para el prompt: {prompt[:50]}...")
            return False

        image_data = response.candidates[0].content.parts[0].inline_data.data
        Image.open(io.BytesIO(image_data)).save(output_path)
        print(f"Imagen guardada en: {output_path}")
        return True

    except Exception as e:
        print(f"ERROR al generar imagen: {e}")
        return False


def main():
    parser = argparse.ArgumentParser(
        description="Genera imágenes usando Gemini Imagen"
    )
    parser.add_argument(
        "--prompt",
        type=str,
        help="El prompt de texto para generar la imagen.",
    )
    parser.add_argument(
        "--output",
        type=str,
        help="Ruta del archivo de salida para la imagen (ej. ./out.png, ./thumbnails/slug/img.png).",
    )
    parser.add_argument(
        "--width",
        type=int,
        default=1792,
        help="Ancho de la imagen en píxeles (predeterminado: 1792).",
    )
    parser.add_argument(
        "--height",
        type=int,
        default=1024,
        help="Altura de la imagen en píxeles (predeterminado: 1024).",
    )
    parser.add_argument(
        "--config",
        type=str,
        help="Ruta a un archivo JSON con una lista de configuraciones de prompts.",
    )

    args = parser.parse_args()

    if args.config:
        with open(args.config, "r") as f:
            configs = json.load(f)
        for config in configs:
            generate_image(
                prompt=config["prompt"],
                output_path=config["output"],
                width=config.get("width", 1792),
                height=config.get("height", 1024),
            )
    elif args.prompt and args.output:
        generate_image(
            prompt=args.prompt,
            output_path=args.output,
            width=args.width,
            height=args.height,
        )
    else:
        parser.print_help()
        sys.exit(1)


if __name__ == "__main__":
    main()

---

Consejos de Uso

• Comienza con un artículo breve: Para tu primera prueba, pega un artículo de 500-800 palabras. Así verás el flujo completo sin esperar mucho tiempo de procesamiento.
• Proporciona especificaciones de marca: Incluso un solo código de color de acento mejora significativamente la coherencia visual de los resultados.
• Especifica el caso de uso: Dinos si las miniaturas son para Twitter/LinkedIn (cuadrado), YouTube (16:9) o la portada de un newsletter (16:9 vertical centrado). Las dimensiones predeterminadas son para artículos.
• Revisa la legibilidad a tamaño reducido: Una miniatura que se ve bien a tamaño completo puede volverse ilegible cuando se reduce a 300 px. La evaluación de Claude verifica esto.
• Itera en lotes: Si estás produciendo miniaturas para una serie, mantén los mismos colores y estilo de fuente en todos los artículos para que la serie parezcozca coherente.
• Problemas con el texto: Gemini Imagen a veces genera texto con errores. Si esto ocurre, usar la superposición de texto manualmente en Canva es más rápido que re-generar.

---

Límites y Consideraciones

• Límites de velocidad de API: La API de Gemini Imagen tiene límites de velocidad. Si generas más de 4 imágenes, puede haber una pausa de 10-15 segundos entre cada una.
• Costes: La API gratuita tiene cuota diaria. Para trabajo de producción, Google Cloud proporciona niveles de pago.
• Calidad de imagen: Gemini Imagen 3.0 maneja bien composiciones tipográficas y de diseño plano; el fotorrealismo con texto superpuesto a veces muestra artefactos, especialmente con fondos complejos.
• Precisión del texto: La generación de texto dentro de imágenes sigue siendo un desafío para los modelos generativos. Las composiciones tipográficas pueden requerir retoques manuales para producción de alta calidad.
• Atribución de estilo: Si proporcionas una URL de imagen de referencia de estilo, la usaremos como entrada. Ten en cuenta que es posible que la API no duplique exactamente el estilo; úsala como inspiración general, no como plantilla exacta.