doggy8088/imagegen-mai

Skill de Generación de Imágenes para Microsoft Foundry MAI-Image

Genera o edita imágenes para el proyecto actual (por ejemplo, activos de sitio web, activos de juego, maquetas de UI, maquetas de producto, wireframes, diseño de logotipos, imágenes fotorrealistas o infografías) con despliegues de MAI-Image en Microsoft Foundry.

En este archivo, <skill-dir> significa el directorio que contiene este SKILL.md.

Modo de ejecución y reglas

Este skill utiliza la CLI incluida en <skill-dir>/scripts/image_gen.js. El host del agente no proporciona herramientas integradas de generación o visualización de imágenes para este flujo de trabajo, por lo tanto, no haga referencia ni intente usar funciones integradas inexistentes.

La CLI expone tres subcomandos:

• generate
• edit
• generate-batch

Reglas:

• Use scripts/image_gen.js para solicitudes normales de generación y edición de imágenes.
• La CLI solo admite modelos de la serie MAI-Image. Nunca enrute GPT Image, DALL-E u otros modelos a través de ella.
• El despliegue predeterminado es IMAGEGEN_MAI_IMAGE_DEPLOYMENT, o MAI-Image-2.6-Flash cuando no está configurado. Nunca cambie silenciosamente a un despliegue diferente. Pregunte primero al usuario, a menos que el usuario ya haya solicitado explícitamente ese modelo.
• Los modelos de imagen MAI siempre devuelven un PNG opaco. Para imágenes transparentes, use el flujo de trabajo de clave cromática a continuación e informe al usuario que el recorte se realiza localmente.
• La palabra batch por sí sola no requiere generate-batch. Use generate-batch cuando una solicitud de múltiples activos se represente naturalmente como un lote JSONL; de lo contrario, ejecute comandos CLI individuales.
• Las llamadas API en vivo requieren credenciales MAI y acceso a la red.
• Use el flujo de trabajo incluido scripts/image_gen.js. No cree ejecutores SDK independientes.
• Nunca modifique scripts/image_gen.js. Si falta algo, pregunte al usuario antes de hacer cualquier otra cosa.

Política de salida:

• Escriba los activos generados directamente en la ruta solicitada, o en output/imagegen/ cuando el usuario no especifique una ruta.
• Si la imagen está destinada al proyecto actual, guarde la imagen final seleccionada en el espacio de trabajo antes de finalizar.
• No sobrescriba un activo existente a menos que el usuario haya solicitado explícitamente el reemplazo; en su lugar, cree un nombre de archivo versionado hermano como hero-v2.png o item-icon-edited.png.

La guía de prompts compartida se encuentra en references/prompting.md y references/sample-prompts.md.

Documentos/recursos de la CLI:

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

Ayudante de posprocesamiento local:

• <skill-dir>/scripts/remove_chroma_key.js: elimina un fondo de clave cromática plano de una imagen generada y escribe un PNG con canal alfa. Prefiera el muestreo automático de clave, el mate suave y el despill para bordes antialiasing.

Cuándo usar

• Generar una nueva imagen (arte conceptual, foto de producto, portada, héroe de sitio web, póster)
• Generar una nueva imagen que dependa de información actual del mundo real (use --web-grounding)
• Editar una imagen existente (eliminación o reemplazo de objetos, cambios de atributos, inpainting, actualizaciones de texto, cambios de iluminación o clima, limpieza de artefactos)
• Combinar hasta cinco imágenes de referencia en un solo resultado (coherencia de producto, personaje o activo de marca)
• Producir muchos activos o variantes para una sola tarea

Cuándo no usar

• Extender o igualar un conjunto de iconos SVG/vectoriales existente, sistema de logotipos o biblioteca de ilustraciones dentro del repositorio
• Crear formas simples, diagramas, wireframes o iconos que se producen mejor directamente en SVG, HTML/CSS o canvas
• Realizar una edición pequeña de un activo local del proyecto cuando el archivo fuente ya existe en un formato nativo editable
• Cualquier tarea donde el usuario quiera claramente una salida nativa de código determinista en lugar de un mapa de bits generado
• Salida más grande que aproximadamente 1.5K (el límite de MAI-Image-2.6 es 2,359,296 píxeles, por ejemplo 1536x1536); informe al usuario sobre el límite en lugar de escalar silenciosamente

