Generate and Edit Images with GPT Image Skill

What GPT Image Skill Does

GPT Image Skill lets Codex, Claude Code, and compatible local agents generate or edit images through the user's ChatGPT subscription. It uses Codex's built-in $imagegen, or a host-native image_gen tool when one is available. It does not call the OpenAI Images API or create a separately billed Images API request.

The skill accepts natural-language prompts and readable local PNG, JPEG, or WebP references. It saves generated PNG files under the active project's generated-images/ directory and returns the resulting path and inline Markdown preview information.

Image generation consumes included ChatGPT or Codex usage and remains subject to plan and workspace limits. Image generations can use included limits faster than comparable non-image turns, so keep parallel batches intentional and small.

Key Features

• Generates images through ChatGPT-authenticated Codex rather than an API key.
• Installs the same gpt-image skill for Codex and Claude Code.
• Preserves a direct image prompt without adding unsolicited creative details.
• Develops distinct prompts when the user explicitly delegates multiple concepts or design directions.
• Supports one or more references in deterministic attachment order.
• Supports edits, follow-up revisions, variations, compositing, transparency, exact text, and dense-layout drafts.
• Runs independent image jobs with default concurrency 2 and a maximum of 4.
• Saves files only inside the active workspace and avoids overwriting existing images by default.
• Supports macOS, Linux, native Windows, and WSL2.
• Blocks API-key login and removes relevant API environment variables from Codex child processes.

Requirements

Before installing the skill, make sure the environment has the following components:

• Node.js 22 or newer: The current supported LTS release is recommended.
• Git: Required when cloning the project from GitHub.
• Codex CLI: It must be signed in with ChatGPT unless the calling host exposes a native image_gen tool.
• An eligible plan: The ChatGPT or Codex plan and workspace must permit image generation.

WSL1 is unsupported. When using WSL2, keep Node.js, Codex, the repository, and the working project on the Linux side. Store the clone under the Linux home directory rather than /mnt/c.

Install Through a Local Agent

The simplest setup method is to ask Codex, Claude Code, or another compatible agent to install the repository. Direct the agent to read AGENT_INSTALL.md, perform a persistent clone or safe fast-forward update, create the Codex and Claude Code links, start ChatGPT device authorization, and run:

bootstrap --target all --yes --json

The readiness report should end with ok: true, status: ready, and best_practice_pass: true. The user personally completes browser or device authorization. The skill does not request a password, token, API key, or the contents of ~/.codex/auth.json.

The installation process is not supposed to generate a live image. It should conclude with a short getting-started guide containing common aspect ratios, quality phrases, and example creation and reference requests.

Manual Installation

macOS, Linux, and WSL2

Use a persistent clone because the installed skill links point to the repository:

REPOSITORY_URL="https://github.com/GENEXIS-AI/gpt-image-skill"
INSTALL_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/gpt-image-skill"

git clone "$REPOSITORY_URL" "$INSTALL_DIR"
cd "$INSTALL_DIR"
node ./gpt-image/scripts/validate_skill.mjs
node ./gpt-image/scripts/gpt_image.mjs bootstrap --target all --yes --json

Native Windows PowerShell

$RepositoryUrl = "https://github.com/GENEXIS-AI/gpt-image-skill"
$InstallDir = Join-Path $env:LOCALAPPDATA "gpt-image-skill"

git clone $RepositoryUrl $InstallDir
Set-Location $InstallDir
node .\gpt-image\scripts\validate_skill.mjs
node .\gpt-image\scripts\gpt_image.mjs bootstrap --target all --yes --json

On macOS, Linux, and WSL2, installation creates symlinks. Native Windows uses directory junctions. Existing unrelated paths are not replaced.

• Codex installation: ~/.agents/skills/gpt-image
• Claude Code installation: ~/.claude/skills/gpt-image
• Windows Codex installation: $env:USERPROFILE\.agents\skills\gpt-image
• Windows Claude Code installation: $env:USERPROFILE\.claude\skills\gpt-image

Generate Your First Image

After installation, invoke the skill directly from the host. In Codex, use:

$gpt-image A cobalt-blue glass robot on a warm off-white background.

In Claude Code, use:

