Enseñando a Claude Code a Pintar: Una Skill de Edición de Imágenes con Estado Construida sobre Gemini y MCP

TL;DR: nb2lite-skill-claude envuelve el modelo gemini-3.1-flash-lite-image de Google en un pequeño servidor FastMCP y lo empaqueta como una skill de Claude Code. Escribes “genera una imagen de una cocina cyberpunk” en Claude Code, y simplemente… lo hace. Luego dices “agrega un letrero de neón de RAMEN” y edita la misma imagen sin necesidad de volver a describir toda la escena.

El problema: la mayoría de los generadores de imágenes no tienen memoria

La mayoría de los flujos de generación de imágenes son sin estado. Envías un prompt, recibes píxeles, y el modelo olvida inmediatamente todo. Si quieres ajustar el resultado, tienes que volver a describir la escena completa y rezar para que el personaje, la iluminación y la composición sobrevivan al viaje de ida y vuelta. (spoiler: no lo hacen.)

Google’s Nano Banana 2 Lite — el apodo amigable para gemini-3.1-flash-lite-image — ofrece un enfoque diferente. Es un modelo de imágenes de alta eficiencia con generaciones en menos de 2 segundos, renderizado de texto sólido en más de 25 idiomas, y — la característica estrella — soporte para la API de Interacciones con estado, que permite iterar sobre una imagen a través de múltiples turnos mientras el modelo mantiene el contexto visual del lado del servidor.

Este repositorio conecta esa capacidad con Claude Code, permitiendo que tu agente de codificación genere y refine imágenes de forma iterativa como parte natural de una sesión. Viene en dos componentes:

Un servidor MCP (Model Context Protocol) (nb2lite-agent, una aplicación FastMCP de un solo archivo en server.py) que expone exactamente cuatro herramientas.
Una skill de Claude Code (nb2lite-image) que le enseña a Claude cuándo y cómo usar esas herramientas correctamente.

La API de Interacciones: imágenes con memoria

La API de Interacciones es el endpoint con estado de Gemini. El ciclo principal funciona así:

Llamas a client.interactions.create(...) con un prompt y store=True.
La respuesta incluye un interaction_id — un identificador del contexto visual del turno, persistido en los servidores de Google.
En la siguiente llamada, pasas previous_interaction_id, y el modelo edita el lienzo existente — preservando personaje, estilo, iluminación y continuidad de píxeles.

Así que en lugar de esto (sufrimiento sin estado):

“Un zorro de acuarela en un bosque al amanecer, niebla, luz suave, usando una bufanda roja, tres abedules a la izquierda, y ahora también sosteniendo una linterna”

…escribes esto:

“Agrega una linterna en su pata.”

Eso es todo. El contexto almacenado se encarga del resto.

Detalles prácticos que el servidor maneja por ti:

Cada turno devuelve un nuevo ID de interacción. Encadena siempre el más reciente; editar desde un ID desactualizado bifurca silenciosamente tu sesión desde un estado anterior (un bug sutil y muy molesto si lo haces manualmente).
La relación de aspecto se elige en la generación (1:1, 16:9, 9:16, 4:3, 3:4) y se hereda en ediciones con estado — cambiarla a mitad de sesión degrada la continuidad de píxeles, así que la herramienta de edición deliberadamente no acepta una nueva.
Niveles de pensamiento: low (por defecto, borradores rápidos) o high (renderizado complejo, diseño de texto preciso, composición de personajes).

¿Qué es MCP en un minuto?

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto para conectar asistentes de IA con herramientas y datos. Antes de MCP, darle a un modelo acceso a algún servicio implicaba escribir una integración personalizada para cada asistente — N asistentes × M servicios, todos reinventando la misma tubería. MCP simplifica esto: un autor de herramientas escribe un servidor MCP que expone herramientas tipadas, y cualquier cliente compatible con MCP (Claude Code, Claude Desktop y muchos otros) puede descubrirlas y llamarlas sin código de integración por cliente.

El servidor nb2lite-agent expone exactamente cuatro herramientas:

Herramienta	Qué hace
`generate_image`	Texto → imagen de 1K. Guarda localmente, devuelve la ruta + un ID de interacción.
`edit_image`	Edición con estado: toma el ID de interacción anterior + una descripción de solo el cambio.
`edit_local_image`	Sube cualquier archivo de imagen local inline (base64) y aplica una edición.
`get_help`	Reporta la configuración en vivo: estado de la API key, modelo activo, directorio de salida.

¿Y qué es una skill de Claude Code?

Si MCP son las manos (las herramientas que Claude puede llamar físicamente), una skill es la memoria muscular — un archivo markdown (SKILL.md) más recursos empaquetados que se cargan en el contexto de Claude y le enseñan el flujo de trabajo: qué herramienta usar, en qué orden, con qué restricciones.

Para nb2lite-image, la skill codifica cosas como:

Llama a get_help primero al diagnosticar problemas de configuración.
Mantén los prompts de edición incrementales: describe el cambio, no la escena.
Siempre encadena el ID de interacción más reciente.
Las generaciones son facturables — agrupa ediciones relacionadas y prefiere thinking_level: low para borradores.

Cómo instalarlo: la edición “solo quiero que funcione”

Necesitas tres cosas: Python 3.10+, Claude Code y una API key de Gemini (gratis desde Google AI Studio).

Ruta A: El marketplace de plugins (menos trabajo)

Dentro de Claude Code, escribe:

/plugin marketplace add xbill9/nb2lite-skill-claude
/plugin install nb2lite-image@nb2lite-skill-claude

Ruta B: Clonar e iniciar

git clone https://github.com/xbill9/nb2lite-skill-claude.git
cd nb2lite-skill-claude
./init.sh

Ruta C: Docker (nada más que Docker en el host)

claude mcp add nb2lite-agent --env GEMINI_API_KEY="$(cat ~/gemini.key)" -- \
  docker run --rm -i -e GEMINI_API_KEY -v "$PWD:$PWD" -w "$PWD" xbill9/nb2lite-agent

Ejemplos: una sesión en la práctica

Una vez instalado, interactúas en lenguaje natural:

Tú: “Genera una cabaña acogedora en un bosque nevado al atardecer, 16:9.”

Claude llama a generate_image(prompt="...", aspect_ratio="16:9", thinking_level="low") y guarda la imagen.

Tú: “Bien. Agrega humo saliendo de la chimenea.”

Claude llama a edit_image(previous_interaction_id="...", edit_prompt="agrega humo suave saliendo de la chimenea") y edita la misma imagen.

Tú: “Ahora haz que sea de noche, con aurora boreal en el cielo.”

Misma herramienta, ID más reciente, y la cabaña, los árboles y el humo permanecen intactos — solo cambia el cielo. Sin volver a prompts, sin ruleta de continuidad.

Dogfooding: la imagen de portada 🐕🍖

La imagen de portada de este artículo fue generada por la misma skill que el artículo describe, desde una sesión de Claude Code dentro del repositorio. Una sola llamada a la herramienta, primer intento, sin retoques.

El texto se renderizó correctamente, la ilustración explica el ciclo de edición con estado mejor que cualquier diagrama, y si quisieran cambiar el color de acento, no regenerarían — simplemente editarían con edit_image y ese ID de interacción.

Esa es la diferencia entre “esto debería funcionar” y “esto lo uso todos los días para enviar código a producción.”

“Dogfooding es la credibilidad más barata que existe: ninguna galería seleccionada, ninguna letra pequeña de ‘los resultados pueden variar’ — la salida real de la herramienta es literalmente lo primero que ves al abrir este artículo.”

Enlaces

Repositorio: github.com/xbill9/nb2lite-skill-claude (Apache-2.0)
Imagen Docker: hub.docker.com/r/xbill9/nb2lite-agent
Referencia API de Interacciones: ai.google.dev/api/interactions-api
Model Context Protocol: modelcontextprotocol.io

Este es un proyecto comunitario de terceros, no afiliado ni respaldado por Anthropic o Google. Trae tu propia API key de Gemini — y recuerda que las generaciones son facturables, así que haz borradores en low y guarda high para el resultado final.

Sigue explorando estos temas en el blog de DojoFullStack. Si te apasiona la intersección entre IA, automatización y desarrollo de software, tenemos artículos sobre MCP, agentes de código y herramientas de productividad que te van a encantar.