gpt-image

gpt-image

Agent runbook for GPT Image 2 generation/editing. Use the prompt library + packaged CLI. Do not reimplement image API code.

Operating loop

1. Classify request: generate, edit, inpaint, or multi-reference; identify asset type, exact text, aspect ratio, references, safety constraints, and budget/quality.
2. Search references first: open references/gallery.md; load/search the closest references/gallery-<category>.md file(s). Read actual **Prompt** text before choosing a pattern.
3. Refine with craft: load references/craft.md for dense text, diagrams, UI, data visualization, multi-panel layouts, weak prompts, or no close gallery match.
4. Confer when useful: before costly/ambiguous/high-polish calls, present 1–3 matched directions plus planned size/quality; ask at most one concise question. Skip long discussion for precise “generate now” requests.
5. Preflight, no side effects: use existing CLI/skill if present. Check command availability (command -v gpt-image), installed tool lists when the tool manager exists, or the runtime’s own skill registry when available. Do not assume a local home path in cloud/hosted runtimes.
6. No blind setup: do not reinstall, overwrite skill folders, create/modify .env, or write API keys unless the user explicitly requested setup. Global/shared installs are opt-in only.
7. Execute via CLI only: call gpt-image or scripts/generate.py. Do not create a new generate.py, SDK wrapper, or ad-hoc script for normal image requests.
8. Report: output file path(s), key flags, and one concise refinement suggestion if useful.

Fast path: precise prompt + explicit “generate now” → quick reference/craft check, then CLI.

CLI resolution

Preferred call order:

# Existing CLI on PATH
gpt-image -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]

# Installed skill folder; use runtime-provided skill path when available
uv run "$SKILL_DIR/scripts/generate.py" -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]

# Direct transient CLI when the user requested setup/one-off CLI execution
uvx --from git+https://github.com/wuyoscar/gpt_image_2_skill gpt-image -p "PROMPT" [options]

scripts/generate.py is a launcher: repo-local src/gpt_image_cli → installed gpt-image → PATH gpt-image → transient uvx/uv fallback.

Codex execution rules

• CLI delegates image work to codex exec --json --enable image_generation --cd <workdir> --model <model> and relies on the user's existing Codex login/subscription/session flow.
• --model selects the Codex model for the delegated run. Set GPT_IMAGE_CODEX_MODEL to change the default.
• The CLI parses Codex JSONL/stdout/exit code, finds generated files under ~/.codex/generated_images/<thread_id>/, copies them to the requested output path(s), and verifies the files exist.
• By default the delegated run uses --sandbox workspace-write. Use --dangerously-bypass-approvals-and-sandbox only when the local Codex policy blocks an otherwise trusted image job.
• Use --codex-timeout to cap long delegated runs. Default is 300 seconds.
• Do not create, read, or ask for OpenAI API key files for this skill.
• Never print secret values.

Flags

Flag	Values	Use
-p, --prompt	string	Required prompt/edit instruction
-f, --file	path	Output path; auto-named if omitted
-i, --image	repeatable path	Use edits endpoint; supports multiple references
-m, --mask	PNG path	Inpaint with alpha mask; requires -i
--model	default from GPT_IMAGE_CODEX_MODEL or gpt-5.4-mini	Codex model for the delegated run
--size	1k, 2k, 4k, portrait, landscape, square, wide, tall, or literal	Canvas size
--quality	low, medium, high, auto	Cost/quality dial
-n, --n	integer	Number of images
--background	auto, opaque	Generation background
--moderation	auto, low	Generation moderation setting
--format	png, jpeg, webp	Output encoding
--compression	0-100	JPEG/WebP compression
--user	string	Optional end-user identifier
--dangerously-bypass-approvals-and-sandbox	boolean	Forward Codex's dangerous bypass flag for trusted local runs only
--codex-timeout	seconds	Timeout for the delegated Codex run
--log-file	path	JSONL timing diagnostics path
--no-log	boolean	Disable timing diagnostics

Quality policy:

• low: cheap drafts, broad exploration, many variants.
• medium: normal exploration, style probing, balanced cost.
• high: final assets, Chinese text, posters, diagrams, UI, paper figures, dense labels.

Size policy:

• default/social square: 1k / 1024x1024
• poster/mobile/beauty: portrait
• landscape/gameplay/photo: landscape
• print/paper figure: 2k
• widescreen hero: 4k
• vertical story/banner: tall

Delegation routing

Mode	Trigger	Delegated Codex inputs
Text-to-image	no -i	prompt + requested output path(s)
Reference edit	one or more -i	prompt + attached reference image(s)
Inpaint	-i + -m	prompt + attached reference and mask image(s)

Surface Codex CLI errors verbatim enough for debugging; exit codes: 0 success, 1 generation/refusal/missing output, 2 bad args/missing Codex CLI.

Reference loading

• references/gallery.md: routing index for the 162-prompt Reference Gallery Atlas. Load first.
• references/gallery-*.md: concrete prompts, previews, paths, metadata, attribution. Load 1 category for normal requests; 2–3 for hybrids.
• references/craft.md: prompt-craft checklist. Load for prompt repair, exact text, UI/data/diagram grammar, edit invariants, and multi-panel consistency.
• references/openai-cookbook.md: official parameter/model semantics. Load for API behavior or model capability questions.

Reference loading policy: load the smallest useful slice; never load all category files by default.

Verification

• Before API call: confirm endpoint mode, size, quality, output path, and required reference/mask files.
• After CLI call: report path(s) printed by the CLI and surface stderr on failure.
• For edits/inpaints: verify -i paths exist; verify -m exists when used.

Preserve Curated vs Author + Source metadata when adapting examples. Add new collected prompts to the Reference Gallery before README promotion.