Árbol de decisión

Piense en dos preguntas separadas:

1. Intención: ¿es una imagen nueva o una edición de una imagen existente?
2. Estrategia de ejecución: ¿es un activo o muchos activos/variantes?

Intención:

• Si el usuario quiere modificar una imagen existente conservando partes de ella, trate la solicitud como edit.
• Si el usuario proporciona imágenes como referencias de estilo, composición, ambiente o tema y quiere que se reflejen en el resultado, use edit con esas imágenes como referencias (la API de generación MAI no acepta imágenes).
• Si el usuario no proporciona imágenes, trate la solicitud como generate.

Semántica de edición:

• El modo de edición de la CLI acepta de uno a cinco archivos PNG o JPEG locales a través de banderas --image repetidas.
• Si el usuario proporciona imágenes adjuntas o referencias de la conversación, guárdelas localmente primero si el entorno lo permite; de lo contrario, solicite al usuario las rutas de archivo locales.
• El orden de las imágenes es significativo, así que etiquete cada imagen por índice y rol en el prompt.
• Para ediciones, preserve los invariantes de manera agresiva y guarde de forma no destructiva por defecto.
• Las ediciones no están documentadas para MAI-Image-2 y MAI-Image-2e, y la CLI las bloquea; use un despliegue MAI-Image-2.5 o MAI-Image-2.6 para ediciones.

Estrategia de ejecución:

• Use el subcomando generate-batch de la CLI para muchos prompts/activos cuando el procesamiento por lotes JSONL sea el flujo de trabajo más claro.
• La API MAI devuelve una imagen por solicitud y no tiene un parámetro n. Para variantes, ejecute comandos separados o trabajos por lotes separados con nombres out distintos.
• Los límites de velocidad son bajos (por ejemplo, 6 solicitudes por minuto para MAI-Image-2.6-Flash en el Nivel 1). Mantenga --concurrency en el valor predeterminado de 2 a menos que el usuario conozca su cuota.

Suponga que el usuario quiere una imagen nueva a menos que pida claramente cambiar una existente.

Flujo de trabajo

1. Decida el subcomando de la CLI: generate, edit o generate-batch.
2. Decida si la salida es solo de vista previa o está destinada a ser consumida por el proyecto actual.
3. Decida la estrategia de ejecución: activo único vs comandos CLI repetidos vs generate-batch de la CLI.
4. Recoja las entradas de antemano: prompt(s), texto exacto (textual), lista de restricciones/evitar, tamaño objetivo o relación de aspecto, y cualquier imagen de entrada.
5. Para cada imagen de entrada, etiquete su rol explícitamente:
   • imagen de referencia
   • objetivo de edición
   • entrada de inserción/estilo/composición de apoyo
6. Si el usuario solicitó una foto, ilustración, sprite, imagen de producto, banner u otro activo explícitamente rasterizado, use este skill en lugar de sustituir marcadores de posición SVG/HTML/CSS. Si la solicitud es para un icono, logotipo o gráfico de UI que debe coincidir con activos SVG/vectoriales/código nativos existentes en el repositorio, prefiera editar esos directamente.
7. Aumente el prompt según la especificidad:
   • Si el prompt del usuario ya es específico y detallado, normalícelo en una especificación clara sin agregar requisitos creativos.
   • Si el prompt del usuario es genérico, agregue un aumento de buen gusto solo cuando mejore materialmente la calidad de la salida.
