GENEXIS-AI/gpt-image-skill

GPT Image Skill

Generate or edit one raster image—or a small set of independent 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

1. Use the host's image_gen tool directly when it is available. Do not install Node.js or start nested Codex in that case.
2. 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

• Treat the user's image prompt as authoritative and pass it through unchanged.
• Do not rewrite, expand, optimize, translate, beautify, or add creative guidance.
• Do not invent composition, lighting, style, color, objects, materials, text, negative prompts, or preservation rules.
• 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"

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.

Run independent images in parallel

Use the CLI batch command only when the user requests two or more independent final images. Read the batch section of image-workflows.md, write one workspace-local JSON manifest, then run batch --manifest <path>. The default concurrency is 2 and the maximum is 4. The batch checks ChatGPT auth once for the whole run and does not run Doctor, planning, inspection, or retries per job.

Never put a revision chain in one batch. If image B edits image A, generate A first and then use its returned path in a normal sequential generate --mode edit call. Each parallel job consumes included Codex image-generation usage separately. 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

Call the native image tool once with the user's prompt unchanged. 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 the selected result to <workspace>/generated-images/ and render its absolute path.

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>)