GPT Image 2 skill

A small, script-first Agent Skill for generating and editing images through OpenAI’s gpt-image-2 Image API.

The repository ships maintained CLI code so an agent chooses an operation and passes flags instead of inventing an API call. The distributable skill contains no API key, .env, generated image, or dependency cache.

What is included

gpt-image/
├── SKILL.md
├── agents/openai.yaml
├── references/prompting-guide.md
└── scripts/
    ├── _common.py
    ├── configure.py
    ├── edit.py
    └── generate.py

Production runtime: four focused Python files. uv resolves the pinned OpenAI SDK on first use.

Requirements

• Python 3.10 or newer
• uv
• An OpenAI API key with access to gpt-image-2
• API network access from the runtime

OpenAI may require API organization verification for GPT Image models.

Configure without modifying the skill

Preferred for CI, hosted shells, and existing OpenAI setups:

export OPENAI_API_KEY="your-key"

Convenient for an interactive local machine:

python gpt-image/scripts/configure.py

The second command hides terminal input and stores the key in a user-owned operating-system config directory with owner-only permissions on POSIX. It never writes into gpt-image/, so repackaging or updating the skill cannot include the configured key. Remove it with:

python gpt-image/scripts/configure.py --remove

Do not put credentials in SKILL.md, .env files beside the scripts, prompts, or archives. In a hosted environment, the host must inject OPENAI_API_KEY; a skill upload cannot do that for you.

Run directly

Generate:

uv run --script gpt-image/scripts/generate.py \
  --prompt "A vintage 1960s travel poster for Kyoto in autumn" \
  --size 1024x1536 \
  --quality high \
  --output kyoto.png

Edit:

uv run --script gpt-image/scripts/edit.py \
  --prompt "Replace the sky with a thunderstorm; preserve everything else" \
  --images photo.jpg \
  --output photo-stormy.png

Composite:

uv run --script gpt-image/scripts/edit.py \
  --prompt "Place the dog from Image 2 next to the person in Image 1; match scale and light" \
  --images scene.png dog.png \
  --output composite.png

Run either script with --help for the complete, current CLI. Existing output files are protected unless --force is supplied.

Install as a local skill

Clone the repository, then copy or link the gpt-image/ directory itself into the skill directory used by your agent. The required layout is /gpt-image/SKILL.md; cloning the whole repository directly to that path leaves the manifest one level too deep.

For example:

git clone https://github.com/dshark3y/gpt-image-2-skill.git
mkdir -p ~/.claude/skills
cp -R gpt-image-2-skill/gpt-image ~/.claude/skills/gpt-image

Restart or reload the agent after installing.

Build a clean archive

The package builder uses a fixed allowlist, rejects high-confidence secrets, and emits deterministic ZIP bytes with one top-level gpt-image/ folder:

python tools/package_skill.py --output dist/gpt-image.skill
python tools/package_skill.py --output dist/gpt-image.zip

.skill is a compatibility filename used by some tools; the file itself is a ZIP archive. ZIP is the documented format for hosted OpenAI Skill uploads. Neither format bundles credentials, installs dependencies, or grants network access.

You can also validate and package a folder locally in your browser with the Agent Skill Validator & Packager.

Test

python -m unittest discover -s tests -v

Tests make no paid API requests. See the current OpenAI image guide for model capabilities and the Skills guide for hosted packaging limits.