8. Elija el tamaño. Use --size ANCHOxALTO para un objetivo conocido, o --auto-aspect-ratio (familia MAI-Image-2.6) cuando la composición deba decidir. Agregue --web-grounding (familia MAI-Image-2.6) cuando el prompt dependa de entidades, lugares o eventos del mundo real actuales.
9. Ejecute scripts/image_gen.js con el despliegue predeterminado.
10. Para solicitudes de salida transparente, siga el flujo de trabajo de clave cromática a continuación.
11. Inspeccione las salidas y valide: tema, estilo, composición, precisión del texto y elementos invariantes/evitar.
12. Itere con un solo cambio dirigido, luego vuelva a verificar.
13. Para trabajo solo de vista previa, escriba en output/imagegen/ a menos que el usuario haya solicitado una ubicación diferente.
14. Para trabajo vinculado al proyecto, escriba el artefacto en el espacio de trabajo y actualice cualquier código o referencias consumidoras.
15. Para lotes o solicitudes de múltiples activos, persista cada entregable solicitado final en el espacio de trabajo a menos que el usuario haya solicitado explícitamente mantener las salidas solo como vista previa. Las variantes descartadas no necesitan conservarse a menos que se soliciten.
16. Use los documentos de la CLI para despliegue, tamaño, auto_aspect_ratio, web_grounding, rutas de salida y configuración de red.
17. Siempre informe la(s) ruta(s) final(es) guardada(s) para cualquier activo vinculado al espacio de trabajo, además del prompt o conjunto de prompts final.

Solicitudes de imágenes transparentes

Los modelos de imagen MAI siempre devuelven un PNG opaco y no tienen una opción de fondo transparente. Cree activos transparentes con una imagen fuente de clave cromática y eliminación local.

Secuencia:

1. Use scripts/image_gen.js generate (o edit para una imagen existente) para colocar el tema solicitado sobre un fondo de clave cromática sólido perfectamente plano.

2. Elija un color de clave que sea poco probable que aparezca en el tema: predeterminado #00ff00, use #ff00ff para temas verdes y evite #0000ff para temas azules.

3. Mantenga la imagen fuente de clave cromática en el espacio de trabajo o en tmp/imagegen/.

4. Ejecute el ayudante incluido:

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

5. Valide que la salida tenga un canal alfa, esquinas transparentes, cobertura plausible del tema y sin franjas evidentes de color clave. Compóngala sobre un fondo claro y uno oscuro para verificar halos. Si queda una franja delgada, reintente una vez con --edge-contract 1; use --edge-feather 0.25 solo cuando el borde sea visiblemente escalonado y el tema no sea brillante o reflectante.

6. Guarde el PNG alfa final en el proyecto si el activo está vinculado al proyecto.

Solicite solicitudes de clave cromática como esta:

Cree el tema solicitado sobre un fondo de clave cromática #00ff00 perfectamente plano y sólido para eliminar el fondo.
El fondo debe ser de un solo color uniforme sin sombras, gradientes, textura, reflejos, plano de suelo o variación de iluminación.
Mantenga el tema completamente separado del fondo con bordes nítidos y relleno generoso.
No use #00ff00 en ninguna parte del tema.
Sin sombra proyectada, sin sombra de contacto, sin reflejo, sin marca de agua y sin texto a menos que se solicite explícitamente.

La clave cromática es una mala opción para cabello, piel, plumas, humo, vidrio, líquidos, materiales translúcidos, objetos reflectantes y sombras suaves. Informe al usuario sobre este límite antes de prometer un recorte limpio para esos temas.

Aumento de prompt

Reformatee los prompts del usuario en una especificación estructurada y orientada a la producción. Haga que el objetivo del usuario sea más claro y más procesable, pero no agregue detalles a ciegas.

Trate esto como una guía de conformación de prompts, no un esquema cerrado. Use solo las líneas que ayudan y agregue una línea etiquetada corta adicional cuando mejore materialmente la claridad.

Política de especificidad

Use la especificidad del prompt del usuario para decidir cuánto aumento es apropiado:

• Si el prompt ya es específico y detallado, conserve esa especificidad y solo normalícelo/estructúrelo.
• Si el prompt es genérico, puede agregar un aumento de buen gusto cuando mejore materialmente el resultado.

Aumentos permitidos:

