doggy8088/imagegen-mai

Habilidade de Geração de Imagens para Microsoft Foundry MAI-Image

Gera ou edita imagens para o projeto atual (por exemplo, ativos de site, ativos de jogo, maquetes de UI, maquetes de produto, wireframes, design de logotipo, imagens fotorrealistas ou infográficos) com implantações MAI-Image no Microsoft Foundry.

Neste arquivo, <skill-dir> significa o diretório que contém este SKILL.md.

Modo de execução e regras

Esta skill usa a CLI empacotada em <skill-dir>/scripts/image_gen.js. O host do agente não fornece ferramentas internas de geração ou visualização de imagens para este fluxo de trabalho, portanto, não faça referência ou tente usar funções internas inexistentes.

A CLI expõe três subcomandos:

• generate
• edit
• generate-batch

Regras:

• Use scripts/image_gen.js para solicitações normais de geração e edição de imagens.
• A CLI suporta apenas modelos da série MAI-Image. Nunca direcione GPT Image, DALL-E ou outros modelos por meio dela.
• A implantação padrão é IMAGEGEN_MAI_IMAGE_DEPLOYMENT, ou MAI-Image-2.6-Flash quando não definida. Nunca mude silenciosamente para uma implantação diferente. Pergunte primeiro ao usuário, a menos que o usuário já tenha solicitado explicitamente aquele modelo.
• Os modelos MAI-Image sempre retornam um PNG opaco. Para imagens transparentes, use o fluxo de chroma-key abaixo e informe ao usuário que o recorte é feito localmente.
• A palavra batch por si só não requer generate-batch. Use generate-batch quando uma solicitação de múltiplos ativos for naturalmente representada como um lote JSONL; caso contrário, execute comandos CLI individuais.
• Chamadas de API ao vivo exigem credenciais MAI e acesso à rede.
• Use o fluxo de trabalho empacotado scripts/image_gen.js. Não crie executores SDK avulsos.
• Nunca modifique scripts/image_gen.js. Se algo estiver faltando, pergunte ao usuário antes de fazer qualquer outra coisa.

Política de saída:

• Grave os ativos gerados diretamente no caminho solicitado, ou em output/imagegen/ quando o usuário não especificar um caminho.
• Se a imagem for destinada ao projeto atual, salve a imagem final selecionada no espaço de trabalho antes de finalizar.
• Não sobrescreva um ativo existente, a menos que o usuário tenha solicitado explicitamente a substituição; caso contrário, crie um nome de arquivo versionado, como hero-v2.png ou item-icon-edited.png.

Orientações compartilhadas de prompt estão em references/prompting.md e references/sample-prompts.md.

Documentação/recursos da CLI:

• references/cli.md
• references/image-api.md
• references/codex-network.md
• scripts/image_gen.js

Auxiliar de pós-processamento local:

• <skill-dir>/scripts/remove_chroma_key.js: remove um fundo chroma-key plano de uma imagem gerada e escreve um PNG com alfa. Prefira amostragem automática de key, soft matte e despill para bordas anti-serrilhadas.

Quando usar

• Gerar uma nova imagem (arte conceitual, foto de produto, capa, hero de site, pôster)
• Gerar uma nova imagem que dependa de informações do mundo real atuais (use --web-grounding)
• Editar uma imagem existente (remoção ou substituição de objetos, mudança de atributos, inpainting, atualizações de texto, alterações de iluminação ou clima, limpeza de artefatos)
• Combinar até cinco imagens de referência em um resultado (consistência de produto, personagem ou ativo de marca)
• Produzir muitos ativos ou variantes para uma tarefa

Quando não usar

• Estender ou corresponder a um conjunto de ícones SVG/vetoriais, sistema de logotipos ou biblioteca de ilustrações existente dentro do repositório
• Criar formas simples, diagramas, wireframes ou ícones que são melhor produzidos diretamente em SVG, HTML/CSS ou canvas
• Fazer uma edição de ativo local pequena quando o arquivo de origem já existe em um formato nativo editável
• Qualquer tarefa em que o usuário claramente queira saída determinística nativa de código em vez de um bitmap gerado
• Saída maior que cerca de 1.5K (o limite do MAI-Image-2.6 é 2.359.296 pixels, por exemplo 1536x1536); informe o usuário sobre o limite em vez de aumentar a resolução silenciosamente

