gpt-image-2-skill: A Prompt Gallery, Agent Wrapper, and CLI for OpenAI Image Generation

Most image-generation workflows end up reinventing the same prompt gallery and the same retry loop. wuyoscar/gpt-image2-skill packages the OpenAI gpt-image-2 model behind a curated prompt library, a CLI, and a skill you can drop into Claude Code, Codex, OpenClaw, or Hermes. You describe the scene, the skill or CLI picks a prompt pattern, generates the image, and writes a PNG.

Why This Skill Matters

The repo ships three things in one: a curated prompt gallery organised into ~25 categories (anime, gaming, typography, research figures, tattoo design, and more) with a local split reference atlas (gallery.md index plus per-category gallery-*.md files); a prompt-craft checklist (craft.md) and a cached OpenAI cookbook (openai-cookbook.md); and the actual generation layer, which talks to OpenAI's /v1/images/generations and /v1/images/edits endpoints via OPENAI_API_KEY.

Supported agents: Claude Code, Codex, OpenClaw, Hermes Agent, and any "skill-capable agent runtime." CLI install goes through uvx --from git+.... Budget knobs include --quality and --size aliases. Exit codes are documented: 0 success, 1 API/refusal, 2 bad args.

Limitations worth knowing: --input-fidelity is unsupported on gpt-image-2 and silently dropped by the CLI; Codex's built-in image skill is black-box and switching to this local skill requires opting in; generated research figures should be treated as references, not drop-in academic assets. License is MIT.

Installation

Three install paths. Pick by environment.

For Claude Code (the README's recommended path):

/plugin marketplace add wuyoscar/gpt_image_2_skill
/plugin install gpt-image@wuyoscar-skills

For any agent that runs CLI tools:

uvx --from git+https://github.com/wuyoscar/gpt_image_2_skill gpt-image -p "a cat astronaut"

For manual placement into an agent's skills directory:

git clone https://github.com/wuyoscar/gpt_image_2_skill.git
export AGENT_SKILLS_DIR="/path/to/your/agent/skills"
ln -s "$PWD/skills/gpt-image" "$AGENT_SKILLS_DIR/gpt-image"

Before invoking, export your OpenAI key:

export OPENAI_API_KEY=sk-...

The README warns that an agent holding OPENAI_API_KEY can accidentally consume it on your behalf. Unset the variable before using the CLI directly if you want to keep the key agent-side only.

Real Workflow: Generate a Photorealistic Scene From a One-Line Intent

You want a hero image for a blog post: a photorealistic convenience store at night. No design skill, just a one-line prompt.

Step 1. From your terminal, run the CLI:

gpt-image -p "a photorealistic convenience store at 10pm" \
  --size 1k --quality high \
  -f store.png

Step 2. The CLI hits /v1/images/generations with the gpt-image-2 model and writes store.png in the working directory. Expect a 1024×1024 PNG (the 1k alias).

Step 3. Open the PNG. If the framing is off, edit the prompt to add camera direction or lighting cues rather than retrying with the same string — the prompt-craft checklist (craft.md) in the repo lists the levers that actually move the output (subject framing, lens, color palette, mood anchors).

Step 4. If you want a tighter quality knob, the README documents --quality values and --size aliases. The CLI exits with code 0 on success, 1 on API or refusal, 2 on bad args — script around those if you wrap the CLI.

Real Workflow: Mask-Based Inpainting on a Reference Image

You have an existing photo where you want to replace only the sky with an aurora. The skill supports multi-reference edits via /v1/images/edits with mask input.

Step 1. Prepare a working directory with the source photo (photo.jpg) and a binary mask (sky_mask.png) where white marks the area to replace. The mask convention follows OpenAI's image-edits endpoint.

Step 2. Run:

gpt-image -p "replace sky with aurora" \
  -i photo.jpg \
  -m sky_mask.png \
  -f aurora.png

Step 3. The CLI hits /v1/images/edits and writes the inpainted image to aurora.png. The reference image and the prompt jointly constrain the result; the prompt should describe only the area inside the mask (here, "aurora sky"), not the rest of the photo.

Step 4. Verify the mask was respected. If the result drifts outside the masked area, tighten the prompt and re-run. The prompt-craft checklist notes that mask-driven edits are most reliable when the prompt's spatial scope matches the masked region.

Step 5. If you want to chain inpainting into a multi-step flow (sky replacement, then subject recolor, then color grade), run the CLI multiple times with intermediate outputs as inputs. Each step's CLI invocation is independent; the skill does not bundle a multi-step pipeline.

Tips

• Use --size aliases (1k, 2k) for routine work; reach for --quality high only when you are committing to the result.
• Tighten prompts by adding one lever at a time (lighting, lens, palette) rather than rewriting — easier to A/B.
• Keep inpaint prompts spatially scoped to the masked region; describing unmasked parts confuses the model.
• Unset OPENAI_API_KEY before CLI-only runs if you want the agent to keep the key.
• Generated research figures are references, not academic assets — verify with the underlying paper before citing.
• Codex users need to opt in to this local skill explicitly; the built-in image skill is black-box and may shadow it.

When Not to Use This

If you only need a one-off image and have no intention of installing the skill into an agent, the OpenAI web UI or a single curl to /v1/images/generations is faster. This skill earns its setup cost when you want the curated prompt gallery, the inpainting flow, or the agent-skill wiring that lets your coding assistant generate images inline.

See the leaderboard for more creative skills.