• pistas de composición o encuadre
• nivel de pulido o pistas de uso previsto
• guía de diseño práctico
• concreción de escena razonable que respalde la solicitud declarada

Aumentos no permitidos:

• personajes u objetos adicionales que no estén implícitos en la solicitud
• nombres de marca, eslóganes, paletas o ritmos narrativos que no estén implícitos
• colocación lateral arbitraria específica a menos que el diseño circundante la respalde

Taxonomía de casos de uso (slugs exactos)

Clasifique cada solicitud en uno de estos cubos y mantenga el slug consistente en todos los prompts y referencias.

Generar:

• photorealistic-natural: escenas de estilo de vida sinceras/editoriales con textura real e iluminación natural.
• product-mockup: tomas de producto/empaque, imágenes de catálogo, conceptos de mercancía.
• ui-mockup: maquetas y wireframes de interfaz de aplicación/web; especifique la fidelidad deseada.
• infographic-diagram: diagramas/infografías con diseño estructurado y texto.
• scientific-educational: explicadores de aula, diagramas científicos y visuales de aprendizaje con etiquetas requeridas y restricciones de precisión.
• ads-marketing: conceptos de campaña y creatividades publicitarias con audiencia, posición de marca, escena y eslogan/texto exacto.
• productivity-visual: diapositiva, gráfico, flujo de trabajo y visuales de negocios con muchos datos.
• logo-brand: exploración de logotipo/marca, amigable con vectores.
• illustration-story: cómics, arte de libros infantiles, escenas narrativas.
• stylized-concept: arte conceptual impulsado por estilo, renders 3D/estilizados.
• historical-scene: escenas precisas de época/conocimiento mundial.

Editar:

• text-localization: traducir/reemplazar texto en la imagen, preservar el diseño.
• identity-preserve: probar, persona en escena; bloquear rostro/cuerpo/pose.
• precise-object-edit: eliminar/reemplazar un elemento específico (incluyendo intercambios interiores).
• lighting-weather: cambios solo de hora del día/estación/ambiente.
• background-extraction: recorte limpio a través de un fondo de clave cromática plano más eliminación local con scripts/remove_chroma_key.js.
• style-transfer: aplicar estilo de referencia mientras se cambia el tema/escena.
• compositing: inserción/fusión de múltiples imágenes con iluminación/perspectiva igualadas (hasta cinco imágenes).
• sketch-to-render: dibujo/arte lineal a render fotorrealista.

Esquema de prompt compartido

Use la siguiente especificación etiquetada como andamio de prompt compartido para ambos modos de nivel superior:

Caso de uso: <slug de taxonomía>
Tipo de activo: <dónde se usará el activo>
Solicitud principal: <prompt principal del usuario>
Imágenes de entrada: <Imagen 1: rol; Imagen 2: rol> (opcional)
Escena/fondo: <entorno>
Tema: <tema principal>
Estilo/medio: <foto/ilustración/3D/etc>
Composición/encuadre: <abierto/cerrado/vista desde arriba; colocación>
Iluminación/ambiente: <iluminación + ambiente>
Paleta de colores: <notas de paleta>
Materiales/texturas: <detalles de superficie>
Texto (textual): "<texto exacto>"
Restricciones: <debe mantener/debe evitar>
Evitar: <restricciones negativas>

Notas:

• Tipo de activo e Imágenes de entrada son andamio de prompt, no banderas dedicadas de la CLI.
• Escena/fondo se refiere al entorno visual.
• Las notas de ejecución como tamaño, auto_aspect_ratio, web_grounding y rutas de salida pertenecen a la ruta de la CLI, no al texto del prompt.

Reglas de aumento:

• Manténgalo corto.
• Agregue solo los detalles necesarios para mejorar el prompt materialmente.
• Para ediciones, enumere explícitamente los invariantes (cambiar solo X; mantener Y sin cambios).
• Si falta algún detalle crítico y bloquea el éxito, haga una pregunta; de lo contrario, continúe.

Examen

… [truncado para traducción]