gen-image

name	gen-image
description	Generate asset/texture images for this project via OpenRouter's openai/gpt-5.4-image-2 model. Use when the user asks to generate, create, draft, or regenerate art, sprites, icons, textures, UI assets, or any image from a text prompt, optionally with one or more reference images. Saves files into the project's assets directory.
allowed-tools	["Bash","Read","Write"]

gen-image: asset image generator

Calls openai/gpt-5.4-image-2 via OpenRouter using the local OPENROUTER_API_KEY. Saves PNGs into assets/generated/ by default. Supports text-only generation and image-referenced generation.

Asset modes

Use --mode for project assets unless the user explicitly wants a raw, unconstrained generation. --mod is accepted as an alias. Mode names and numbers are both accepted.

Mode 1: character

For characters, NPCs, monsters, and the cat protagonist.

• Style: 2D pixel art
• Background: #FF00FF
• Frame size: 64x64
• Default frames: 4
• Default layout: 1x4
• Default canvas: 256x64

If the prompt action is walk / walking / move / moving / 移动 / 行走:

• Generate all four directions in one sheet: down, left, right, up
• Each direction has 4 frames
• Layout: 4x4
• Canvas: 256x256

Mode 2: map

For scenes, rooms, biomes, and room backgrounds.

• Resolution: 640x360
• Style: 2D top-down / 3/4 pixel art
• Full scene image, no magenta background
• Single image, no frame slicing
• No UI, no text
• No characters by default unless the prompt explicitly asks

Mode 3: item_gpu

For items, GPUs, devices, machines, and props.

• Style: 2D pixel art
• Background: #FF00FF
• Frame size: 64x64
• Frames: 4
• Layout: 1x4
• Canvas: 256x64

Mode 4: ui

For UI assets. Select with --ui-subtype.

Subtype	Size	Frames	Background
icon_small	16x16	1	#FF00FF
icon	32x32	1	#FF00FF
icon_large	64x64	1	#FF00FF
button	160x48	1	transparent-ready / #FF00FF
panel	320x180	1	transparent-ready / #FF00FF
card	180x240	1	transparent-ready / #FF00FF
popup	360x200	1	transparent-ready / #FF00FF

Mode 5: fx

For visual effects.

• Style: 2D pixel art
• Background: #FF00FF
• Default frame size: 64x64
• Default frames: 4
• Default layout: 1x4
• Default canvas: 256x64
• Large FX: --fx-size large, frame size 96x96, canvas 384x96

Preflight

test -n "$OPENROUTER_API_KEY" && echo OK || echo "MISSING OPENROUTER_API_KEY"
command -v python3 >/dev/null && echo PY_OK || echo "MISSING python3"

If OPENROUTER_API_KEY is missing, stop and ask the user to export it (export OPENROUTER_API_KEY=sk-or-...) before retrying. Do not hard-code the key into any file.

Usage

Invoke the script from the project root:

python3 .claude/skills/gen-image/scripts/generate.py \
  --mode character \
  --prompt "kitten miner holding a pickaxe idle animation" \
  -n 4 \
  --output-dir assets/generated/kitten-miner

With reference images:

python3 .claude/skills/gen-image/scripts/generate.py \
  --mode character \
  --prompt "redraw this kitten miner as a walking sprite" \
  --reference-image assets/2d/spritesheet/characters/player/idle/down-1.png \
  --reference-image assets/2d/spritesheet/characters/player/idle/right-1.png \
  -n 2 \
  --output-dir assets/generated/kitten-miner

UI example:

python3 .claude/skills/gen-image/scripts/generate.py \
  --mode ui \
  --ui-subtype button \
  --prompt "green upgrade button with beveled pixel edges" \
  --output-dir assets/generated/ui

Flags:

Flag	Default	Notes
--prompt	(required)	Text prompt for the image
--mode, --mod	none	1/character, 2/map, 3/item_gpu, 4/ui, 5/fx; omit only for raw prompts
--ui-subtype, --subtype	icon	UI subtype when --mode ui is used
--fx-size	normal	Use large for 96x96 x 4 = 384x96 FX sheets
-n, --num	1	How many images to generate (one API call per image)
-o, --output-dir	assets/generated	Directory to write files into (created if missing)
--name	slug of prompt	Base filename
--size	mode target size	Override the image request size
--quality	model default	low / medium / high
--model	openai/gpt-5.4-image-2	Override model id
-r, --reference-image	none	Reference image path, URL, or data URL. Repeat for multiple images
--dry-run	off	Print request payload without calling API

Files are named <base>-<timestamp>-<NN>.<ext>. If the model returns multiple images in one response, they are suffixed -1, -2, ...

Choosing n

• Exploring a new concept: start with -n 4 to compare variants.
• Refining a locked design: -n 1 or -n 2 per iteration.
• Batch generating matching assets (e.g. a set of icons): issue one call per asset with distinct prompts, not a single -n 10 blob.

Each image is a separate API call, so cost scales linearly with n.

Output conventions

• Project-root-relative output paths only (stay inside assets/).
• Prefer project-root-relative reference image paths when using local assets.
• Do not commit generated images unless the user asks.
• If the response contains no image (content policy, rate limit, etc.), the raw JSON is saved next to the expected filename for debugging.

After generating

Read the file back with the Read tool so the user can see it:

Read({file_path: "/absolute/path/to/assets/generated/...png"})

Show all generated files this way before reporting DONE.

When to use this skill

• "generate a sprite for X"
• "draft some concept art for the mine background"
• "make 4 icon variants for the upgrade button"
• "regenerate the title screen art"
• "use this image as reference and make it match the game style"

When NOT to use

• Precise editing/compositing existing images where pixel-accurate preservation is required.
• Vector / SVG output (model returns raster).
• Reference-image workflows that require masking, inpainting, or control over exact regions.