Árvore de decisão

Pense em duas perguntas separadas:

1. Intenção: é uma imagem nova ou uma edição de uma imagem existente?
2. Estratégia de execução: é um ativo ou muitos ativos/variantes?

Intenção:

• Se o usuário deseja modificar uma imagem existente preservando partes dela, trate a solicitação como edit.
• Se o usuário fornecer imagens como referências de estilo, composição, clima ou assunto e quiser que elas sejam refletidas no resultado, use edit com essas imagens como referências (a API de gerações MAI não aceita imagens).
• Se o usuário não fornecer imagens, trate a solicitação como generate.

Semântica de edição:

• O modo de edição da CLI aceita de um a cinco arquivos PNG ou JPEG locais por meio de sinalizações --image repetidas.
• Se o usuário fornecer imagens anexadas ou referências da conversa, salve-as localmente primeiro se o ambiente suportar isso; caso contrário, peça ao usuário os caminhos dos arquivos locais.
• A ordem das imagens é significativa, então rotule cada imagem por índice e função no prompt.
• Para edições, preserve invariáveis agressivamente e salve de forma não destrutiva por padrão.
• Edições não são documentadas para MAI-Image-2 e MAI-Image-2e, e a CLI as bloqueia; use uma implantação MAI-Image-2.5 ou MAI-Image-2.6 para edições.

Estratégia de execução:

• Use o subcomando generate-batch da CLI para muitos prompts/ativos quando o lote JSONL for o fluxo de trabalho mais claro.
• A API MAI retorna uma imagem por solicitação e não possui parâmetro n. Para variantes, execute comandos separados ou trabalhos em lote separados com nomes out distintos.
• Os limites de taxa são baixos (por exemplo, 6 solicitações por minuto para MAI-Image-2.6-Flash no Nível 1). Mantenha --concurrency no padrão de 2, a menos que o usuário saiba sua cota.

Presuma que o usuário deseja uma nova imagem, a menos que ele peça claramente para alterar uma existente.

Fluxo de trabalho

1. Decida o subcomando da CLI: generate, edit ou generate-batch.
2. Decida se a saída é apenas para visualização ou destinada a ser consumida pelo projeto atual.
3. Decida a estratégia de execução: ativo único vs comandos CLI repetidos vs generate-batch da CLI.
4. Colete as entradas antecipadamente: prompt(s), texto exato (ipsis litteris), lista de restrições/evitar, tamanho alvo ou proporção de aspecto, e quaisquer imagens de entrada.
5. Para cada imagem de entrada, rotule sua função explicitamente:
   • imagem de referência
   • alvo de edição
   • entrada de suporte de inserção/estilo/composição
6. Se o usuário pediu uma foto, ilustração, sprite, imagem de produto, banner ou outro ativo explicitamente raster, use esta skill em vez de substituir por placeholders SVG/HTML/CSS. Se a solicitação for para um ícone, logotipo ou gráfico de UI que deve corresponder a ativos SVG/vetoriais/código existentes no repositório, prefira editá-los diretamente.
7. Aumente o prompt com base na especificidade:
   • Se o prompt do usuário já for específico e detalhado, normalize-o em uma especificação clara sem adicionar requisitos criativos.
   • Se o prompt do usuário for genérico, adicione aumento criterioso apenas quando melhorar materialmente a qualidade da saída.
