imagegen

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 and editing. Does not require OPENAI_API_KEY.
• Fallback CLI mode (explicit-only): scripts/image_gen.py CLI. Use only when the user explicitly asks for the CLI path. Requires OPENAI_API_KEY.

Within the explicit CLI fallback only, the CLI exposes three subcommands:

• generate
• edit
• generate-batch

Rules:

• Use the built-in image_gen tool by default for all normal image generation and editing requests.
• Never switch to CLI fallback automatically.
• 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:
• If the user names a destination, move or copy the selected output there.
• If the image is meant for the current project, move or copy the final selected image into the workspace before finishing.
• 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

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 explicit CLI fallback path, use the CLI generate-batch subcommand only when the user explicitly chose CLI mode and needs many prompts/assets.

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, fallback CLI only if explicitly requested.
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:
7. reference image
8. edit target
9. supporting insert/style/compositing input
10. 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.
11. 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.
12. Augment the prompt based on specificity:
13. If the user's prompt is already specific and detailed, normalize it into a clear spec without adding creative requirements.
14. If the user's prompt is generic, add tasteful augmentation only when it materially improves output quality.
15. Use the built-in image_gen tool by default.
16. If the user explicitly chooses the CLI fallback, then and only then use the fallback-only docs for quality, input_fidelity, masks, output format, output paths, and network setup.
17. Inspect outputs and validate: subject, style, composition, text accuracy, and invariants/avoid items.
18. Iterate with a single targeted change, then re-check.
19. For preview-only work, render the image inline; the underlying file may remain at the default $CODEX_HOME/generated_images/... path.
20. 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 $CODEX_HOME/generated_images/... path.
21. For batches, persist only the selected finals in the workspace unless the user explicitly asked to keep discarded variants.
22. Always report the final saved path for any workspace-bound asset, plus the final prompt and whether the built-in tool or fallback CLI mode was used.

Prompt augmentation

Reformat user prompts into a structured, production-oriented spec. Make the user's goal clearer and more actionable, but do not blindly add detail.

Treat this as prompt-shaping guidance, not a closed schema. Use only the lines that help, and add a short extra labeled line when it materially improves clarity.

Specificity policy

Use the user's prompt specificity to decide how much augmentation is appropriate:

• If the prompt is already specific and detai