git:20260821.9fc42be to git:20260821.efe2a77

---

name: codex-imagegen

description: Generate or edit images via the Codex CLI's built-in `$imagegen` skill (gpt-image-2). Use this skill when the user needs visual assets saved to disk — icons, banners, illustrations, OG images, infographics, diagrams, hero art, placeholder images, transparent-background cutouts, or photo edits — in PNG/JPEG/WebP format. Triggers include "generate image", "make an icon", "create a banner", "OG image", "imagegen", "GPT Image 2", "codex image", "transparent background", "이미지 만들어줘", "아이콘 생성", "배너 디자인", and "투명 배경". Do not use for design discussion, image analysis, or screenshot review.

---

# Codex Imagegen

## Overview

Invoke Codex CLI's built-in `$imagegen` skill to generate images with **gpt-image-2**. Translate the request into a concrete art direction, run the bundled safe launcher, move or post-process only a validated generated PNG, and visually verify the final asset.

Prerequisites:

- macOS or Linux

- Python 3.9 or newer, available as `python3`

## Prompt flow

The Codex agent rewrites prompts into a labeled schema before calling gpt-image-2. A detailed prompt is normalized; a vague prompt is augmented with the agent's own choices. Fill every relevant slot to keep control:

```text

$imagegen

Use case: <slug>

Asset type: <where the asset will be used, final size/aspect>

Primary request: <main ask in one sentence>

Input images: <Image 1: role; Image 2: role> (only for edits/references)

Scene/backdrop: <environment, time, mood>

Subject: <main subject; for people: crop, pose, gaze, hands, expression>

Style/medium: <photo, illustration, 3D, print process>

Composition/framing: <viewpoint, placement, negative space, hierarchy>

Lighting/mood: <source, direction, temperature>

Color palette: <3-5 named colors or relationships>

Materials/textures: <surface details, grain, imperfections>

Text (verbatim): "<exact copy>" (omit if no text)

Constraints: <must keep, must render exactly once, must not change>

Avoid: <watermark, logo, extra text, unwanted styles>

```

Generate use-case slugs: `photorealistic-natural`, `product-mockup`, `ui-mockup`, `infographic-diagram`, `scientific-educational`, `ads-marketing`, `productivity-visual`, `logo-brand`, `illustration-story`, `stylized-concept`, `historical-scene`.

Edit use-case slugs: `text-localization`, `identity-preserve`, `precise-object-edit`, `lighting-weather`, `background-extraction`, `style-transfer`, `compositing`, `sketch-to-render`.

For detailed prompting guidance, read [`references/prompting-guide.md`](references/prompting-guide.md).

## Safe execution

Always use [`scripts/run_codex_imagegen.py`](scripts/run_codex_imagegen.py) for the Codex subscription path. The launcher:

- passes the prompt to `codex exec` over stdin through a subprocess argument array, never through shell interpolation;

Execution procedure:

1. Write the complete `$imagegen` brief to a temporary UTF-8 text file with the host's file-write tool. Do not construct it with `echo`, `printf`, a shell variable, or a quoted command string.

2. Run the launcher from the installed skill directory:

```bash

python3 "<SKILL_DIR>/scripts/run_codex_imagegen.py" \

--prompt-file "<PROMPT_FILE>"

```

For edits or references, repeat `--image` in role order:

```bash

python3 "<SKILL_DIR>/scripts/run_codex_imagegen.py" \

--prompt-file "<PROMPT_FILE>" \

--image "./base.png" \

--image "./style-reference.png"

```

## Control surfaces

gpt-image-2 size constraints are deterministic: edges must be multiples of 16, max edge 3840, long:short ratio at most 3:1, and total pixels 655,360-8,294,400. Generate a small icon at a valid size such as 1024×1024, then downscale on the host.

## Workflow

### 1. Parse the request

Fill the native-schema slots from the user's request. Ask one clarifying question only when a critical item such as subject, required text, or edit target is missing. Infer concrete defaults for minor gaps.

### 2. Choose the output path

Use a meaningful path in the current project, such as `./public/og-image.png`, `./assets/icons/dashboard.png`, or `./<purpose>-<descriptor>.png`.

### 3. Preflight the brief

- Replace empty adjectives such as "modern", "clean", and "stunning" with specific layout, medium, palette, lighting, and material decisions.

- Put exact text in quotes, specify placement and contrast, and require it to appear exactly once.

- For people, specify crop, body scale, gaze, pose, hands, object contact, skin texture, lens, and light.

- Attach brand, product, venue, or style references instead of describing them from memory.

### 4. Generate safely

Write the prompt file and run the bundled launcher. For multiple inputs, label every image by index and role in the prompt and pass `--image` in the same order.

### 5. Finish locally

Copy or resize the validated source PNG in the host's approved tool context. On macOS, `sips -z` uses height then width:

```bash

cp "$SRC" ./output.png

sips -z 512 512 ./output.png

# Linux: convert input.png -resize WxH! output.png

```

### 6. Verify visually

Open the result with the host's image viewer. Reject generic AI gloss, weak composition, wrong or duplicated text, incorrect aspect, and unwanted borders or backgrounds. Iterate with one change per pass and restate every invariant.

## Transparent backgrounds

```text

$imagegen

```

```bash

```

## Recipe notes

### OG images and text

### Batch icon sets

### Edits and compositing

State one change per pass and list everything that must remain identical. Label roles explicitly:

```text

$imagegen

Use case: compositing

Input images: Image 1: base scene to edit — preserve framing and lighting;

Image 2: style reference only — do not copy its content

Primary request: change only the background color from white to deep navy (#0a1f3d),

adopting the paper grain of Image 2

Constraints: preserve logo position, typography, all text, composition, and lighting direction

Avoid: any other change, watermark, extra text

```

### Character consistency

Use the first accepted image as the anchor. Attach it in every later prompt, label it as the identity reference, and repeat the same face, clothing, proportions, and palette verbatim.

### Photorealistic people

Write a documentary photo brief with crop, body geometry, gaze, pose, hands, object contact, real skin texture, worn fabric, lens, and light direction. Add "honest and unposed, no heavy retouching, no plastic skin, no extra fingers."

## Resources

- [`scripts/run_codex_imagegen.py`](scripts/run_codex_imagegen.py) — safe subprocess launcher and generated-path validator

- [`references/prompting-guide.md`](references/prompting-guide.md) — prompting schema, text, people, edits, multi-image consistency, and anti-patterns

- [`assets/hero.png`](assets/hero.png) — sample 1600×900 output

## Failure modes

| Symptom | Cause | Fix |

|---|---|---|

| `codex CLI was not found on PATH` | CLI not installed | `npm i -g @openai/codex` |

| Authentication required | Not logged in | Ask the user to run `codex login` directly |

| Launcher rejects the prompt file | Empty file, unreadable file, or missing `$imagegen` | Write a UTF-8 file containing the full image brief |

| Launcher rejects the output path | Codex did not return an existing generated PNG in the trusted root | Do not copy another path; rerun once or inspect Codex stderr |

| Output size differs | Requested size violates model constraints | Generate at a valid size and resize on the host |

| Generic AI appearance | Too many prompt slots were left vague | Specify medium, palette, lighting, composition, and materials |

| Run exceeds five minutes | Complex generation or stalled agent | Let the launcher time out, report it, and do not weaken the sandbox |