GPT Image Agent Skill

GPT Image Skill

Generate or edit one or more raster images, save results under the current workspace, and show them in chat.

Keep the subscription boundary

• Never call the OpenAI Images API or fall back to a separately billed route.
• Never use, request, inspect, print, or forward OPENAI_API_KEY.
• Never use codex login --with-api-key or read ~/.codex/auth.json.
• Require explicit ChatGPT auth before the bridge generates an image.
• Stop when API-key auth is detected. Replace authentication only after a separate explicit user choice.

Choose the route

• Use the host's image_gen tool directly when it is available. Do not install Node.js or start nested Codex in that case.
• Otherwise use scripts/gpt_image.mjs. Claude Code and generic local agents need Node.js 22+, Codex CLI, and Sign in with ChatGPT in the same OS environment.

Read image-workflows.md for references, Claude attachments, edits, follow-up revisions, or multiple images. Read subscription-runtime.md for authentication or architecture. Read platform-setup.md only when setup is missing or uncertain.

Preserve the user's request

• For a direct image or edit request, treat the user's image prompt as authoritative and pass it through unchanged. Do not rewrite, expand, optimize, translate, beautify, or add creative guidance.
• Distinguish repeated renders from delegated concept development. “Make five images with this exact prompt” means repeat the same prompt. “Make five different designs/concepts/options” means the user has asked the agent to develop five distinct creative directions.
• For delegated concepts, preserve every explicit subject, product, reference, brand, text, ratio, quality, and exclusion constraint, then write one standalone image-ready prompt per output. Make the concepts meaningfully different in composition and art direction; do not merely number the same prompt.
• Never append ordinal or orchestration metadata such as “this is the first of five,” “1st option,” or “1번째 시안” to an image prompt. The job id and output path carry ordering.
• When the user names the individual directions, follow those directions instead of replacing them. When the user does not delegate creative differences, do not invent them.
• Outside creative choices the user delegated, add a constraint only when the user explicitly supplied it through the prompt or a runner flag.
• Ask one concise question only when missing information makes the requested operation impossible. Otherwise generate without prompt coaching.

Resolve references before generation

• Require a real, readable local path for every bridge reference and edit target.
• In Claude Code, prefer an explicit @path or filesystem path. If the attachment context exposes an exact readable temporary path, copy that exact file non-destructively into <workspace>/generated-images/inputs/ and use the copy. If Claude can see the image but exposes no path, stop before generation and ask the user to save it in the workspace and provide that path.
• Never silently omit an unresolved image, replace it with a text description, or guess a file from ~/.claude/image-cache.
• Use --reference when an image guides a new image. Use --edit-target when that exact image must be changed.
• For a follow-up such as “change the last result,” use the previously returned output as the new --edit-target. Do not reuse the original source by mistake.
• Treat every bridge call as ephemeral. Reattach the current edit target and every still-needed reference on every revision.
• Keep the final absolute output path in the response so the next turn can reuse it.

Bootstrap the bridge

Resolve this installed skill directory from the loaded SKILL.md; ${CLAUDE_SKILL_DIR} points to it in Claude Code. Quote paths containing spaces.

Check node --version first. If Node.js is absent or older than 22, follow platform-setup.md. After the user authorizes user-level skill links, Codex installation, and device login, run:

node <skill-folder>/scripts/gpt_image.mjs bootstrap --target all --yes --json

The command installs non-destructive Codex and Claude skill links, installs a missing Codex CLI from the official platform installer, starts Sign in with ChatGPT when signed out, and returns one consolidated readiness report plus getting_started. It reuses the auth result already obtained during setup rather than running a second diagnostic pass. It does not generate an image or require a no-image setup check.

After successful installation, present getting_started once in the user's language. Keep it brief: say setup is ready, list common ratio requests (1:1, 16:9, 9:16, 4:3, 3:4), mention natural-language quality phrases (draft, high quality, high detail, final quality), and show one creation example plus one reference or revision example. Explain that exact pixel dimensions may vary. Do not repeat this guide after ordinary image requests.

Do not say “dry-run” without explanation. When troubleshooting requires the literal --dry-run flag, describe it to the user as a setup check that does not create an image.

Use doctor --json for diagnosis. Follow its next_action; never improvise an API route. Keep Windows runtimes on native Windows and Linux runtimes inside WSL2. WSL1 is unsupported.

Generate with the bridge

Run the requested generation directly. Do not run doctor, plan, inspect, capabilities, or the no-image setup check (--dry-run) first unless the user asks or a real error needs diagnosis.

node <skill-folder>/scripts/gpt_image.mjs generate \
  --prompt "<user prompt verbatim>" \
  --out "generated-images/<descriptive-name>.png"

