Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →Edit, restyle, or vary an EXISTING image file using OpenAI gpt-image-2 through the Codex CLI — change one thing and keep the rest, swap a background, recolor to a brand palette, add or fix text, or produce style-matched variants of a reference image. Use whenever the user points at an image file and asks to change, fix, restyle, clean up, or make a version of it.
.claude/skills/sateezg-edit-an-existing-image-gpt-image-2-via-codex-cli/SKILL.md| Test case | Without → With | Effect | Δ tokens | Δ turns |
|---|---|---|---|---|
| case-12 | ✗→✓ | ▲ Improved | -8% | 0% |
| case-14 | ✗→✓ | ▲ Improved | -12% | 0% |
| case-16 | ✗→✓ | ▲ Improved | -12% | 0% |
| case-20 | ✗→✓ | ▲ Improved | -51% | 0% |
| case-17 | ✓→✗ | ▼ Worse | 42% | 0% |
Same wrapper as generation, plus --ref to attach the source image:
bashcodex-imagegen "<what to change>" <output.png> --ref <source.png> [--size WxH]
The wrapper attaches the reference with codex exec -i, tells Codex to preserve everything not mentioned, and prints the absolute path of the new file. The source file is never modified — always write to a new path.
bash# change one thing, keep the rest codex-imagegen "change the sky to a sunset orange, keep the building and people identical" \ ./out/hero-sunset.png --ref ./assets/hero.png # recolor to a brand palette codex-imagegen "recolor to a monochrome palette of #2563EB on white, keep the exact shapes" \ ./out/icon-blue.png --ref ./assets/icon.png # style-matched sibling asset codex-imagegen "a settings gear icon in exactly the style of the reference: same stroke weight, same palette, same corner radius" \ ./out/settings.png --ref ./assets/home.png
Up to four --ref images can be passed — useful when one is the subject and the others are style references. Say in the prompt which is which.
Be surgical. The model preserves what you don't mention, so name the change and then name what must survive it:
For a series of edits, chain them one at a time (each output becomes the next --ref) rather than stacking five changes into one prompt.
the user has seen the result. Note that Codex itself resists overwriting — the wrapper prints the path actually written, which may be a versioned sibling like out-v2.png. Use the printed path, not the one you asked for.
against the request before reporting done. Regenerate with a sharper prompt if the model drifted — at most 2 retries.
#00FF00background (#FF00FF if the subject is green) and strip the key with the helper Codex ships: bash python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \ --input ./keyed.png --out ./final.png --auto-key border --soft-matte \ --transparent-threshold 12 --opaque-threshold 220 --despill Verify transparent corners and no colour fringe afterwards. True native transparency needs Codex's CLI fallback plus an OPENAI_API_KEY — only raise that option for hard subjects (hair, fur, glass, smoke) and let the user decide.
and compression are faster and lossless with ImageMagick or sips — use those directly instead of regenerating.
For multi-image jobs, hand the whole brief to the codex-artist subagent instead.
| Case | Status | Duration (ms) | Turns | Tokens | Tool calls | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Without | With | Δ | Without | With | Δ | Without | With | Δ | Without | With | Δ | ||
case-19 | fail→fail | 24,009 | 17,382 | -28% | 1 | 1 | 0% | 3,579 | 1,251 | -65% | 0 | 0 | — |
case-04 | fail→fail | 17,802 | 19,396 | +9% | 1 | 1 | 0% | 201 | 1,694 | +743% | 0 | 0 | — |
case-05 | fail→fail | 17,363 | 17,527 | +1% | 1 | 1 | 0% | 559 | 1,222 | +119% | 0 | 0 | — |
case-12 | fail→pass | 17,993 | 5,623 | -69% | 1 | 1 | 0% | 1,779 | 1,629 | -8% | 0 | 0 | — |
case-13 | fail→fail | 11,989 | 10,445 | -13% | 1 | 1 | 0% | 353 | 1,072 | +204% | 0 | 0 | — |
case-01 | fail→fail | 27,934 | 16,645 | -40% | 1 | 1 | 0% | 1,492 | 1,201 | -20% | 0 | 0 | — |
case-02 | fail→fail | 10,284 | 16,481 | +60% | 1 | 1 | 0% | 988 | 1,222 | +24% | 0 | 0 | — |
case-03 | fail→fail | 16,064 | 7,974 | -50% | 1 | 1 | 0% | 257 | 1,388 | +440% | 0 | 0 | — |
case-06 | fail→fail | 13,900 | 19,534 | +41% | 1 | 1 | 0% | 1,382 | 1,299 | -6% | 0 | 0 | — |
case-07 | fail→fail | 11,132 | 15,093 | +36% | 1 | 1 | 0% | 202 | 1,261 | +524% | 0 | 0 | — |
case-08 | fail→fail | 29,142 | 11,973 | -59% | 1 | 1 | 0% | 3,757 | 1,134 | -70% | 0 | 0 | — |
case-09 | fail→fail | 14,224 | 8,430 | -41% | 1 | 1 | 0% | 1,332 | 1,404 | +5% | 0 | 0 | — |
case-10 | fail→fail | 17,772 | 15,672 | -12% | 1 | 1 | 0% | 288 | 1,637 | +468% | 0 | 0 | — |
case-11 | pass→pass | 11,521 | 7,792 | -32% | 1 | 1 | 0% | 1,008 | 1,316 | +31% | 0 | 0 | — |
case-14 | fail→pass | 10,312 | 3,719 | -64% | 1 | 1 | 0% | 1,627 | 1,437 | -12% | 0 | 0 | — |
case-15 | fail→fail | 10,700 | 13,225 | +24% | 1 | 1 | 0% | 210 | 1,197 | +470% | 0 | 0 | — |
case-16 | fail→pass | 15,436 | 9,658 | -37% | 1 | 1 | 0% | 1,859 | 1,635 | -12% | 0 | 0 | — |
case-17 | pass→fail | 9,686 | 11,391 | +18% | 1 | 1 | 0% | 818 | 1,162 | +42% | 0 | 0 | — |
case-18 | fail→fail | 2,708 | 11,384 | +320% | 1 | 1 | 0% | 300 | 1,140 | +280% | 0 | 0 | — |
case-20 | fail→pass | 17,779 | 2,605 | -85% | 1 | 1 | 0% | 2,364 | 1,163 | -51% | 0 | 0 | — |
case-21 | pass→fail | 7,669 | 1,981 | -74% | 1 | 1 | 0% | 1,258 | 1,158 | -8% | 0 | 0 | — |
case-22 | pass→pass | 21,593 | 14,595 | -32% | 1 | 1 | 0% | 1,736 | 1,465 | -16% | 0 | 0 | — |
case-23 | pass→pass | 19,361 | 7,203 | -63% | 1 | 1 | 0% | 1,990 | 2,065 | +4% | 0 | 0 | — |
DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 23 cases were attempted, and 8 counted toward the lift figure. The other 15 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of +9 percentage points is the difference between those two pass rates over the 8 comparable cases. 2 cases got worse with the skill loaded, and they are included in that figure.
Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.
Other measured skills in the registry, with their headline benchmark lift.