gpt-image-skill — Claude Code image skill: features and setup
Generate or edit images through the OpenAI GPT Image API. The skill is for requests that name OpenAI or GPT, not for diagrams.
MIT 156 installs ★ 1,682 updated 2026-09-27
npx skills add feiskyer/claude-code-settings --skill gpt-image-skill -a claude-codeWhat gpt-image-skill does
The skill runs the Python script gpt_image.py to create an image from a text prompt or modify existing images. Editing accepts up to 3 input images. You can choose a GPT Image model, dimensions, quality, output format, and background; the result is saved to a chosen path or an automatically generated filename.
It requires OPENAI_API_KEY, Python 3, and the openai and Pillow libraries. Put the key in ~/.gpt-image.env or export it as an environment variable, then install dependencies from requirements.txt. A custom OPENAI_API_BASE can point to a compatible API endpoint. Requests cannot reach the API without a key. The skill is meant for prompts that explicitly name OpenAI or GPT; use Mermaid or code for diagrams.
What it helps with
- generate an image from a text prompt
- edit an existing image using instructions
- combine several reference images into one composition
- save an image in a chosen size and format
Example prompts for the agent
- Create a cover image from this description with OpenAI GPT and save it as
cover.png. - Use GPT to add a rainbow to
photo.pngand save the edited image asedited.png. - Combine
item1.png,item2.png, anditem3.pnginto one composition with OpenAI.
How to install gpt-image-skill
1Skills CLI (Vercel)
npx skills add feiskyer/claude-code-settings --skill gpt-image-skill -a claude-code2Manually: put the files in place
~/.claude/skills/gpt-image-skill/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gpt-image-skill/
1Skills CLI (Vercel)
npx skills add feiskyer/claude-code-settings --skill gpt-image-skill -a codex2Manually: put the files in place
.agents/skills/gpt-image-skill/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add feiskyer/claude-code-settings --skill gpt-image-skill -a cursor2Manually: put the files in place
.cursor/skills/gpt-image-skill/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install feiskyer/claude-code-settings skills/gpt-image-skill2Manually: put the files in place
.github/skills/gpt-image-skill/SKILL.md1Skills CLI (Vercel)
npx skills add feiskyer/claude-code-settings --skill gpt-image-skill -a gemini-cli2Platform CLI
gemini skills install https://github.com/feiskyer/claude-code-settings --path skills/gpt-image-skillManually: put the files in place
.devin/skills/gpt-image-skill/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add feiskyer/claude-code-settings --skill gpt-image-skill -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about gpt-image-skill
How do I install gpt-image-skill in Claude Code?
Run npx skills add feiskyer/claude-code-settings --skill gpt-image-skill -a claude-code. The skill file is placed at ~/.claude/skills/gpt-image-skill/SKILL.md.
What does gpt-image-skill do?
It generates images through the OpenAI GPT Image API and edits existing images from text instructions. It runs the gpt_image.py script to do this.
What does gpt-image-skill need to run?
It requires OPENAI_API_KEY, Python 3, and the openai and Pillow libraries. Editing also requires readable input image files.
Source text
SKILL.md · MIT
---
name: gpt-image-skill
description: 'Generate or edit images using OpenAI GPT Image API (gpt-image-2, gpt-image-1, etc). Use ONLY when the user explicitly names OpenAI or GPT as the provider: "gpt image", "openai image", "generate image with openai", "用 openai 画图", "用 GPT 生成图片". For generic image requests without a provider, use nanobanana-skill instead. Do NOT use for diagrams (架构图/流程图) — draw those with Mermaid or code.'
allowed-tools: Read, Write, Glob, Grep, Task, Bash(cat:*), Bash(ls:*), Bash(tree:*), Bash(python3:*)
---
# GPT Image Skill
Generate or edit images using OpenAI's GPT Image models through a bundled Python script.
## Requirements
1. **OPENAI_API_KEY**: Must be configured in `~/.gpt-image.env` or `export OPENAI_API_KEY=<your-key>`
2. **OPENAI_API_BASE** (optional): Custom API base URL for compatible endpoints (e.g. Azure OpenAI, proxies). Set in `~/.gpt-image.env` or export it.
3. **Python3 with dependencies**: openai, Pillow. Install via `python3 -m pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt` if not installed yet.
4. **Executable**: `${CLAUDE_SKILL_DIR}/gpt_image.py`
## Instructions
### For image generation
1. Ask the user for:
- What they want to create (the prompt)
- Desired size (optional, defaults to 1024x1024)
- Output filename (optional, auto-generates UUID-based name if not specified)
- Model preference (optional, defaults to gpt-image-2)
- Quality (optional, defaults to auto)
- Number of images (optional, defaults to 1)
2. Run the script:
```bash
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py --prompt "description of image" --output "filename.png"
```
3. Show the user the saved image path when complete.
### For image editing
1. Ask the user for:
- Input image file(s) to edit (up to 3)
- What changes they want (the prompt)
- Output filename (optional)
2. Run with input images:
```bash
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py edit --prompt "editing instructions" --input image1.png image2.png --output "edited.png"
```
## Available Options
### Models (--model)
- `gpt-image-2` (default) — Latest model with strong instruction following, text rendering, and broad world knowledge
- `gpt-image-1.5` — Mid-tier model
- `gpt-image-1` — First-generation GPT image model
- `gpt-image-1-mini` — Lightweight, faster generation
### Sizes (--size)
- `1024x1024` (default) — Square
- `1024x1536` — Portrait (2:3)
- `1536x1024` — Landscape (3:2)
- `auto` — Let the model decide
### Quality (--quality)
- `auto` (default) — Model decides optimal quality
- `high` — Higher detail, slower
- `medium` — Balanced
- `low` — Fastest
### Output Format (--format)
- `png` (default) — Lossless
- `jpeg` — Smaller file size
- `webp` — Modern format, good compression
### Background (--background)
- `auto` (default) — Model decides
- `transparent` — Transparent background (png/webp only)
- `opaque` — Solid background
### Other Options
- `--n <count>` — Number of images to generate (default: 1)
- `--output <filename>` — Output filename (default: auto-generated)
## Examples
### Generate a simple image
```bash
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py --prompt "A serene mountain landscape at sunset with a lake"
```
### Generate with specific size and output
```bash
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
--prompt "Modern minimalist logo for a tech startup" \
--size 1024x1024 \
--quality high \
--output "logo.png"
```
### Generate landscape image
```bash
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
--prompt "Futuristic cityscape with flying cars" \
--size 1536x1024 \
--output "cityscape.png"
```
### Generate with transparent background
```bash
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
--prompt "A cute cartoon cat mascot" \
--background transparent \
--format png \
--output "mascot.png"
```
### Generate multiple images
```bash
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
--prompt "Abstract art in the style of Kandinsky" \
--n 3 \
--output "art.png"
```
### Edit existing images
```bash
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py edit \
--prompt "Add a rainbow in the sky" \
--input photo.png \
--output "photo-with-rainbow.png"
```
### Combine multiple reference images
```bash
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py edit \
--prompt "Create a gift basket containing all items shown" \
--input item1.png item2.png item3.png \
--output "gift-basket.png"
```
### Use a different model
```bash
python3 ${CLAUDE_SKILL_DIR}/gpt_image.py \
--prompt "Detailed portrait of a cat in watercolor style" \
--model gpt-image-1 \
--output "cat-portrait.png"
```
## Error Handling
If the script fails:
- Check that `OPENAI_API_KEY` is exported
- If using a custom endpoint, verify `OPENAI_API_BASE` is correct
- Verify input image files exist and are readable (for editing)
- Ensure the output directory is writable
- Check that the model name is valid
## Best Practices
1. Be descriptive in prompts — include style, mood, colors, composition details
2. For logos/icons, use square size (1024x1024) with transparent background
3. For social media, use portrait (1024x1536) for stories or square for posts
4. For wallpapers/headers, use landscape (1536x1024)
5. Use `high` quality for final output, `auto` for quick iterations
6. GPT Image models excel at text rendering — include text in prompts when needed
7. For editing, provide clear instructions about what to change and what to keep
© feiskyer · MIT · feiskyer/claude-code-settings