For reference-guided generation, repeat --reference. Add --reference-role only when the user states a relationship that is not already clear in the prompt.

node <skill-folder>/scripts/gpt_image.mjs generate \
  --mode generate \
  --prompt "<user prompt verbatim>" \
  --reference "<stable local path>" \
  --out "generated-images/<name>.png"

For an edit or follow-up revision, attach the current image as the primary target:

node <skill-folder>/scripts/gpt_image.mjs generate \
  --mode edit \
  --prompt "<user's exact revision request>" \
  --edit-target "<previous output path>" \
  --out "generated-images/<revised-name>.png"

Transparent background

Treat an explicit transparent-background request, including the literal option background="transparent", as an image-generation output option rather than extra creative prompt text.

• With a host-native image_gen tool, keep the user's prompt unchanged and pass background="transparent" through the tool's actual background parameter when that parameter is available. Use a PNG-capable output so alpha transparency can be preserved.
• With the CLI bridge, translate the same request to --background transparent. The bridge must route that setting into the built-in $imagegen call and the saved PNG must contain real alpha transparency.
• Do not fake transparency with a checkerboard pattern, white background, solid color, or background-removal description.
• If the active native image tool exposes no background option, do not claim that transparency is guaranteed. Prefer the bridge when available; otherwise report that actual alpha transparency cannot be verified.

node <skill-folder>/scripts/gpt_image.mjs generate \
  --prompt "<user prompt verbatim>" \
  --background transparent \
  --out "generated-images/<transparent-name>.png"

Use --region, --preserve, --avoid, --exact-text, --size, --quality, or --background only when the user explicitly supplied those details. The runner attaches the edit target first, then references in command-line order; strips API-related environment variables; verifies ChatGPT auth once; invokes built-in $imagegen; and saves a new PNG without overwriting by default.

Generate multiple images

When the user requests two or more outputs, use parallel calls for every job whose image inputs already exist. With the CLI bridge, read the multi-image section of image-workflows.md, write one workspace-local manifest, and run batch --manifest <path>. Do not make the user ask for batch explicitly.

Classify the request once without running a planning command:

• Same design, different styles: reuse one shared design anchor. For the same composition with style changes, run parallel variation jobs with the same edit_target. For the same character or product in new scenes or layouts, run parallel generate jobs with the same first reference. Use user-named styles, or choose distinct style concepts when the user delegated that choice. Attach only that job's style reference after the shared anchor.
• Different design concepts: when the user asks for different designs, concepts, directions, options, or alternatives, develop one complete creative concept and image-ready prompt per output, keep the shared brief and references, then run them together. Do this internally in one pass; do not run a separate planning command or ask for concept approval unless the user requested it.
• Repeated renders: when the user requests several images but does not ask for different concepts—or explicitly says to use the same prompt—reuse the exact image prompt for each independent job.
• No anchor yet: generate the first requested output normally, then use that returned image as the shared anchor for the remaining parallel jobs. Do not generate an extra hidden anchor that the user did not request.

Never put an output-dependent revision in the same batch as its source. In a mixed request, batch all currently ready jobs, resolve the dependency, then batch the newly ready jobs. The default concurrency is 2 and the maximum is 4. A batch checks ChatGPT auth once and does not run Doctor, planning, inspection, or retries per job. If a limit rejects a job, report it without switching to an API route. Use --check-only only when the user requests a precheck or the manifest fails; describe it as checking the batch without creating images.

Generate with a native host

For one direct output, call the native image tool once with the user's prompt unchanged. For multiple outputs, finalize one prompt per output under the rules above, then issue one call per output concurrently when the host supports it and the calls have no unresolved dependency. Apply the same shared-anchor versus independent-concept routing. Pass the primary edit target and all references through the host's actual image-input mechanism; do not merely describe them in text. On a follow-up, include the last generated image as the edit target plus any still-needed references. Save or copy every result to <workspace>/generated-images/ and render each absolute path. When the user explicitly requests a transparent background or supplies background="transparent", pass that as the native tool's background option when supported rather than appending it to the prompt.

Finish lightly

Report success when:

• generation used native image_gen or the ChatGPT-authenticated Codex bridge;
• every requested reference was actually attached;
• every output exists inside the workspace and has usable PNG bytes;
• the response contains each absolute path and inline image.

Do not require SHA-256, a plan, a no-image setup check, a large receipt, or a separate visual-inspection gate for normal generation. Check real transparency only when the user explicitly requests transparent output. Never star the repository automatically; request a Star politely only after a successful result.

![generated image](</absolute/path with spaces/generated-image.png>)