What does this skill do, and when should you use it?
imagegen is one of the bundled skills in OpenAI's Codex repository, teaching Codex when and how to generate or edit raster images. It defaults to Codex's built-in image_gen tool, which requires no API key; the bundled scripts/image_gen.py CLI (requiring OPENAI_API_KEY) is used only when the user explicitly asks for the CLI/API path or needs true native transparency. The skill ships a use-case taxonomy, shared prompt templates, batching strategy, and a complete chroma-key workflow that converts a flat key-color background into an alpha PNG/WebP locally. It also draws a clear boundary: SVG, icon, and logo work should stay code-native rather than be replaced by AI-generated bitmaps.
- Generates new images via the built-in image_gen tool (concept art, product shots, website heroes, UI mockups) or style-matched variants from reference images
- Edits images already in conversation context: inpainting, background replacement, object removal, compositing, lighting/weather changes
- Handles batch requests via one built-in call per asset, or the CLI generate-batch subcommand in fallback mode
- Creates transparent images by generating on a chroma-key background (default #00ff00) and running remove_chroma_key.py locally to produce alpha PNG/WebP
- Applies save-path policy: moves project-bound assets from $CODEX_HOME/generated_images/ into the workspace with versioned filenames to avoid overwrites
- In CLI fallback, calls gpt-image-2 via scripts/image_gen.py with quality and size control up to 3840px
- A frontend developer generating hero images, product mockups, or UI visuals for a landing page directly into the workspace
- A game developer batch-producing textures and sprite bitmaps that must land as final files in the project directory
- A marketer or designer swapping a product photo's background or changing lighting/weather while strictly preserving the product itself
- Users needing transparent-background icons or assets via the chroma-key workflow, with CLI gpt-image-1.5 native transparency (after confirmation) for complex subjects like hair, glass, or smoke
- Users producing multiple variants for one task, such as several ad creative versions
- Tasks involving existing SVG/vector icon sets, logos, or simple shapes and diagrams — the skill explicitly directs these to code-native editing instead of generated bitmaps
- Non-Codex environments: the built-in image_gen tool and $CODEX_HOME conventions are Codex-specific; other platforms are limited to the CLI fallback path, which needs adaptation
- Users who need fine CLI controls (quality/size/masks) but won't set OPENAI_API_KEY — that path requires the key
How do you install this skill?
- Image generation depends on an external model service; handling, retention, and privacy boundaries for prompts and input images are not explicitly documented.
- CLI mode requires OPENAI_API_KEY, Python dependencies, and network access; mainland-China users may face service reachability or network-approval issues.
- No tests or CI evidence cover the key paths, so output quality, text accuracy, transparency edges, and edit invariants require manual verification.
- Shell / CLI
- Network access
- Local filesystem
Python (openai, pillow packages)OPENAI_API_KEY (CLI fallback only)Codex built-in image_gen tool (default mode)
The skill ships inside the Codex repository as a bundled sample/system skill and requires no separate installation.
Codex (install the Codex CLI; the skill comes with the repo)
curl -fsSL https://chatgpt.com/codex/install.sh | shor
npm install -g @openai/codexCLI fallback dependencies (only if using scripts/image_gen.py)
uv pip install openai
uv pip install pillowHow do you use this skill?
Once installed, send your agent any of these to trigger it:
- Generate a minimal hero image of a ceramic coffee mug for our landing page, soft studio lighting, no logos or text, save as assets/hero.png
- Replace the background of product photo hero.jpg with a warm sunset gradient; change only the background and keep the product and edges unchanged
- Generate a mascot icon on a flat #00ff00 chroma-key background, then remove the background and output a transparent PNG to assets/mascot.png
- Use CLI mode to batch-generate 5 ad banners in different styles, output to output/imagegen/
The skill triggers automatically when Codex detects an image generation or editing task. Default flow: pick the mode first (built-in image_gen preferred; CLI fallback only when explicitly requested or confirmed for native transparency), then decide intent (generate vs edit), output purpose (preview-only vs project asset), and execution strategy (single asset / repeated calls / generate-batch). You supply prompts, verbatim text, constraints, and input images; the skill labels each input's role and loads local files with view_image before built-in edits. Transparent requests follow the chroma-key flow:
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 \
--despillCLI fallback offers generate / edit / generate-batch subcommands, with intermediates in tmp/imagegen/ and final artifacts in output/imagegen/. Note: ordinary quality/size/path control is not a reason to switch to CLI, and downgrading to gpt-image-1.5 always requires asking the user first.
What are this skill's strengths and limitations?
- Built-in tool mode requires no API key and works out of the box
- Extremely explicit rules on when to use built-in vs CLI fallback and when to ask the user, reducing misuse
- Ships full prompt templates, a use-case taxonomy with exact slugs, and per-asset-type examples
- Transparent backgrounds have a concrete local chroma-key solution with soft matte, despill, and edge-tuning parameters
- Clear save-path and no-overwrite policy keeps project assets out of default directories
- Tightly coupled to Codex: built-in image_gen, view_image, and $CODEX_HOME paths are Codex-specific and need rewriting for other Agent Skills clients
- True native transparency requires downgrading to gpt-image-1.5 (gpt-image-2 lacks background=transparent) plus OPENAI_API_KEY
- Chroma-key removal is limited for complex subjects like fur, smoke, glass, and translucent materials
- scripts/image_gen.py must never be modified, limiting customization
- The repo has no GitHub topics, and the README targets the whole Codex CLI, so standalone documentation for this skill is limited
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| Codex Image Generation Skill (imagegen) this page ✓ OpenAI · Official | 56 · Use with care | ★ 129k | 11d ago | Apache-2.0 |
| GPT Image 2 Creative Workflow | 53 · Use with care | ★ 13k | 15d ago | MIT |
| Banana Claude — Gemini Image Creative Director | 59 · Recommended | ★ 1.1k | 7d ago | MIT |
| Academic Figure Prompt — Modern ML Airy Style | 68 · Recommended | ★ 2.6k | 7mo ago | MIT |
| Academic Figure Prompt Generator | 69 · Recommended | ★ 2.6k | 7mo ago | MIT |
The skill itself contrasts its two execution paths: the built-in image_gen tool (default, key-free, transparency via chroma-key post-processing) versus the CLI fallback (scripts/image_gen.py with gpt-image-2/1.5, key required, supporting quality, sizes, masks, and native transparency). They are complementary, not competing.
How did FollowSkills review this skill?
The documentation separates built-in and CLI modes, requires confirmation for the transparency downgrade, avoids overwriting files, handles API keys cautiously, and discusses network-approval risk. It does not fully disclose image/prompt data flows, retention or privacy behavior, built-in-tool external effects, or a general rollback mechanism, so 7 points are deducted.
The script and docs provide parameter validation, missing-dependency guidance, output-collision protection, batch limits, and some transient-error retries; the main path is plausible from static inspection. However, there is no committed test suite or execution evidence, and built-in-tool failure coverage and recovery remain limited, so the score is capped conservatively.
Use cases, generate/edit distinctions, non-fit cases, trigger rules, and output handling are clearly described. Chinese-language support is not documented, and the CLI depends on OpenAI network services without evidence of mainland-China reachability or a practical alternative, so 5 points are deducted.
The package has strong information architecture, progressive disclosure, dependency notes, parameters, examples, limitations, and cross-references. It lacks an intrinsic version, changelog, explicit maintenance owner, and update path; license and governance are mainly supplied as external metadata, so 4 points are deducted.
The skill covers generation, editing, batching, transparency workflows, and project-local artifact handling, with a clear core benefit. Static files do not verify output quality, text accuracy, or iteration outcomes, so limited manual review remains necessary and 1 point is deducted.
The SKILL.md, reference documents, and CLI source provide auditable rules, parameters, and diagnostics, making some claims source-checkable. There is no committed test suite, CI coverage, or third-party execution record, so the static evidence supports only a low score.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →