josephprada/jp-skill-image

What does jp-skill-image do?

Convierte una petición en lenguaje natural en una imagen generada con Cloudflare Workers AI (@cf/black-forest-labs/flux-1-schnell). Este es el flujo completo: el usuario describe lo que quiere, Claude hace la ingeniería de prompt, el script llama a la API de Cloudflare, y la imagen se guarda localmente como JPG.

Cuándo aplica

El usuario quiere una imagen generada a partir de una descripción — "genera un logo para una cafetería", "hazme un thumbnail para mi video de IA", "una foto de un gato cyberpunk". Claude es responsable de convertir un pedido vago en un buen prompt antes de generar.

No aplica a: editar una imagen existente, arte vectorial/SVG, o video.

Paso 0 — SIEMPRE verificar el .env primero

Antes de ejecutar el script, comprueba que las credenciales se resuelvan. El script las busca en este orden: variables de entorno reales → .env del directorio actual o cualquier padre → ~/.claude/skills/jp-skill-image/.env (fallback global).

python3 -c "import sys; sys.path.insert(0, '$HOME/.claude/skills/jp-skill-image'); from generate import load_credentials; print('OK' if all(load_credentials()) else 'MISSING')"

Si falta alguna variable (usuario nuevo / proyecto recién clonado), NO intentes generar la imagen — primero indícale al usuario, en 3 pasos cortos, cómo obtenerlas:

1. CF_ACCOUNT_ID: Cloudflare Dashboard → cualquier dominio/proyecto → Workers & Pages → Overview (aparece a la derecha), o directo en https://dash.cloudflare.com/profile/account-id... si no aparece ahí, usar el ID que se ve en la URL del dashboard o en la sección Manage Account del sidebar izquierdo (no "My Profile").
2. CF_API_TOKEN: https://dash.cloudflare.com/profile/api-tokens → Create Token → Custom Token → permiso Account.Workers AI Scripts: Edit → Account Resources: tu cuenta → Create.
3. Crear el archivo .env — en la raíz del proyecto, o en ~/.claude/skills/jp-skill-image/.env para que funcione desde cualquier carpeta — con:

   CF_ACCOUNT_ID=xxxxx
   CF_API_TOKEN=xxxxx
   

Si el proyecto usa proxy corporativo para salir a internet (revisar si existe HTTPS_PROXY en .npmrc o si peticiones a APIs externas fallan por timeout), añadir también:

HTTPS_PROXY=<proxy-corporativo>

Una vez confirmado que las variables existen, continúa normalmente.

Cómo ejecutarlo

Desde cualquier directorio (la imagen se guarda relativa al directorio actual):

python3 ~/.claude/skills/jp-skill-image/generate.py "<prompt optimizado>" -o <nombre-archivo>.jpg --steps <N>

• "<prompt optimizado>" — el prompt que tú escribes (ver abajo), no las palabras crudas del usuario.
• -o / --output — dónde guardar (default out.jpg). Usa un nombre corto y descriptivo, ej. coffee-logo.jpg.
• --steps — pasos de difusión (default 4). flux-schnell está afinado para pocos pasos, pero para la MEJOR calidad usa 8 salvo que el usuario pida velocidad. Nunca uses menos de 4.

El script imprime Saved <archivo> ... si tiene éxito, o un error legible si falla (incluye el caso de respuesta JSON con imagen en base64, ya manejado internamente).

El trabajo real de Claude: escribir un prompt de máxima calidad

El valor de esta skill está en que Claude expande la intención del usuario en un prompt vívido, específico y técnicamente correcto antes de llamar al script. Nunca pases el pedido del usuario tal cual — siempre trabájalo primero.

Una prompt de alta calidad para Flux debe nombrar, en este orden:

1. Sujeto principal — qué hay en la escena, de forma concreta y sin ambigüedad.
2. Estilo/medio — foto realista, render 3D, vector plano, acuarela, isométrico, pixel art, etc.
3. Composición y encuadre — primer plano, plano general, centrado, regla de tercios, ángulo de cámara.
4. Iluminación y atmósfera — hora dorada, neón, luz de estudio suave, sombras dramáticas, contraluz.
5. Color y nivel de detalle — paleta específica, fondo, texturas, nivel de detalle ("highly detailed", "clean minimal").
6. Calidad técnica (para fotos/renders realistas) — términos como "cinematic", "8k", "sharp focus", "professional photography" ayudan a Flux a acercarse a resultados premium.

Ejemplo de transformación:

• Usuario: "un logo para una cafetería"
• Prompt que pasas: "minimalist logo of a steaming coffee cup, flat vector illustration, warm brown and cream palette, centered on a clean off-white background, simple bold shapes, modern branding, professional design"

Reglas duras:

• Prompt en inglés siempre (Flux responde mejor).
• 1-2 frases, densas en información, sin relleno.
• Nunca pidas texto/palabras legibles dentro de la imagen — Flux no las renderiza bien.
• Si el usuario no da suficiente detalle, rellena tú los huecos con las mejores decisiones creativas (no preguntes salvo que sea realmente ambiguo el sujeto).
• Usa --steps 8 por defecto para maximizar calidad; solo baja a 4 si el usuario pide velocidad explícitamente.

Después de generar

1. Confirma que el archivo se guardó (el script imprime la ruta).
2. Dile al usuario el nombre del archivo y el prompt exacto que usaste, para que pueda ajustarlo y re-ejecutar.
3. Si quiere variaciones, vuelve a ejecutar con un prompt modificado y un nuevo -o.

Requisitos técnicos

• CF_ACCOUNT_ID y CF_API_TOKEN resueltos por alguna de las tres fuentes del Paso 0.
• Python 3.8+. Sin dependencias externas — el script usa solo la librería estándar (urllib), así que no hace falta pip install ni un venv.
• El script decodifica la respuesta base64 de la API de Cloudflare y la guarda como binario JPG — la respuesta no es la imagen directamente.