8. Escolha o tamanho. Use --size LARGURAxALTURA para um alvo conhecido, ou --auto-aspect-ratio (família MAI-Image-2.6) quando a composição deve decidir. Adicione --web-grounding (família MAI-Image-2.6) quando o prompt depender de entidades, lugares ou eventos do mundo real atuais.
9. Execute scripts/image_gen.js com a implantação padrão.
10. Para solicitações de saída transparente, siga o fluxo de chroma-key abaixo.
11. Inspecione as saídas e valide: assunto, estilo, composição, precisão do texto e itens de invariáveis/evitar.
12. Itere com uma única alteração direcionada e depois verifique novamente.
13. Para trabalho apenas de visualização, escreva em output/imagegen/ a menos que o usuário tenha pedido um local diferente.
14. Para trabalho vinculado ao projeto, escreva o artefato no espaço de trabalho e atualize qualquer código ou referências consumidoras.
15. Para lotes ou solicitações de múltiplos ativos, persista cada entrega final solicitada no espaço de trabalho, a menos que o usuário tenha pedido explicitamente para manter as saídas apenas para visualização. Variantes descartadas não precisam ser mantidas, a menos que solicitado.
16. Use a documentação da CLI para implantação, tamanho, auto_aspect_ratio, web_grounding, caminhos de saída e configuração de rede.
17. Sempre informe o(s) caminho(s) final(is) salvo(s) para qualquer ativo vinculado ao espaço de trabalho, mais o prompt final ou conjunto de prompts.

Solicitações de imagem transparente

Os modelos MAI-Image sempre retornam um PNG opaco e não têm opção de fundo transparente. Crie ativos transparentes com uma imagem de origem chroma-key e remoção local.

Sequência:

1. Use scripts/image_gen.js generate (ou edit para uma imagem existente) para colocar o assunto solicitado em um fundo chroma-key sólido perfeitamente plano.

2. Escolha uma cor de key que seja improvável de aparecer no assunto: padrão #00ff00, use #ff00ff para assuntos verdes e evite #0000ff para assuntos azuis.

3. Mantenha a imagem de origem chroma-key no espaço de trabalho ou em tmp/imagegen/.

4. Execute o auxiliar empacotado:

   node "<skill-dir>/scripts/remove_chroma_key.js" \
     --input <origem> \
     --out <final.png> \
     --auto-key border \
     --soft-matte \
     --transparent-threshold 12 \
     --opaque-threshold 220 \
     --despill
   

5. Valide se a saída tem um canal alfa, cantos transparentes, cobertura plausível do assunto e nenhuma franja de cor key óbvia. Componha-a sobre um fundo claro e um escuro para verificar halos. Se uma franja fina permanecer, tente novamente com --edge-contract 1; use --edge-feather 0.25 apenas quando a borda estiver visivelmente em escada e o assunto não for brilhante ou reflexivo.

6. Salve o PNG alfa final no projeto se o ativo estiver vinculado ao projeto.

Solicite pedidos de chroma-key como este:

Crie o assunto solicitado em um fundo chroma-key #00ff00 sólido perfeitamente plano para remoção de fundo.
O fundo deve ser de uma cor uniforme, sem sombras, gradientes, textura, reflexos, plano de chão ou variação de iluminação.
Mantenha o assunto completamente separado do fundo com bordas nítidas e amplo preenchimento.
Não use #00ff00 em nenhuma parte do assunto.
Sem sombra projetada, sombra de contato, reflexo, marca d'água ou texto, a menos que explicitamente solicitado.

O chroma keying é inadequado para cabelo, pelos, penas, fumaça, vidro, líquidos, materiais translúcidos, objetos reflexivos e sombras suaves. Informe o usuário sobre esse limite antes de prometer um recorte limpo para esses assuntos.

Aumento de prompt

Reformate os prompts do usuário em uma especificação estruturada e orientada à produção. Torne o objetivo do usuário mais claro e acionável, mas não adicione detalhes cegamente.

Trate isso como orientação de modelagem de prompt, não um esquema fechado. Use apenas as linhas que ajudam e adicione uma linha curta extra rotulada quando melhorar materialmente a clareza.

Política de especificidade

Use a especificidade do prompt do usuário para decidir quanto aumento é apropriado:

• Se o prompt já for específico e detalhado, preserve essa especificidade e apenas normalize/estruture-o.
• Se o prompt for genérico, você pode adicionar aumento criterioso quando melhorar materialmente o resultado.

