Image Generation Skill

Image Generation Skill

Generates or edits images for the current project (for example website assets, game assets, UI mockups, product mockups, wireframes, logo design, photorealistic images, or infographics).

Top-level modes and rules

This skill has exactly two top-level modes:

• Default built-in tool mode (preferred): built-in image_gen tool for normal image generation, editing, and simple transparent-image requests. Does not require OPENAI_API_KEY.
• Fallback CLI mode: scripts/image_gen.py CLI. Use when the user explicitly asks for the CLI/API/model path, or after the user explicitly confirms a true model-native transparency fallback with gpt-image-1.5. Requires OPENAI_API_KEY.

Within CLI fallback, the CLI exposes three subcommands:

• generate
• edit
• generate-batch

Rules:

• Use the built-in image_gen tool by default for normal image generation and editing requests.
• Do not switch to CLI fallback for ordinary quality, size, or file-path control.
• If the user explicitly asks for a transparent image/background, stay on built-in image_gen first: prompt for a flat removable chroma-key background, then remove it locally with the installed helper at $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py.
• Never silently switch from built-in image_gen or CLI gpt-image-2 to CLI gpt-image-1.5. Treat this as a model/path downgrade and ask the user before doing it, unless the user has already explicitly requested gpt-image-1.5, scripts/image_gen.py, or CLI fallback.
• If a transparent request appears too complex for clean chroma-key removal, asks for true/native transparency, or local removal fails validation, explain that true transparency requires CLI gpt-image-1.5 --background transparent --output-format png because gpt-image-2 does not support background=transparent, then ask whether to proceed. Run the CLI fallback only after the user confirms.
• The word batch by itself does not mean CLI fallback. If the user asks for many assets or says to batch-generate assets without explicitly asking for CLI/API/model controls, stay on the built-in path and issue one built-in call per requested asset or variant.
• If the built-in tool fails or is unavailable, tell the user the CLI fallback exists and that it requires OPENAI_API_KEY. Proceed only if the user explicitly asks for that fallback.
• If the user explicitly asks for CLI mode, use the bundled scripts/image_gen.py workflow. Do not create one-off SDK runners.
• Never modify scripts/image_gen.py. If something is missing, ask the user before doing anything else.

Built-in save-path policy:

• In built-in tool mode, Codex saves generated images under $CODEX_HOME/* by default.
• Do not describe or rely on OS temp as the default built-in destination.
• Do not describe or rely on a destination-path argument (if any) on the built-in image_gen tool. If a specific location is needed, generate first and then move or copy the selected output from $CODEX_HOME/generated_images/....
• Save-path precedence in built-in mode:
  1. If the user names a destination, move or copy the selected output there.
  2. If the image is meant for the current project, move or copy the final selected image into the workspace before finishing.
  3. If the image is only for preview or brainstorming, render it inline; the underlying file can remain at the default $CODEX_HOME/* path.
• Never leave a project-referenced asset only at the default $CODEX_HOME/* path.
• Do not overwrite an existing asset unless the user explicitly asked for replacement; otherwise create a sibling versioned filename such as hero-v2.png or item-icon-edited.png.

Shared prompt guidance for both modes lives in references/prompting.md and references/sample-prompts.md.