imagegen

name	imagegen
description	Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.
scope	harness
invocation	ability

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.

Fallback-only docs/resources for CLI mode:

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

Local post-processing helper:

• $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py: removes a flat chroma-key background from a generated image and writes a PNG/WebP with alpha. Prefer auto-key sampling, soft matte, and despill for antialiased edges.

When to use

• Generate a new image (concept art, product shot, cover, website hero)
• Generate a new image using one or more reference images for style, composition, or mood
• Edit an existing image (inpainting, lighting or weather transformations, background replacement, object removal, compositing, transparent background)
• Produce many assets or variants for one task

When not to use

• Extending or matching an existing SVG/vector icon set, logo system, or illustration library inside the repo
• Creating simple shapes, diagrams, wireframes, or icons that are better produced directly in SVG, HTML/CSS, or canvas
• Making a small project-local asset edit when the source file already exists in an editable native format
• Any task where the user clearly wants deterministic code-native output instead of a generated bitmap

Decision tree

Think about two separate questions:

1. Intent: is this a new image or an edit of an existing image?
2. Execution strategy: is this one asset or many assets/variants?

Intent:

• If the user wants to modify an existing image while preserving parts of it, treat the request as edit.
• If the user provides images only as references for style, composition, mood, or subject guidance, treat the request as generate.
• If the user provides no images, treat the request as generate.

Built-in edit semantics:

• Built-in edit mode is for images already visible in the conversation context, such as attached images or images generated earlier in the thread.
• If the user wants to edit a local image file with the built-in tool, first load it with built-in view_image tool so the image is visible in the conversation context, then proceed with the built-in edit flow.
• Do not promise arbitrary filesystem-path editing through the built-in tool.
• If a local file still needs direct file-path control, masks, or other explicit CLI-only parameters, use the explicit CLI fallback only when the user asks for it.
• For edits, preserve invariants aggressively and save non-destructively by default.

Execution strategy:

• In the built-in default path, produce many assets or variants by issuing one image_gen call per requested asset or variant.
• In the CLI fallback path, use the CLI generate-batch subcommand only when the user explicitly chose CLI mode and needs many prompts/assets.
• For many distinct assets, do not use n as a substitute for separate prompts. n is for variants of one prompt; distinct assets need distinct built-in calls or distinct CLI generate-batch jobs.

Assume the user wants a new image unless they clearly ask to change an existing one.

Workflow

1. Decide the top-level mode: built-in by default, including simple transparent-output requests; fallback CLI only if explicitly requested or after the user explicitly confirms a transparent-output fallback.
2. Decide the intent: generate or edit.
3. Decide whether the output is preview-only or meant to be consumed by the current project.
4. Decide the execution strategy: single asset vs repeated built-in calls vs CLI generate-batch.
5. Collect inputs up front: prompt(s), exact text (verbatim), constraints/avoid list, and any input images.
6. For every input image, label its role explicitly:
   • reference image
   • edit target
   • supporting insert/style/compositing input
7. If the edit target is only on the local filesystem and you are staying on the built-in path, inspect it with view_image first so the image is available in conversation context.
8. If the user asked for a photo, illustration, sprite, product image, banner, or other explicitly raster-style asset, use image_gen rather than substituting SVG/HTML/CSS placeholders. If the request is for an icon, logo, or UI graphic that should match existing repo-native SVG/vector/code assets, prefer editing those directly instead.
9. Augment the prompt based on specificity:
   • If the user's prompt is already specific and detailed, normalize it into a clear spec without adding creative requirements.
   • If the user's prompt is generic, add tasteful augmentation only when it materially improves output quality.
10. Use the built-in image_gen tool by default.
11. For transparent-output requests, follow the transparent image guidance below: generate with built-in image_gen on a flat chroma-key background, copy the selected output into the workspace or tmp/imagegen/, run the installed $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py helper, and validate the alpha result before using it. If this path looks unsuitable or fails, ask before switching to CLI gpt-image-1.5.
12. Inspect outputs and validate: subject, style, composition, text accuracy, and invariants/avoid items.
13. Iterate with a single targeted change, then re-check.
14. For preview-only work, render the image inline; the underlying file may remain at the default $CODEX_HOME/generated_images/... path.
15. For project-bound work, move or copy the selected artifact into the workspace and update any consuming code or references. Never leave a project-referenced asset only at the default path.

Transparent image requests

Transparent-image requests still use built-in image_gen first. Because the built-in tool does not expose a true transparent-background control, create a removable chroma-key source image and then convert the key color to alpha locally.

Default sequence:

1. Use built-in image_gen to generate the requested subject on a perfectly flat solid chroma-key background.
2. Choose a key color that is unlikely to appear in the subject: default #00ff00, use #ff00ff for green subjects, and avoid #0000ff for blue subjects.
3. After generation, move or copy the selected source image from $CODEX_HOME/generated_images/... into the workspace or tmp/imagegen/.
4. Run the installed helper path, not a project-relative script path:

   python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \
     --input <source> \
     --out <final.png> \
     --auto-key border \
     --soft-matte \
     --transparent-threshold 12 \
     --opaque-threshold 220 \
     --despill
   

5. Validate that the output has an alpha channel, transparent corners, plausible subject coverage, and no obvious key-color fringe. If a thin fringe remains, retry once with --edge-contract 1; use --edge-feather 0.25 only when the edge is visibly stair-stepped and the subject is not shiny or reflective.
6. Save the final alpha PNG/WebP in the project if the asset is project-bound. Never leave a project-referenced transparent asset only under $CODEX_HOME/*.

Prompt transparent requests like this:

Create the requested subject on a perfectly flat solid #00ff00 chroma-key background for background removal.
The background must be one uniform color with no shadows, gradients, texture, reflections, floor plane, or lighting variation.
Keep the subject fully separated from the background with crisp edges and generous padding.
Do not use #00ff00 anywhere in the subject.
No cast shadow, no contact shadow, no reflection, no watermark, and no text unless explicitly requested.

Do not automatically use CLI gpt-image-1.5 --background transparent --output-format png instead of chroma keying. Ask the user first when the user asks for true/native transparency, when local removal fails validation, or when the requested image is complex: hair, fur, feathers, smoke, glass, liquids, translucent materials, reflective objects, soft shadows, realistic product grounding, or subject colors that conflict with all practical key colors.

Use a concise confirmation like:

This likely needs true native transparency. The default built-in path uses a chroma-key background plus local removal, but true transparency requires the CLI fallback with gpt-image-1.5 because gpt-image-2 does not support background=transparent. It also requires OPENAI_API_KEY. Should I proceed with that CLI fallback?

Prompt augmentation, schema, examples & asset guidance

For prompt-shaping + specificity policy, the use-case taxonomy, the shared prompt schema, generation/edit examples, prompting best practices, and per-asset-type + gpt-image-2 CLI-fallback guidance: See references/prompting-and-assets.md.

Session Notes

2026-06-16

• session: 102m | peak ctx: 0% | compacts: 0
• tools: Bash×160, Read×60, WebSearch×44, WebFetch×37, Edit×35, Write×16, Agent×11, ToolSearch×8, TodoWrite×8, Skill×6, AskUserQuestion×5, ExitPlanMode×4
• corrections: none
• errors: none