imager
Skill0 starsChanged 52 days agoMITView on GitHub
Generate and edit images using OpenAI's GPT Image API (gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2). Interactive skill that guides users through image creation with style presets, a cost-aware draft/final workflow, transparent backgrounds, masked inpainting, carousels, batches and photo editing. This skill should be used when the user requests image generation via OpenAI/GPT Image, wants to create social media carousels, edit photos into artistic styles, needs a raster asset on a transparent background, or needs images with readable text (infographics, posters, slides). Not for vector marks, icons or exact diagrams that should be drawn as SVG or code.
- Reads credentials
2 other projects use a version of this.
Adopted by
Most recently taken up by
- yuntao1122/ai-media-skillstheir own version, first seen Nov 1, 2026
- dbhq-uk/gpt-image-2-skillword for word, first seen Sep 25, 2026
Other versions2 projects use a version of this.
Word for word · 1
- dbhq-uk/gpt-image-2-skill★ 0100% same
Edited · 0
None found.
Wrote their own version · 1
- yuntao1122/ai-media-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repositoryOne other file it gives its agents.
- AGENTS.mdAGENTS.md
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 63
Ask the user one question at a time, and wait for each answer.
- Very specific: line 91
Run --dry-run and read the assembled prompt.
- Distinctive: line 97
If approved, generate the final, and choose its tier this way:
- Distinctive: line 110
Read paths and cost from it.
- Distinctive: line 128
Story arc: Ask for the key message, propose a slide-by-slide plan, get it approved.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
imager - guided image generation
Generate and edit images through OpenAI's GPT Image API: draft cheaply, show the user, then pay for the final.
PY=python3
GEN=${CLAUDE_SKILL_DIR}/scripts/imager.pyPython 3.9 or later, standard library only: nothing to install. It needs OPENAI_API_KEY in the
environment. ImageMagick is optional (platform fitting, contact sheets).
When not to use
- Vector marks, logos and icons that must stay sharp at every size. Draw them as SVG.
- Exact diagrams: flowcharts, architecture, charts. Use Mermaid, SVG or a plotting library. The model draws plausible diagrams, not correct ones.
- An asset the repository already generates from code. Change the generator.
- Under Codex, the built-in
image_gentool needs no API key, but has no file paths, masks, set check or cost record. Use this skill when those matter.
Step 0: Is this going into a set that already exists?
Do this before anything else, every time.
A folder of images is a set, with a model and tier somebody already chose. Adding at another tier gives images that do not match, at a price nobody needed to pay. Another model changes the look.
$PY $GEN set-check <dir-or-file> # what did this set use last time?The CLI also does this itself: when the output lands in a folder the history knows, it adopts
that model and tier and says so. --model or --quality overrides it, with a warning.
Inside git a set is the repository plus the folder's path, so another worktree is the same set.
More than a few images? Use batch (below). Do not write your own runner. A script that
calls the API itself gets no set check, no daily total and no record of what it spent.
Models and quality
| Model | When |
gpt-image-2.5-flare (default) | Everything, unless a reason says otherwise. Faster and cheaper per tier than gpt-image-2. |
gpt-image-2.5-sunburst | Fine detail, dense text, precision and multi-turn edits. Slower. |
gpt-image-2 | A set made on it, or a Batch API run (the 50% discount does not cover 2.5). |
Aliases: flare, sunburst, 2. Do not use retiring models: gpt-image-1 leaves the API on
23 October 2026; gpt-image-1.5, gpt-image-1-mini and chatgpt-image-latest on
1 December 2026.
Quality: low, medium, high, plus xhigh and max on the 2.5 models. The default is
low, because the flow is draft first. There is no seed and no thinking control.
Interactive flow
Ask the user one question at a time, and wait for each answer. Skip a question the request already answers.
Step 1: What are we making?
A single image, a photo edit, a carousel (5-10 slides), variants, or a quick generate with no questions. If the user already gave a clear prompt, go to Step 3.
Step 2: Style
Offer the presets ($PY $GEN list-presets), grouped:
- Visual, no text: editorial, blueprint, ink, risograph, wireframe, constellation, brutalist, grain, nordic, bauhaus
- Text-heavy: infographic, slide, diagram, poster, menu, manga
- Community: trading-card, pixar, app-mockup, isometric, action-figure, cinematic, panorama
- Social: flat-social, linkedin-hero, social-bold, social-split
- Custom: the user describes their own
Step 3: Where will it be used?
Pass --platform: youtube, youtube-short, slides, blog, x, square, story or
pinterest (list-platforms shows the sizes). The image is generated at that shape and scaled
down, not cropped. Or pass --size WIDTHxHEIGHT; the CLI names the nearest legal size if needed.
Step 4: Draft first, then final
Always generate a draft first unless the user says "skip draft".
- Run
--dry-runand read the assembled prompt. A preset brings its own background, palette and often "no text". If the subject asks for something the preset forbids, such as a headline on a "no text" preset, fix the prompt or change the preset before spending. - Generate with
--draft(about $0.006) and the--platformor--sizethe final will use, so the draft is composed as the final will be. - Show it (Step 5). Ask: final, adjust the prompt, another style, or regenerate?
- If approved, generate the final, and choose its tier this way:
- The set has a tier (Step 0 found one): pass no
--quality. The CLI adopts the set's tier and prints the price. Passing--qualityoverrides the set, the failure Step 0 stops. - The set is new: agree the tier with the user first, then pass it. Low is right unless the image is shown large. Say what each tier costs.
- The set has a tier (Step 0 found one): pass no
Composition moves between draft and final, because there is no seed. To keep it, describe
it in the prompt (framing, camera, placement), or pass the approved draft as --reference.
Step 5: Show the result
- Show the image with the Read tool.
- A run's last line is JSON:
paths,contact_sheet,cost,cost_source,preview_urls. Read paths and cost from it. openandxdg-opendo nothing on a headless machine. Post eachpreview_urlsURL as a clickable link. The CLI fills them by runningpreview_commanditself; never run a preview helper by hand.- Report the cost.
cost_source: billedis what the API billed. - Offer: variants, edit further, use as a reference, or done.
Timeouts
A generation can take two minutes or more at high tiers, large sizes or with several
references, and many agent shells stop a command at 120 seconds. Run finals, xhigh, max,
--n above 1 and every batch with a longer timeout (10 minutes) or in the background.
A killed run stays in the history as pending and counts at its estimate, because it may have
been billed. Check $PY $GEN history -n 5 before running it again.
Carousels
- Story arc. Ask for the key message, propose a slide-by-slide plan, get it approved.
- Consistency comes from the prompt and references. One preset, model, tier and size.
Repeat the palette, type and grid wording in every prompt. Pass the approved slide 1 as
--reference. Ask for pagination dots. For a recurring character, repeat age, appearance, hairstyle, features and clothing every time. - Drafts of every slide, then finals of the approved ones as a
batch.
Photo edits
A clipboard image must be saved to a file first (osascript on macOS, xclip -selection
clipboard -t image/png -o > /tmp/clip.png on Linux). Then draft, show and final, as in Step 4.
--edit <path>edits the photo. The CLI sendssize=autounless--sizeor--platformis set, because the edit endpoint otherwise returns a square.--mask <mask.png>: a PNG the size of the source whose transparent areas mark what to replace. It is guidance, so also say what changes and what must not.--reference(up to 16) carries a subject or a look into a new scene.
Assets and formats
Transparent: --background transparent, png or webp. Say it in the prompt too ("isolated
on a transparent background, no shadow, no halo"): the flag sets alpha, the words stop the model
painting a background. With jpeg the CLI switches to png.
Formats: --output-format png (default), jpeg or webp, with --output-compression
0-100 on the last two. Use webp for the web.
Files: a run never replaces a file. If out.png exists it writes out-2.png and says so.
--overwrite replaces on purpose. Report the path the CLI printed. --sidecar also writes
<image>.json.
Batch runs
For more than a handful of images, write one JSON object per line and run the file:
$PY $GEN batch runs.jsonl --dry-run # the plan for each folder, and one total
$PY $GEN batch runs.jsonl # one confirmation for the whole file{"prompt": "a lighthouse at dusk", "output": "notes/01.png", "preset": "ink"}
{"prompt": "a harbour crane", "output": "notes/02.png", "platform": "story"}prompt and output are required. A row may also carry preset, platform, size, edit,
reference, mask, background and output_format; any other key is refused. --model and
--quality apply to the whole file. One image per row, at the normal price (not the Batch API).
- The file is checked whole before anything is priced, with every problem listed.
- One set check per folder, one total, one confirmation.
-ydoes not skipdaily_cap. - Outputs that exist are skipped, so running the file again resumes it.
--concurrency N(default 4, at most 16). A failed row does not stop the others; five in a row stop the run.
Cost
Say what a run costs before running it. The CLI prices prompt text, input images and output image, each at its token rate. Per image at 1024x1024 on flare or sunburst:
| Quality | Per image | 10 slides | 2,000 images |
| low (default) | $0.006 | $0.06 | $12 |
| high | $0.053 | $0.53 | $105 |
| xhigh | $0.100 | $1.00 | $200 |
gpt-image-2 high is $0.211. Each input image adds about $0.013 per output. Non-square is
cheaper (1536x864 is about 0.63x); size=auto is priced at 1.2x square. The estimate names its
basis: measured, calibrated, published or upper bound (deliberately high). Every run
records what was actually billed.
Guards. A run of $0.50 or more asks first. Past $5 in a day, every run warns. daily_cap: 20
in ~/.dbhq/imager/config.yaml stops any run that would pass it, -y or not, and exits 4.
They only see spend that went through this CLI.
Prompt tips
- Name the deliverable first: "A 3:2 conference poster for...", not "a poster of...".
- Subject first, then detail, lighting and constraints.
- For text in the image, quote the exact string and give it a hierarchy. Never "add some text".
- On an edit, say what must not change. With
--reference, say what each one controls. - End with style tags such as
editorial-magazineto pull a set together.
CLI reference
$PY $GEN --draft --preset editorial --platform square "subject" out.png
$PY $GEN --model sunburst --quality xhigh "dense infographic" out.png
$PY $GEN --n 4 --preset ink "mountain" out.png # variants and a contact sheet
$PY $GEN --estimate --n 10 --quality high "test" # price only
$PY $GEN -y "prompt" out.png # skip the confirmation
$PY $GEN --project launch "prompt" out.png # tag it for history --project
$PY $GEN again # the last run, same inputs
$PY $GEN history -n 10--project with no output path files the image under ~/imager/outputs/<project>/. With no
path and no project, a run writes imager-<timestamp>.png here.
Exit codes: 0 done, 1 an error (a missing input image is caught before pricing) or a failed
batch row, 2 a bad or removed flag, 3 cancelled at the confirmation, 4 over daily_cap. Treat
only 0 as an image made.
Refusals
A moderation block names its stage and categories. The CLI does not retry: change the prompt or
the inputs. For a legitimate generation, --moderation low is less strict. Edits have none.
Files
scripts/imager.py (the CLI), presets.json, platforms.json, references/api_reference.md.
In ~/.dbhq/imager/ (or GPT_IMAGE_HOME): config.yaml (flat key: value defaults),
history.jsonl (every run and its billed cost, written before the request and completed after),
last.json (for again) and contact-sheets/ (the newest 50, never in the set's folder).
preview_command in config.yaml (unset by default), for example
"/path/to/preview.sh {path} {name}", runs once per saved file with no shell. {name} is unique to the run; its last output line is the URL.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

