jp-skill-image

O que jp-skill-image faz?

Converte uma solicitação em linguagem natural em uma imagem gerada com Cloudflare Workers AI (@cf/black-forest-labs/flux-1-schnell). Este é o fluxo completo: o usuário descreve o que deseja, Claude faz a engenharia de prompt, o script chama a API da Cloudflare e a imagem é salva localmente como JPG.

Quando aplicar

O usuário quer uma imagem gerada a partir de uma descrição — "gere um logotipo para uma cafeteria", "faça um thumbnail para meu vídeo de IA", "uma foto de um gato cyberpunk". Claude é responsável por converter um pedido vago em um bom prompt antes de gerar.

Não se aplica a: editar uma imagem existente, arte vetorial/SVG ou vídeo.

Passo 0 — SEMPRE verificar o .env primeiro

Antes de executar o script, verifique se as credenciais são resolvidas. O script as procura nesta ordem: variáveis de ambiente reais → .env do diretório atual ou qualquer pai → ~/.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')"

Se faltar alguma variável (novo usuário / projeto recém-clonado), NÃO tente gerar a imagem — primeiro instrua o usuário, em 3 passos curtos, como obtê-las:

1. CF_ACCOUNT_ID: Cloudflare Dashboard → qualquer domínio/projeto → Workers & Pages → Visão Geral (aparece à direita), ou diretamente em https://dash.cloudflare.com/profile/account-id... se não aparecer, use o ID que está visível na URL do dashboard ou na seção Gerenciar Conta da barra lateral esquerda (não "Meu Perfil").
2. CF_API_TOKEN: https://dash.cloudflare.com/profile/api-tokens → Criar Token → Token Personalizado → permissão Account.Workers AI Scripts: Edit → Account Resources: sua conta → Criar.
3. Criar o arquivo .env — na raiz do projeto, ou em ~/.claude/skills/jp-skill-image/.env para funcionar de qualquer pasta — com:

   CF_ACCOUNT_ID=xxxxx
   CF_API_TOKEN=xxxxx
   

Se o projeto usar proxy corporativo para sair para a internet (verificar se existe HTTPS_PROXY em .npmrc ou se requisições a APIs externas falham por timeout), adicione também:

HTTPS_PROXY=<proxy-corporativo>

Uma vez confirmado que as variáveis existem, continue normalmente.

Como executar

De qualquer diretório (a imagem é salva relativa ao diretório atual):

python3 ~/.claude/skills/jp-skill-image/generate.py "<prompt otimizado>" -o <nome-arquivo>.jpg --steps <N>

• "<prompt otimizado>" — o prompt que você escreve (veja abaixo), não as palavras cruas do usuário.
• -o / --output — onde salvar (padrão out.jpg). Use um nome curto e descritivo, ex. coffee-logo.jpg.
• --steps — passos de difusão (padrão 4). flux-schnell é ajustado para poucos passos, mas para a MELHOR qualidade use 8 a menos que o usuário peça velocidade. Nunca use menos de 4.

O script imprime Saved <arquivo> ... se bem-sucedido, ou um erro legível se falhar (inclui o caso de resposta JSON com imagem em base64, já tratada internamente).

O trabalho real do Claude: escrever um prompt de máxima qualidade

O valor deste skill está em que Claude expande a intenção do usuário em um prompt vívido, específico e tecnicamente correto antes de chamar o script. Nunca passe o pedido do usuário como está — sempre o refine primeiro.

Um prompt de alta qualidade para Flux deve nomear, nesta ordem:

1. Sujeito principal — o que está na cena, de forma concreta e sem ambiguidade.
2. Estilo / meio — foto realista, render 3D, vetor plano, aquarela, isométrico, pixel art, etc.
3. Composição e enquadramento — primeiro plano, plano geral, centrado, regra dos terços, ângulo de câmera.
4. Iluminação e atmosfera — hora dourada, neon, luz de estúdio suave, sombras dramáticas, contraluz.
5. Cor e nível de detalhe — paleta específica, fundo, texturas, nível de detalhe ("highly detailed", "clean minimal").
6. Qualidade técnica (para fotos/renders realistas) — termos como "cinematic", "8k", "sharp focus", "professional photography" ajudam o Flux a se aproximar de resultados premium.

Exemplo de transformação:

• Usuário: "um logotipo para uma cafeteria"
• Prompt que você passa: "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"

Regras rígidas:

• Prompt em inglês sempre (Flux responde melhor).
• 1-2 frases, densas em informação, sem enchimento.
• Nunca peça texto/palavras legíveis dentro da imagem — Flux não as renderiza bem.
• Se o usuário não der detalhes suficientes, preencha você as lacunas com as melhores decisões criativas (não pergunte a menos que o sujeito seja realmente ambíguo).
• Use --steps 8 por padrão para maximizar a qualidade; só reduza para 4 se o usuário pedir velocidade explicitamente.

Após gerar

1. Confirme que o arquivo foi salvo (o script imprime o caminho).
2. Diga ao usuário o nome do arquivo e o prompt exato que você usou, para que ele possa ajustar e reexecutar.
3. Se quiser variações, execute novamente com um prompt modificado e um novo -o.

Requisitos técnicos

• CF_ACCOUNT_ID e CF_API_TOKEN resolvidos por alguma das três fontes do Passo 0.
• Python 3.8+. Sem dependências externas — o script usa apenas a biblioteca padrão (urllib), então não é necessário pip install nem venv.
• O script decodifica a resposta base64 da API da Cloudflare e a salva como binário JPG — a resposta não é a imagem diretamente.