Aumentos permitidos:

• dicas de composição ou enquadramento
• dicas de nível de polimento ou uso pretendido
• orientação prática de layout
• concretude de cena razoável que suporte a solicitação declarada

Aumentos não permitidos:

• personagens ou objetos extras que não são implícitos pela solicitação
• nomes de marcas, slogans, paletas ou batidas narrativas que não são implícitas
• posicionamento arbitrário específico de lado, a menos que o layout circundante o suporte

Taxonomia de caso de uso (slugs exatos)

Classifique cada solicitação em um destes baldes e mantenha o slug consistente entre prompts e referências.

Generate:

• photorealistic-natural: cenas de estilo de vida casuais/editoriais com textura real e iluminação natural.
• product-mockup: fotos de produto/embalagem, imagens de catálogo, conceitos de mercadoria.
• ui-mockup: maquetes e wireframes de interface de aplicativo/web; especifique a fidelidade desejada.
• infographic-diagram: diagramas/infográficos com layout estruturado e texto.
• scientific-educational: explicadores de sala de aula, diagramas científicos e visuais de aprendizagem com rótulos necessários e restrições de precisão.
• ads-marketing: conceitos de campanha e criativos de anúncio com público, posição de marca, cena e slogan/texto exato.
• productivity-visual: visuais de negócios para slides, gráficos, fluxos de trabalho e dados pesados.
• logo-brand: exploração de logotipo/marca, amigável para vetor.
• illustration-story: quadrinhos, arte de livro infantil, cenas narrativas.
• stylized-concept: arte conceitual orientada por estilo, renders 3D/estilizados.
• historical-scene: cenas historicamente precisas/com conhecimento mundial.

Edit:

• text-localization: traduzir/substituir texto na imagem, preservar layout.
• identity-preserve: experimentar, pessoa em cena; travar rosto/corpo/pose.
• precise-object-edit: remover/substituir um elemento específico (incluindo trocas internas).
• lighting-weather: apenas mudanças de hora do dia/estação/atmosfera.
• background-extraction: recorte limpo via um fundo chroma-key plano mais remoção local com scripts/remove_chroma_key.js.
• style-transfer: aplicar estilo de referência enquanto muda assunto/cena.
• compositing: inserção/mesclagem de múltiplas imagens com iluminação/perspectiva combinadas (até cinco imagens).
• sketch-to-render: desenho/arte linear para render fotorrealista.

Esquema compartilhado de prompt

Use a seguinte especificação rotulada como estrutura compartilhada de prompt para ambos os modos de alto nível:

Caso de uso: <slug da taxonomia>
Tipo de ativo: <onde o ativo será usado>
Solicitação principal: <prompt principal do usuário>
Imagens de entrada: <Imagem 1: função; Imagem 2: função> (opcional)
Cena/fundo: <ambiente>
Assunto: <assunto principal>
Estilo/mídia: <foto/ilustração/3D/etc>
Composição/enquadramento: <aberto/fechado/de cima para baixo; posicionamento>
Iluminação/clima: <iluminação + clima>
Paleta de cores: <anotações de paleta>
Materiais/texturas: <detalhes de superfície>
Texto (ipsis litteris): "<texto exato>"
Restrições: <deve manter/deve evitar>
Evitar: <restrições negativas>

Notas:

• Tipo de ativo e Imagens de entrada são estrutura de prompt, não sinalizações CLI dedicadas.
• Cena/fundo refere-se ao cenário visual.
• Notas de execução como tamanho, auto_aspect_ratio, web_grounding e caminhos de saída pertencem ao caminho CLI, não ao texto do prompt.

Regras de aumento:

• Mantenha-o curto.
• Adicione apenas os detalhes necessários para melhorar materialmente o prompt.
• Para edições, liste explicitamente invariáveis (mude apenas X; mantenha Y inalterado).
• Se algum detalhe crítico estiver faltando e bloquear o sucesso, faça uma pergunta; caso contrário, prossiga.

Exame

…

[truncado para tradução]