Preface

When writing front-end code, building small games, or putting together landing pages, you often get stuck on “missing an image”: Hero backgrounds, product mockups, spritesheets, transparent cutout images. The common practices back then were to switch to a standalone drawing tool to generate the image, then download it, rename it, and copy it into the repository; or use SVG/HTML placeholders first and replace them with real images later. As the workflow lengthens, it’s easy for copy, layout, and assets to get out of sync.

OpenAI has packaged image generation capabilities into an Agent Skill: imagegen. It lives under the .system skill catalog of Codex, and the latest version of Codex will install it automatically. The core idea is straightforward—specify the bitmap you want in the conversation, use the built-in image_gen tool (or an explicitly enabled CLI) to produce raster resources like PNGs, and then place them into the project directory according to the rules. This article organizes its capabilities, enabling methods, and typical usage based on the SKILL.md and CLI reference from the official repository.

What is this

imagegen is a system-level Skill for Codex, with the official repository path:
https://github.com/openai/skills/tree/main/skills/.system/imagegen

Its positioning can be summed up in one sentence: When a task requires AI-generated bitmaps (photos, illustrations, textures, spritesheets, mockups, transparent cutout images, etc.), use a structured workflow to generate or edit images; do not use this path if it is more suitable to modify existing SVG/vector/HTML/CSS files in the repository.

The repository README states that skills under skills/.system/ are automatically installed with the latest version of Codex, and you generally do not need to install them separately using $skill-installer. The Skill itself follows the standard Agent Skills open format with a SKILL.md + scripts/ + references/ directory structure; but the built-in image_gen tool and the $CODEX_HOME storage convention are capabilities of the Codex side, so use them based on your Codex environment.

Two Working Modes

The official documentation makes it clear that there are only two top-level modes for the Skill:

  1. Default: Built-in image_gen tool (Recommended)
    For daily generation and editing, you do not need to set OPENAI_API_KEY.

  2. Fallback: scripts/image_gen.py CLI (Only for explicit use)
    Only used when the user explicitly requests to use the CLI. Requires OPENAI_API_KEY and network access. It provides three subcommands: generate, edit, and generate-batch.

Key rules:
- Always use the built-in tool for normal requests, do not automatically switch to the CLI.
- If the built-in tool fails or is unavailable, inform the user that there is a CLI fallback that relies on an API Key; only use the CLI after the user explicitly agrees.
- When using the CLI, use the skill’s built-in scripts/image_gen.py, do not write a temporary SDK script; and do not modify this script without authorization.

Core Capabilities and Boundaries

What it is suitable for

The official listed typical scenarios include:
- Generating from scratch: concept art, product images, covers, website Heroes, etc.
- Generating with reference images: use one or more images to constrain style, composition, or atmosphere
- Editing existing images: local redrawing, lighting/weather changes, background replacement, object removal, compositing, transparent backgrounds
- Producing multiple assets or variants for the same task

The generation side also has categorized slugs by use case (such as product-mockup, ui-mockup, photorealistic-natural, illustration-story, etc.); the editing side has precise-object-edit, background-extraction, style-transfer, compositing, etc. Keeping the slugs consistent when writing prompts makes it easier for the Agent to expand according to the same template.

What it is not suitable for

The official has also drawn boundaries to avoid “generating any image”:
- Extending or aligning existing SVG vector icons, logo systems, or illustration libraries in the repository
- Simple graphics, diagrams, wireframes, or icons that can be better completed using SVG, HTML/CSS, or canvas
- Source files that are already editable native formats that only require minor changes
- Scenarios where the user explicitly requires deterministic code-side output instead of generating bitmaps

In short: Use imagegen for bitmap assets; continue modifying files in the repository for vector and code-native visuals.

Installation and Activation

In the latest version of Codex, imagegen under .system/ will be installed automatically. To confirm if the skill is available, you can check the loaded Skills in Codex, or check the local skill directory (the default CODEX_HOME is ~/.codex):

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
ls "$CODEX_HOME/skills/.system/imagegen"

The directory will usually contain SKILL.md, scripts/image_gen.py, references/, etc. After installing or updating the skill, restart the session as required by the Codex documentation to reload it.

If the built-in tool is unavailable and you explicitly want to use the CLI fallback, first prepare dependencies and keys:

# Officially recommended to install in an uv-managed environment
uv pip install openai
# Optional, only needed to resize output images
uv pip install pillow

# Configure in your local environment variables, do not paste the full key into the conversation
export OPENAI_API_KEY="your-api-key"

The CLI entry can be fixed as:

export IMAGE_GEN="$CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py"

You can create an API key on the OpenAI platform: https://platform.openai.com/api-keys

Note: The README of the openai/skills repository currently marks the repository as deprecated, and new examples have moved to the OpenAI Plugins repository; but the SKILL.md under .system/imagegen is still the current official first-hand documentation, and Codex still automatically installs it as a system skill. This article and practice are based on the content of this directory.

Built-in Mode: Save Path Convention

