Ativos de imagem finais
<skill-dir> é a pasta que contém este SKILL.md, e <plugin-root> fica duas pastas acima. Substitua-os pelos caminhos reais nos comandos. (No Claude Code, eles são ${CLAUDE_SKILL_DIR} e ${CLAUDE_PLUGIN_ROOT}.)
Entrada: um ativo ou uma lista, como "ícone de streak freeze" ou "os 6 ícones de recompensa do GDD de daily-quests". Saída: PNGs no caminho de ativos do jogo, cada um registrado com seu prompt e modelo.
Leia primeiro <plugin-root>/shared/conventions.md e a configuração do repositório (seção Art).
GI="<skill-dir>/scripts/gen_image.py" # Python 3 apenas; nunca imprime a chave
python3 "$GI" check # chave + modelo que seria usado, sem custo (execute a partir do repositório do jogo)
python3 "$GI" generate --prompt "…" --out <file.png> [--size WxH] [--background transparent] [--ref <art.png> …] [--log <log.jsonl>]
0. A geração de imagens está ativada para este projeto?
Leia config: Geração de imagens:
on: vá para o passo 1.off: não gere. Use arte existente ou o padrão de placeholder do repositório, e liste os ativos ainda necessários (nome, tamanho, uso) no relatório. Não pergunte novamente.not setou ausente: esta é a primeira imagem para este projeto. Executecheck, depois pergunte com a ferramenta de pergunta:- Se nenhuma chave foi encontrada, a pergunta informa que os ativos finais usam por padrão o GPT Image da OpenAI (a versão mais recente, 2 ou posterior) e que uma chave de API é necessária. As opções são:
- Configurar uma chave agora (Recomendado): mostre as etapas de configuração abaixo e aguarde até o usuário dizer que está pronto. Então execute
checknovamente. Quando estiver pronto, escrevaon. - Não para este projeto: escreva
off (opted out <YYYY-MM-DD>)e continue sem arte gerada. - Agora não: pule imagens desta vez, deixe o campo
not sete pergunte novamente na próxima vez.
- Configurar uma chave agora (Recomendado): mostre as etapas de configuração abaixo e aguarde até o usuário dizer que está pronto. Então execute
- Se uma chave foi encontrada (no
.envdo repositório, no ambiente, ou configurada para outro projeto), a pergunta informa onde foi encontrada e o modelo quecheckescolheu. Secheckdisser que o arquivo.envé rastreado pelo git, avise que a chave está comprometida e deve ser rotacionada, e recomende movê-la para fora do git. As opções são: usar para este projeto (Recomendado, então escrevaon), não para este projeto (off), e agora não.
- Se nenhuma chave foi encontrada, a pergunta informa que os ativos finais usam por padrão o GPT Image da OpenAI (a versão mais recente, 2 ou posterior) e que uma chave de API é necessária. As opções são:
Configuração da chave de API (mostre ao usuário)
- Acesse platform.openai.com → API keys → Create new secret key. Uma chave com escopo de projeto é a melhor.
- Certifique-se de que Billing tenha crédito. Os modelos GPT Image podem pedir que você verifique sua organização (Settings → Organization → General). O acesso pode levar alguns minutos para ser ativado após a verificação.
- Salve a chave nesta máquina. Nunca cole no chat.
- macOS (recomendado): execute no Terminal. Ele pede a chave sem mostrá-la e a armazena no Keychain:
security add-generic-password -U -a "$USER" -s gd-toolkit-openai -w - Apenas este projeto: adicione
OPENAI_API_KEY=…ao.envou.env.localdo repositório. Verifique se o arquivo está no.gitignoreprimeiro. - Em qualquer lugar: adicione
export OPENAI_API_KEY=…ao seu perfil de shell, como~/.zshrc, depois abra um novo terminal. - Ou use um arquivo legível apenas por você:
~/.config/gd-toolkit/openai_api_key(chmod 600).
- macOS (recomendado): execute no Terminal. Ele pede a chave sem mostrá-la e a armazena no Keychain:
- Avise-me quando estiver pronto, e eu verificarei. Essa verificação não custa nada.
Uma chave no Keychain, no shell ou no arquivo de configuração funciona para todos os projetos; uma chave no .env funciona para seu repositório e tem prioridade sobre o Keychain. A escolha on/off é feita por projeto.
1. Planeje os ativos
- Estilo: leia config: Estilo de arte e veja as artes de referência listadas. Passe 1–4 dos ativos existentes mais próximos como
--ref, para que a nova arte combine com o jogo. Descreva o estilo em todos os prompts com as mesmas palavras: paleta, espessura de linha, sombreamento, ângulo de câmera e material. - Especificações: para cada ativo, seu tamanho final, formato, se precisa de transparência, nome do arquivo e caminho (config: Diretório de ativos, mais o padrão de nomenclatura do repositório).
- Mostre a lista, com contagem total e modelo, e gere assim que o usuário aprovar. Uma confirmação cobre o lote.
2. Gere
- Modelo:
--model auto(padrão) usa o modelo gpt-image mais recente, versão 2 ou posterior, que a chave pode usar, preferindo a variante detalhada para arte final.--fast(passado como--prefer fast) é apenas para rascunhos. Se config: Modelo de imagem nomear um modelo, passe-o com--model. - Tamanho: gere no maior quadrado ou proporção mais próxima do modelo, depois reduza para os tamanhos finais (
sips -Z <px>no macOS). Nunca aumente. - Transparência: ícones, itens e sprites precisam de
--background transparent. Se a saída indicar que o modelo rejeitou, a imagem foi gerada opaca: regenere com uma cor de fundo plana e simples nomeada no prompt, remova essa cor e informe no relatório. - Prompt: descreva o assunto, depois o bloco de estilo, depois a composição (centralizado, padding, sem texto a menos que solicitado). Peça para não conter palavras, logotipos ou marcas d'água, a menos que o ativo precise de texto.
- Registre cada geração em config: Log de arte (
--log). Nunca coloque arquivos de metadados ao lado dos ativos entregues.
3. Verifique cada imagem
Olhe para cada imagem antes de mantê-la, usando uma cópia pequena para economizar contexto. Regenere-a, no máximo 3 vezes, se não corresponder às referências de estilo, tiver texto estranho ou artefatos, estiver cortada incorretamente ou for ilegível em seu menor tamanho no jogo. Se ainda falhar, mantenha a melhor e sinalize-a.
4. Relatório
Liste cada ativo com seu caminho, tamanhos, modelo e quaisquer sinalizações. Também forneça os ativos ainda necessários (se a geração estiver off ou pulada), e o caminho do log. Informe que as imagens são geradas por IA, para que o proprietário possa decidir onde isso precisa ser divulgado, como em listagens de loja.