Skill de Document Illustrator
Herramienta de generación de ilustraciones para documentos basada en análisis inteligente de IA. No requiere un formato específico, comprende el contenido automáticamente y genera ilustraciones profesionales.
🎯 Características principales
- ✨ Resumen inteligente por IA: Comprende automáticamente el contenido del documento y extrae los temas principales.
- 🎨 Sin dependencia de formato: Compatible con cualquier formato de documento (Markdown, texto plano, PDF, etc.).
- 📐 Proporciones flexibles: Admite 16:9 (horizontal) y 3:4 (vertical).
- 🖼️ Portada opcional: Puede generar una imagen de portada que resuma todo el documento.
- 🎭 Tres estilos: Tarjeta de vidrio degradado, estilo ticket, ilustración vectorial.
🚀 Cómo usar
Díselo directamente a Codex
Ayúdame a generar ilustraciones para este documento: /ruta/al/documento.md
O:
Quiero generar algunas ilustraciones para este artículo
📝 Flujo de trabajo completo
Paso 1: Codex lee y comprende el documento
Cuando solicitas generar ilustraciones, Codex:
- Usa la herramienta Read para leer el documento completo.
- La IA analiza y comprende el contenido y la estructura del documento.
- Identifica los temas centrales y los puntos clave.
No te preocupes por el formato del documento:
- ✅ Markdown estándar (##, ###)
- ✅ Formato con líneas separadoras (======, ------)
- ✅ Párrafos de texto plano
- ✅ Cualquier otro formato
Paso 2: Opciones de configuración (3 preguntas)
Codex te preguntará tus preferencias:
Pregunta 1: Proporción de la imagen
Por favor, selecciona la proporción de la imagen:
1. 16:9 (horizontal) - Ideal para presentaciones, diapositivas, visualización horizontal.
2. 3:4 (vertical) - Ideal para redes sociales, visualización en móvil, pósters.
Selecciona (1/2):
Pregunta 2: Portada
¿Generar imagen de portada?
La portada resumirá toda la información central del documento y servirá como guía para la serie de ilustraciones.
1. Sí - Generar portada + ilustraciones de contenido
2. No - Solo generar ilustraciones de contenido
Selecciona (1/2):
Pregunta 3: Número de ilustraciones de contenido
¿Cuántas ilustraciones de contenido deseas generar?
Rango sugerido: 3-10
Según el contenido del documento, se recomiendan 6.
Introduce un número:
Paso 3: Codex resume el contenido y lo muestra
Según la cantidad que hayas especificado, Codex resumirá el documento de forma inteligente y te lo mostrará para que confirmes:
📋 Resumen de contenido completado
📄 Contenido de la portada: (si se eligió generarla)
"Evolución del concepto de herramientas de IA: De Rules a Skills"
- Concepto central: Contexto estático vs Contexto dinámico
- Camino evolutivo: Rules → Commands → MCP → Modes → Skills
- Mejores prácticas: Simplificar a dos herramientas centrales
📚 Ilustraciones de contenido (6 en total):
1. El nacimiento y la evolución de Rules
Incluye: Problemas de alucinación en modelos tempranos, función de los archivos rules, concepto de contexto estático
2. Commands y empaquetado de flujos de trabajo
Incluye: Aparición de flujos de trabajo fijos, slash commands, compartición en equipo
3. MCP Servers aportan capacidades dinámicas
Incluye: Integración de herramientas de terceros, autenticación OAuth, problema de expansión del contexto
4. La llegada de Modes y Subagents
Incluye: Prompts de personalidad, modificación de system prompts, diseño de fiabilidad, determinismo de Hooks
5. Skills unifican el contexto dinámico
Incluye: Concepto de Skills, carga dinámica, optimización de herramientas de programación
6. Mejores prácticas y perspectivas futuras
Incluye: Recomendaciones de uso de Rules, exploración de Skills, resumen de conceptos centrales
✓ Todo el contenido ha sido cubierto, sin omisiones
¿Confirmar inicio de generación de ilustraciones? (S/N)
Garantías clave:
- ✅ Contenido completo: Toda la información importante se asignará a alguna imagen.
- ✅ Lógica clara: Segmentación basada en la lógica natural del contenido.
- ✅ Control del usuario: Se muestra el resumen y se espera la confirmación del usuario.
Paso 4: Generar ilustraciones
Tras la confirmación, Codex llama al script de Python para generar las imágenes:
🖼️ Iniciando generación de ilustraciones...
Generando portada...
✓ Guardado: /ruta/al/documento/imagenes/cover.png
Generando ilustración 1/6...
Título: El nacimiento y la evolución de Rules
✓ Guardado: /ruta/al/documento/imagenes/illustration-01.png
Generando ilustración 2/6...
Título: Commands y empaquetado de flujos de trabajo
✓ Guardado: /ruta/al/documento/imagenes/illustration-02.png
...
✨ ¡Completado! Se generaron 7 ilustraciones (1 portada + 6 de contenido)
Paso 5: Resultado
Ubicación de salida: Carpeta imagenes/ en el mismo directorio del documento.
/ruta/a/tu/documento/
└── imagenes/
├── cover.png # Portada (si se eligió generar)
├── illustration-01.png # 1ª ilustración de contenido
├── illustration-02.png # 2ª ilustración de contenido
├── illustration-03.png
├── illustration-04.png
├── illustration-05.png
└── illustration-06.png
🎨 Descripción de los tres estilos
1. Estilo tarjeta de vidrio degradado (gradient-glass)
Características:
- Minimalismo al estilo Apple Keynote
- Diseño glassmorphism
- Base de negro profundo tipo vacío o blanco puro
- Colores degradados tipo aurora
- Objetos 3D de vidrio y efectos brillantes
Casos de uso:
- Introducción de productos tecnológicos
- Informes de análisis de datos
- Perspectivas de tendencias futuras
- Demostración de funciones de producto
2. Estilo ticket (ticket)
Características:
- Diseño de ticket digital minimalista
- Paleta de colores blanco y negro de alto contraste
- Estructura similar a tarjetas de embarque o entradas
- Divisiones geométricas precisas
- Disposición de texto multilingüe y multidireccional
Casos de uso:
- Infografías
- Visualización de datos estadísticos
- Líneas de tiempo y diagramas de flujo
- Resúmenes de puntos clave
3. Estilo ilustración vectorial (vector-illustration)
Características:
- Ilustración vectorial plana
- Líneas de contorno negras de grosor uniforme
- Paleta de colores suaves y retro
- Tratamiento geométrico
- Composición panorámica horizontal
Casos de uso:
- Narración de historias
- Explicación de conceptos
- Contenido educativo
- Promoción de marca
💡 Ejemplos de uso
Ejemplo 1: Flujo completo
Usuario: Ayúdame a generar ilustraciones para ~/blog/ai-tools.md, estilo ticket
Codex: De acuerdo, déjame leer el documento primero...
[Lee el documento, analiza el contenido]
Detecté que el documento tiene aproximadamente 3000 palabras y trata sobre la evolución de herramientas de IA.
Por favor, selecciona la proporción de la imagen:
1. 16:9 (horizontal)
2. 3:4 (vertical)
Usuario: 1
Codex: ¿Generar imagen de portada?
1. Sí
2. No
Usuario: Sí
Codex: ¿Cuántas ilustraciones de contenido deseas generar?
Rango sugerido: 3-10
Según el contenido del documento, se recomiendan 5.
Usuario: 5
Codex: [Muestra los 5 temas resumidos]
¿Confirmar inicio de generación de ilustraciones?
Usuario: S
Codex: [Llama al script de Python para generar 6 imágenes]
✨ ¡Completado! Ilustraciones guardadas en ~/blog/imagenes/
Ejemplo 2: Documento de texto plano
Usuario: Genera ilustraciones para esta nota de texto plano
Codex: [Lee la nota, incluso sin títulos puede entender el contenido]
[Identifica inteligentemente 3 temas centrales]
[Pregunta configuración, muestra resumen, genera ilustraciones]
Ejemplo 3: Cantidad personalizada
Usuario: Quiero 8 imágenes, verticales, sin portada
Codex: De acuerdo, 3:4 vertical, sin portada, 8 ilustraciones de contenido.
[Resume el documento en 8 temas]
[Muestra el resumen, tras confirmación del usuario, genera]
🔧 Detalles técnicos
Especificaciones de imagen
Las siguientes proporciones y resoluciones aplican para Gemini; Nebula image2-4k solo es compatible con 16:9, 3840x2160. Cuando el usuario selecciona Nebula, se usa directamente 4K; si el usuario solicita 2K o imagen vertical, primero se explican las limitaciones y se determina una solución compatible.
| Proporción | Resolución | Casos de uso |
|---|---|---|
| 16:9 | 2560x1440 (2K) | Presentaciones, visualización horizontal |
| 3:4 | 1920x2560 | Redes sociales, visualización vertical |
Resolución 4K opcional:
- 16:9 → 3840x2160
- 3:4 → 2880x3840
Llamadas a la API
- Modelo Gemini:
gemini-3-pro-image-preview(valor predeterminado actual del script) - Modelo Nebula:
gpt-image-2-4k, usando tokens del grupo image2-4k - Costo: Cada imagen = 1 llamada a la API
- Velocidad: Depende de la carga del backend; el tiempo de espera para solicitudes Nebula 4K es de 1800 segundos
Selección de backend y llamada a Nebula
Grupo nanobanana
Cuando el usuario especifica nanobanana, ambos scripts reciben --provider nanobanana.
En el .env unificado se usa la clave dedicada NEBULA_NANOBANANA_API_KEY (token del grupo nanobanana),
no se reutiliza la clave de image2-4k. NEBULA_NANOBANANA_MODEL por defecto es gemini-3.1-flash-image,
se puede especificar otro modelo compatible con el token; ILLUSTRATOR_IMAGE_PROVIDER=nanobanana se puede establecer como predeterminado.
Tanto para imágenes individuales como por lotes, se admiten 16:9 y 3:4; se pueden solicitar 1K, 2K, 4K, por defecto 2K.
Los valores compatibles específicos y los píxeles reales dependen del modelo seleccionado y no aplican la limitación de imagen horizontal 4K de image2-4k.
El .env unificado usa ILLUSTRATOR_SINGLE_RATIO para establecer la proporción predeterminada para imágenes individuales,
ILLUSTRATOR_BATCH_RATIO para la proporción predeterminada para lotes, e ILLUSTRATOR_RESOLUTION para la resolución predeterminada de la solicitud.
Ambos puntos de entrada admiten --ratio y --resolution para anular la configuración. Si no se configura o el valor está vacío, la proporción es 16:9
y la resolución usa el valor predeterminado del backend (2K para Gemini/nanobanana, 4K para image2-4k).
Estas configuraciones se aplican a todos los backends; si entran en conflicto con las limitaciones del backend, se mostrará un error antes de la solicitud, y se debe ajustar la configuración o anular explícitamente.
python -X utf8 scripts/generate_single_image.py --provider nanobanana --title "Tema" --content "Contenido de la ilustración" --style-file styles/ticket.md --ratio 3:4 --resolution 2K --output output/banana.png
python -X utf8 scripts/generate_illustrations.py articulo.md --provider nanobanana --style ticket --level h2 --resolution 2K
Llama a la API nativa POST /v1beta/models/{model}:generateContent de Gemini, decodifica y verifica la imagen desde inlineData,
sin persistir la respuesta Base64 completa. No requiere Google SDK.
La integración actual solo admite generación de texto a imagen; las tareas que caducan no se reenvían automáticamente como tareas facturables.
Consulta README.md y
Documentación oficial de la API para más detalles.
Grupo image2-4k original
Ambos scripts admiten --provider gemini|nebula. Si no se especifica, se lee ILLUSTRATOR_IMAGE_PROVIDER;
si no está configurado, se usa Gemini. Cuando el usuario especifica explícitamente Nebula, se pasa --provider nebula; no se debe cambiar a otro servicio.
Configurar NEBULA_API_KEY en la ruta unificada ~/.agents/skills/document-illustrator/.env, o usar una variable de entorno con el mismo nombre; el token debe pertenecer al grupo image2-4k.
Nebula no requiere clave de Gemini ni SDK de Google, pero sigue necesitando Pillow y python-dotenv.
python -X utf8 scripts/generate_single_image.py --provider nebula --title "Tema" --content "Contenido de ilustración confirmado" --style-file styles/ticket.md --output output/image-01.png --resolution 4K
python -X utf8 scripts/generate_illustrations.py articulo.md --provider nebula --style ticket --level h2 --resolution 4K
El script llama a POST https://img-api.apinebula.ai/v1/images/generations, usando siempre
gpt-image-2-4k, 3840x2160, quality=high, response_format=url.
Prioriza la lectura de URL, compatible con Base64; verifica los píxeles reales antes de guardar y convierte el JPEG del servidor al formato correspondiente a la extensión local.
La respuesta de la API se guarda como <nombre_archivo_imagen>.response.json; si falla la descarga, se reutiliza el enlace temporal para reanudarla.
Cuando la solicitud POST caduca, el estado de la tarea puede ser desconocido y no se reenvía automáticamente; primero se confirma el estado del servidor para evitar facturación duplicada.
HTTP 403 o cuando la conexión no se ha establecido, se intenta el proxy http://127.0.0.1:81.
Actualmente solo se admite generación de texto a imagen; la edición con imagen de referencia no está implementada.
Las instrucciones completas de configuración y los comandos de prueba fuera de línea se encuentran en README.md; los parámetros de la API se basan en la documentación oficial.
Requisitos del entorno
Requeridos:
pip install google-genai pillow python-dotenv
Claves API:
- Codex, Claude y todos los demás agentes leen unificadamente
~/.agents/skills/document-illustrator/.env - En Windows:
%USERPROFILE%\.agents\skills\document-illustrator\.env - Solo se carga ese archivo; sus valores anulan las variables de entorno con el mismo nombre; si el archivo no existe, se usan solo las variables de entorno existentes, sin buscar en otras ubicaciones
- Gemini usa
GEMINI_API_KEY, Nebula usaNEBULA_API_KEY - El grupo nanobanana usa
NEBULA_NANOBANANA_API_KEY; la configuración del modelo se encuentra en la descripción del grupo anterior.
📊 Principios de resumen de contenido
Claude sigue estos principios al resumir el contenido:
1. Prioridad de integridad
- ✅ Toda la información importante se incluye.
- ✅ No se omiten conceptos clave.
- ✅ Se conservan las ideas centrales del texto original.
2. Lógica clara
- Segmentación basada en la lógica natural del contenido.
- El contenido relacionado se agrupa.
- Se mantiene la coherencia narrativa.
3. Distribución equilibrada
- Cada imagen contiene una cantidad similar de información.
- Se evita que una imagen esté demasiado cargada o vacía.
- Se ajusta según la importancia del contenido.
4. Control del usuario
- Se muestra el resumen al usuario para su confirmación.
- El usuario puede solicitar ajustes.
- La generación solo comienza después de la confirmación.
🐛 Solución de problemas
Problema 1: Error de clave API
Mensaje de error:
Error: Invalid API key
Solución:
- Verifica
GEMINI_API_KEYoNEBULA_API_KEYdel backend correspondiente en.env; para Nebula, verifica también el grupo del token. - Asegúrate de que la clave API sea válida y no haya caducado.
- Obtén una nueva clave: https://makersuite.google.com/app/apikey
Problema 2: Resumen de contenido no ideal
Problema: Los temas resumidos no coinciden con lo esperado.
Solución:
- Durante la fase de visualización del resumen, indícale a Codex tus expectativas.
- Codex volverá a resumir y ajustar.
- Confirma que estás satisfecho antes de comenzar la generación.
Problema 3: Fallo en la generación de imágenes
Posibles causas:
- Problemas de conexión de red.
- Cuota de API agotada.
- Contenido demasiado largo que supera el límite.
Solución:
- Verifica la conexión de red.
- Verifica la cuota de API.
- Intenta aumentar el número de imágenes (para distribuir el contenido).
💰 Estimación de costos
| Número de imágenes | Llamadas a la API | Costo estimado |
|---|---|---|
| Sin portada + 3 | 3 | Bajo |
| Con portada + 5 | 6 | Medio |
| Con portada + 10 | 11 | Alto |
Recomendaciones:
- Documentos cortos (<1000 palabras): 3-5 imágenes
- Documentos medianos (1000-3000 palabras): 5-7 imágenes
- Documentos largos (>3000 palabras): 8-10 imágenes
📚 Mejores prácticas
1. Elegir adecuadamente el número de imágenes
Demasiado pocas:
- Cada imagen tiene demasiada información.
- Difícil de entender y recordar.
Demasiadas:
- El contenido se dispersa.
- Aumenta el costo y el tiempo de generación.
Recomendación:
- Elegir según la longitud del documento.
- Cada imagen debe cubrir 1-2 ideas centrales.
2. Elegir la proporción según el uso
16:9 es adecuado para:
- Presentaciones PPT
- Banners de sitios web
- Portadas de videos
- Ilustraciones de blogs (escritorio)
3:4 es adecuado para:
- Redes sociales (Instagram, Xiaohongshu)
- Artículos para móvil
- Diseño de pósters
- Videos verticales
3. Uso de la portada
Escenarios donde se recomienda generar portada:
- Series de artículos (como guía unificada)
- Compartición en redes sociales (como imagen de vista previa)
- Página de inicio del documento (para resumir todo el texto)
Escenarios donde se puede omitir:
- Solo para uso interno.
- La cantidad de imágenes ya es suficiente.
- Se desea reducir costos.
4. Recomendaciones de selección de estilo
Documentos técnicos → Estilo tarjeta de vidrio degradado Informes de datos → Estilo ticket Tutoriales / Historias → Estilo ilustración vectorial Presentaciones de productos → Estilo tarjeta de vidrio degradado
🔄 Cómo funciona
Forma tradicional (obsoleta)
[Código] Lee el documento → Identifica títulos ## ### → Divide mecánicamente
↓
Depende de un formato específico
Fácilmente omite contenido
No es inteligente
Nueva forma (implementación actual)
[Claude] Lee el documento → La IA comprende el contenido → Resume inteligentemente los temas
↓
Sin dependencia de formato
Contenido completo
Control del usuario
Diferencia clave:
- ❌ Forma antigua: Depende de análisis de código, solo procesa formatos estándar.
- ✅ Nueva forma: La IA comprende el contenido, puede procesar cualquier formato.
🎯 Comparación con otras herramientas
| Función | Document Illustrator | Herramientas PPT tradicionales | Generadores de imágenes por IA |
|---|---|---|---|
| Comprender contenido del documento | ✅ Comprensión inteligente por IA | ❌ Requiere entrada manual | ❌ Requiere entrada manual |
| Dependencia de formato | ✅ Sin dependencia de formato | ❌ Depende de formato específico | ✅ Sin dependencia |
| Integridad del contenido | ✅ Verificación automática | ⚠️ Asegurar manualmente | ❌ No se puede garantizar |
| Generación por lotes | ✅ Generar múltiples de una vez | ❌ Una por una | ⚠️ Requiere múltiples entradas |
| Consistencia de estilo | ✅ Mantenimiento automático | ⚠️ Ajuste manual | ⚠️ Requiere repetir prompts |
📞 Obtener ayuda
Si tienes preguntas o sugerencias:
- Pregunta directamente en Codex.
- Consulta el directorio de la skill:
~/.agents/skills/document-illustrator
¡Deja que la IA te ayude a entender y resumir el contenido, generando ilustraciones profesionales! ✨