/gpt-image A cobalt-blue glass robot on a warm off-white background.

You can express framing and quality naturally:

$gpt-image Create a cozy reading room at sunset, 16:9, high quality.

Common requests include 1:1, 16:9, 9:16, 4:3, and 3:4. Useful quality phrases include draft, high quality, and high detail / final quality. These are natural-language requests rather than a fixed API size list, so exact pixel dimensions can vary.

Use the Direct Runner

From the repository, you can call the Node.js runner explicitly:

node ./gpt-image/scripts/gpt_image.mjs generate \
  --prompt "A cobalt-blue glass robot on a warm off-white background." \
  --out "generated-images/glass-robot.png"

Normal generation performs a quick ChatGPT authentication check, creates one image, runs a minimal PNG sanity check, and returns PATH=... plus an absolute MARKDOWN=... value.

Generate an Image from a Reference

References must be actual readable files. In Claude Code, prefer an @path or an explicit filesystem path:

/gpt-image Use @references/robot.png as the character reference. Draw it riding a bicycle.

A pasted or dragged image shown in Claude is not automatically inherited by a nested Codex process. If Claude exposes an exact temporary attachment path, the agent can copy that file into generated-images/inputs/. Otherwise, save the image inside the project and provide its path. The skill does not guess which file to use from Claude's image cache.

The equivalent direct command is:

node ./gpt-image/scripts/gpt_image.mjs generate \
  --mode generate \
  --prompt "Draw this character riding a bicycle." \
  --reference "/absolute/path/robot.png" \
  --out "generated-images/robot-bicycle.png"

Attach Multiple References

Repeat --reference in the required order. Add matching roles only when the references have explicit roles:

node ./gpt-image/scripts/gpt_image.mjs generate \
  --prompt "Use Image 1 for the character and Image 2 for the bicycle design." \
  --reference "/absolute/path/character.png" \
  --reference-role "character" \
  --reference "/absolute/path/bicycle.png" \
  --reference-role "bicycle design" \
  --out "generated-images/combined.png"

For an edit, the edit target is Image 1. Supporting references follow it in command-line order.

Edit and Revise an Image

Use --mode edit with --edit-target to modify an existing image:

node ./gpt-image/scripts/gpt_image.mjs generate \
  --mode edit \
  --prompt "Replace the bicycle basket with a small wooden crate." \
  --edit-target "generated-images/robot-bicycle.png" \
  --out "generated-images/robot-bicycle-crate.png"

For every follow-up revision, edit the latest result rather than returning to the original source:

node ./gpt-image/scripts/gpt_image.mjs generate \
  --mode edit \
  --prompt "Make the wooden crate dark green." \
  --edit-target "generated-images/robot-bicycle-crate.png" \
  --out "generated-images/robot-bicycle-green-crate.png"

Reattach every supporting reference that remains necessary. Each bridge invocation is ephemeral, so it does not automatically retain earlier attachments. Editing the original source instead of the latest output would discard the previous revision.

Run Multiple Images in Parallel

Use generate for the one-image path. For two or more ready jobs, the skill can use a bounded batch. Default concurrency is 2 and the maximum is 4. Authentication is checked once for the batch, and failed jobs are not retried automatically.

The batching model supports three common structures:

• Shared-anchor variations: Every job reads the same existing design and applies a different style.
• Delegated concepts: The agent creates one complete and meaningfully different prompt for each requested design direction while preserving shared constraints.
• Repeated renders: When no differences are requested, each job reuses the exact prompt.

Create a workspace-local manifest such as image-jobs.json:

{
  "version": 1,
  "jobs": [
    {
      "id": "watercolor",
      "mode": "variation",
      "prompt": "Keep the same design and render it in watercolor style.",
      "edit_target": "references/base-design.png",
      "references": ["references/watercolor-style.png"],
      "reference_roles": ["style reference for this output"],
      "out": "generated-images/design-watercolor.png"
    },
    {
      "id": "clay",
      "mode": "variation",
      "prompt": "Keep the same design and render it in clay style.",
      "edit_target": "references/base-design.png",
      "references": ["references/clay-style.png"],
      "reference_roles": ["style reference for this output"],
      "out": "generated-images/design-clay.png"
    }
  ]
}

