Imagegen

Image Generation Skill

Generates or edits images for the current project (website assets, game assets, UI mockups, product mockups, logos, photorealistic images, infographics).

When to use

• Generate a new image (concept art, product shot, cover, website hero)
• Edit an existing image (inpainting, masked edits, background replacement, object removal)
• Batch runs (many prompts or many variants)

Decision tree (generate vs edit vs batch)

• If the user provides an input image OR says "edit/retouch/inpaint/mask" → edit
• Else if the user needs many different prompts/assets → generate-batch
• Else → generate

Environment — Priority Order

1st choice: Built-in image_generation_call (PREFERRED)

If built-in tool is available in this session → use it directly.
Best quality, no API key needed, platform-handled.
Skip all steps below if this works.

2nd choice: Custom endpoint via auth.json

Only if built-in tool is NOT available in this session.

Read credentials from ~/.config/imagegen/auth.json:

{
  "endpoint": "https://your-proxy-or-api/v1/images/generations",
  "api_key": "YOUR_KEY_HERE",
  "model": "cx/gpt-5.4-image"
}

Auto-detect and run:

python3 - <<'PY'
import json, os, subprocess, sys
from pathlib import Path

auth_path = Path.home() / '.config' / 'imagegen' / 'auth.json'
if not auth_path.exists():
    sys.exit("[imagegen] auth.json not found. See SETUP.md for instructions.")

auth = json.loads(auth_path.read_text())
endpoint = auth.get('endpoint', '').strip()
api_key  = auth.get('api_key', '').strip()
model    = auth.get('model', 'gpt-image-1').strip()

if not endpoint or not api_key:
    sys.exit("[imagegen] auth.json is missing 'endpoint' or 'api_key'.")

print(f"[imagegen] Using endpoint: {endpoint}")
print(f"[imagegen] Model: {model}")
PY

Full curl call:

python3 scripts/image_gen.py generate \
  --prompt "<PROMPT>" \
  --model "$(python3 -c "import json,pathlib; d=json.loads(pathlib.Path.home().joinpath('.config/imagegen/auth.json').read_text()); print(d.get('model','gpt-image-1'))")"\
  --out output/imagegen/<filename>.png

OR via direct curl (SSE stream):

ENDPOINT=$(python3 -c "import json,pathlib; d=json.loads(pathlib.Path.home().joinpath('.config/imagegen/auth.json').read_text()); print(d['endpoint'])")
API_KEY=$(python3 -c "import json,pathlib; d=json.loads(pathlib.Path.home().joinpath('.config/imagegen/auth.json').read_text()); print(d['api_key'])")
MODEL=$(python3 -c "import json,pathlib; d=json.loads(pathlib.Path.home().joinpath('.config/imagegen/auth.json').read_text()); print(d.get('model','gpt-image-1'))")

curl -sS -N -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: text/event-stream" \
  -d "{\"model\":\"$MODEL\",\"prompt\":\"<PROMPT>\",\"n\":1,\"size\":\"auto\",\"quality\":\"high\",\"output_format\":\"png\"}" \
  -o tmp/imagegen/response.raw

# Parse SSE and save PNG
python3 - <<'PY'
import json, base64
from pathlib import Path

raw = Path('tmp/imagegen/response.raw').read_text(errors='replace')
final = None
for block in raw.strip().split('\n\n'):
    lines = block.splitlines()
    ev   = next((l[6:].strip() for l in lines if l.startswith('event:')), '')
    data = ''.join(l[5:].strip() for l in lines if l.startswith('data:'))
    if ev == 'done' and data:
        final = json.loads(data)

if not final:
    raise SystemExit('[imagegen] No done event in SSE response.')

out = Path('output/imagegen/result.png')
out.parent.mkdir(parents=True, exist_ok=True)
out.write_bytes(base64.b64decode(final['data'][0]['b64_json']))
print(f'[imagegen] Saved: {out} ({out.stat().st_size:,} bytes)')
PY

STOP conditions (strict)

• Do NOT hardcode any API key or endpoint URL in code or skill files
• Do NOT use direct OpenAI API (api.openai.com) unless user explicitly sets it in auth.json
• Do NOT use sharp, canvas, jimp, PIL, or any programmatic library as image substitute
• Do NOT fake image generation with placeholder or solid colour
• If built-in tool unavailable AND auth.json missing → inform user to create auth.json, then STOP
• If both option 1 and 2 fail → report clearly and STOP

Workflow

0. Environment check (strict order):

   • a. Built-in image_generation_call tool available? → use it, proceed to step 1
   • b. ~/.config/imagegen/auth.json exists and valid? → use curl/SDK path, proceed
   • c. Neither available → STOP. Report: "Built-in tool unavailable and auth.json not found. See SETUP.md."
   • d. NEVER ask for or use a hardcoded API key

1. Decide intent: generate vs edit vs batch (see decision tree above)

2. Collect inputs: prompt(s), exact text (verbatim), constraints, and any input image(s)/mask(s)

3. If batch: write temp JSONL under tmp/imagegen/, run once, delete JSONL after

4. Augment prompt into a short labeled spec (structure + constraints)

5. Run image generation via priority order above

6. Inspect outputs and validate: subject, style, composition, text accuracy, constraints

7. Iterate with single targeted change if needed

8. Save final outputs to output/imagegen/ and note the final prompt used

Defaults & rules

• Default model from auth.json → field model. If missing, default to gpt-image-1
• Assume the user wants a new image unless they explicitly ask for an edit
• Prefer built-in tool over curl path always
• Prefer the bundled CLI (scripts/image_gen.py) over writing new one-off scripts
• Never modify scripts/image_gen.py
• Use tmp/imagegen/ for intermediates, output/imagegen/ for final assets

Prompt augmentation

Reformat user prompts into a structured spec. Only make implicit details explicit; do not invent new requirements.

Template:

Use case: <taxonomy slug>
Asset type: <where the asset will be used>
Primary request: <user's main prompt>
Scene/background: <environment>
Subject: <main subject>
Style/medium: <photo/illustration/3D/etc>
Composition/framing: <wide/close/top-down; placement>
Lighting/mood: <lighting + mood>
Color palette: <palette notes>
Quality: <low/medium/high/auto>
Text (verbatim): "<exact text>"
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

Use-case taxonomy

Generate: photorealistic-natural, product-mockup, ui-mockup, infographic-diagram, logo-brand, illustration-story, stylized-concept, historical-scene
Edit: text-localization, identity-preserve, precise-object-edit, lighting-weather, background-extraction, style-transfer, compositing, sketch-to-render

Reference map

• references/cli.md — how to run image_gen.py CLI
• references/image-api.md — API parameters reference
• references/prompting.md — prompting principles
• references/sample-prompts.md — copy-paste prompt recipes
• SETUP.md — user setup instructions (auth.json, dependencies)