In built-in mode, Codex by default writes generated results to $CODEX_HOME/* (usually $CODEX_HOME/generated_images/...). Do not treat the system temporary directory as the default save location, and do not rely on the “target path parameter” of the built-in tool. When you need a fixed location, the workflow is: Generate first, then move/copy the selected file to the target path.

The official agreed priority is as follows:
1. The user specifies a target path → move the file to that path
2. The image needs to be added to the current project → copy it to the workspace before finishing and update references
3. Only for preview/brainstorming → can be displayed inline, and the files remain in $CODEX_HOME/*

Notes:
- Assets that are actually referenced by the project cannot just stay in the default $CODEX_HOME directory.
- Do not overwrite existing assets unless the user explicitly requests it; use sibling filenames like hero-v2.png, item-icon-edited.png.

In terms of editing semantics, the built-in editing tool targets images that are already visible in the conversation context (attachments or images generated earlier in the current round). To modify a local file, you need to first load the context using the built-in view_image tool before editing; do not promise that the built-in tool can directly perform fine-grained control such as mask operations based on any file system path—that capability belongs to the explicit CLI fallback.

How to Write Prompts

The official recommendation is to organize the user’s intent into a structured specification instead of adding unnecessary details blindly. The shared template is roughly as follows:

Use case: <taxonomy slug>
Asset type: <where the asset will be used>
Primary request: <user's main prompt>
Input images: <Image 1: role; Image 2: role> (optional)
Scene/backdrop: <environment>
Subject: <main subject>
Style/medium: <photo/illustration/3D/etc>
Composition/framing: <wide/close/top-down; placement>
Lighting/mood: <lighting + mood>
Color palette: <palette notes>
Materials/textures: <surface details>
Text (verbatim): "<exact text>"
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

Expansion principles:
- If the user has already written detailed requirements → only standardize them without adding creative requirements without authorization
- If the user’s requirements are vague → you can supplement information such as composition, use case, lighting, etc. that “can substantially improve the result”
- Do not add unspecified characters/objects, brand slogans, or irrelevant narratives without authorization
- When editing, clearly restate the invariants repeatedly, for example “only change the background, keep the subject and its edges unchanged”

Generation example (Hero / product image):

Use case: product-mockup
Asset type: landing page hero
Primary request: a minimal hero image of a ceramic coffee mug
Style/medium: clean product photography
Composition/framing: wide composition with usable negative space for page copy if needed
Lighting/mood: soft studio lighting
Constraints: no logos, no text, no watermark

Editing example (only replace background):

Use case: precise-object-edit
Asset type: product photo background replacement
Primary request: replace only the background with a warm sunset gradient
Constraints: change only the background; keep the product and its edges unchanged; no text; no watermark

In Codex conversations, you can also directly describe the requirements in natural language, for example: “Generate a minimalist product Hero for a landing page featuring a ceramic coffee mug, leave negative space for copy, and do not include logos or text”. The Agent should follow the Skill rules to use the built-in image_gen tool and place the final usable files into the project.

CLI Fallback Example (When Explicitly Enabled)

The following commands are from the official references/cli.md and should only be used when the user explicitly requests to use the CLI.

Dry run (does not call the API, no openai package required):

python "$IMAGE_GEN" generate \
  --prompt "Test" \
  --out output/imagegen/test.png \
  --dry-run

Generate:

python "$IMAGE_GEN" generate \
  --prompt "A cozy alpine cabin at dawn" \
  --size 1024x1024 \
  --out output/imagegen/alpine-cabin.png

Edit:

python "$IMAGE_GEN" edit \
  --image input.png \
  --prompt "Replace only the background with a warm sunset" \
  --out output/imagegen/sunset-edit.png

Edit with quality and input fidelity parameters (CLI-exclusive parameters, not available in the built-in tool):

python "$IMAGE_GEN" edit \
  --image input.png \
  --prompt "Change only the background" \
  --quality high \
  --input-fidelity high \
  --out output/imagegen/background-edit.png

The official CLI defaults include: model gpt-image-1.5 (GPT Image series), size 1024x1024, quality auto, output format png. Supported sizes are 1024x1024, 1536x1024, 1024x1536, or auto. Transparent backgrounds require the output format to be png or webp. Intermediate files are recommended to be placed in tmp/imagegen/, and finished products in output/imagegen/; add --force to overwrite existing target files.

You can use generate-batch for batch multiple prompts (you must specify --out-dir):

mkdir -p tmp/imagegen output/imagegen/batch
cat > tmp/imagegen/prompts.jsonl << 'EOF'
{"prompt":"Cavernous hangar interior with a compact shuttle parked near the center","use_case":"stylized-concept","size":"1536x1024"}
{"prompt":"Gray wolf in profile in a snowy forest","use_case":"photorealistic-natural","size":"1024x1024"}
EOF

python "$IMAGE_GEN" generate-batch \
  --input tmp/imagegen/prompts.jsonl \
  --out-dir output/imagegen/batch \
  --concurrency 5

Applicable Scenarios and Notes

It is suitable for:
- Synchronously producing bitmap assets for websites/games/UI during Codex coding sessions
- Needing reference images to constrain style, or performing local edits on existing bitmaps
- Quickly generating images during the preview phase, then moving the selected results into the repository

Points to note:
- The default path is the built-in tool; the CLI is an explicit fallback, do not mix parameter semantics (for example, CLI parameters like --quality, --mask, --input-fidelity are not available in the built-in tool).
- Editing local files: use view_image first in the built-in path; consider the CLI only when you need path-level control, masks, etc.
- Final files referenced by the project must be added to the workspace, and report the final path, final prompt, and whether the built-in tool or CLI was used.
- When iterating, only change one point at a time and repeat the invariants to reduce drift.
- If the goal is to align with an existing SVG/icon system, you should directly modify the vector or code instead of forcibly generating bitmaps.

Summary

imagegen streamlines the process of “requesting a bitmap during a coding conversation” into a repeatable Skill: use the built-in image_gen by default (no API Key required), and explicitly use scripts/image_gen.py only when necessary. With structured prompts and clear save rules, it reduces the hassle of placeholder images and asset back-and-forth. It solves raster asset production, and does not replace vector and code-native visuals in the repository.

Official repository:
https://github.com/openai/skills/tree/main/skills/.system/imagegen

For more complete prompt principles and examples, see references/prompting.md and references/sample-prompts.md in the same directory; see references/cli.md for CLI details.