Run the manifest with:

node ./gpt-image/scripts/gpt_image.mjs batch \
  --manifest "image-jobs.json" \
  --concurrency 2

Several jobs may safely read the same anchor. Attach only the relevant style reference to each output. For unrelated concepts, omit the common edit_target and give each job a standalone prompt and its own references.

A result created by one batch job cannot become another job's input in that same batch. Run workflows with output-to-input dependencies in stages. If no common anchor exists, generate the first requested output and use its returned path for later variants; the skill does not create an extra hidden anchor.

Advanced Usage Tips

Preserve Prompt Intent

For a single direct request, the user's wording is authoritative and is forwarded unchanged. If the user asks for several different designs, concepts, directions, options, or alternatives, the delegated creative intent is also authoritative. In that case, the agent develops a distinct image-ready prompt for each output while preserving the common subject, brand, text, references, aspect ratio, and other constraints.

Job numbers belong in manifest IDs and filenames, not in image prompts. Avoid adding phrases such as this is the second option.

Choose the Correct Mode

• Use --mode generate for text-to-image work.
• Add --reference PATH for a new image guided by an existing file.
• Use --mode edit --edit-target PATH to change an existing image.
• Use --mode variation --edit-target PATH for a variation of an existing design.
• Use --background transparent only when transparency is requested.
• Use the same edit target in multiple variation jobs for one composition rendered in different styles.
• Use the same image as a reference in multiple generation jobs when the identity should appear in different scenes or layouts.

Avoid Accidental Overwrites

The runner does not overwrite an existing image unless --overwrite is explicit. Give each result a descriptive output path under generated-images/.

Troubleshooting and Setup Checks

Planning and detailed diagnostics are optional. They are not required before normal generation. Use them when setup, authentication, references, or output files need investigation:

node ./gpt-image/scripts/gpt_image.mjs doctor --json
node ./gpt-image/scripts/gpt_image.mjs guide
node ./gpt-image/scripts/gpt_image.mjs capabilities --json
node ./gpt-image/scripts/gpt_image.mjs inspect \
  --input "generated-images/combined.png" --json

To check sign-in and paths without creating an image:

node ./gpt-image/scripts/gpt_image.mjs generate \
  --prompt "test" \
  --out "generated-images/test.png" \
  --dry-run --json

To validate a batch manifest and its scheduling without signing in or generating images:

node ./gpt-image/scripts/gpt_image.mjs batch \
  --manifest "image-jobs.json" \
  --check-only --json

Generated images receive lightweight file and signature checks rather than SHA-256 receipts. SHA-256 remains available where it is meaningful, such as installer verification:

node ./gpt-image/scripts/gpt_image.mjs verify-installers --json

Security and Privacy Safeguards

• The skill removes OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_ORG_ID, OPENAI_PROJECT_ID, and CODEX_ACCESS_TOKEN from Codex child processes.
• Generation is blocked unless redacted diagnostics establish ChatGPT authentication.
• No OpenAI Images API endpoint or /v1/images request is included.
• The skill does not read authentication files.
• Generated files remain inside the active workspace.
• When subscription limits are reached, the runner does not fall back to the Images API.

Update the Skill

On macOS, Linux, or WSL2, fast-forward the persistent clone and rerun bootstrap:

INSTALL_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/gpt-image-skill"
git -C "$INSTALL_DIR" pull --ff-only
node "$INSTALL_DIR/gpt-image/scripts/gpt_image.mjs" \
  bootstrap --target all --yes --json

On native Windows PowerShell:

$InstallDir = Join-Path $env:LOCALAPPDATA "gpt-image-skill"
git -C $InstallDir pull --ff-only
node "$InstallDir\gpt-image\scripts\gpt_image.mjs" bootstrap --target all --yes --json

Conclusion

GPT Image Skill provides a workspace-focused way to generate and edit images from Codex, Claude Code, or another compatible agent using ChatGPT authentication. Start with a direct natural-language request, provide stable local paths for references, use the latest output for each revision, and reserve bounded batches for independent concepts or shared-anchor variations.

For the installation contract and deeper workflow details, visit the GPT Image Skill repository.