---
name: "ai_image_editing_workflows"
description: "Plan, execute, and verify AI image edits: inpainting masks, text-instruction edits, iterative edit loops with edit-prompt discipline, and before/after consistency checks. Triggers when an agent needs to modify an existing image with a generative model, e.g. object removal, relighting, product retouching, background swaps, or text fixes in images."
metadata: { "includeInPrompt": true }
---

# AI Image Editing Workflows

## Purpose

Most image-edit jobs fail on process, not model quality. Agents describe edits vaguely, run one shot, and ship the result without checking what else changed. This skill gives a model-agnostic workflow that treats image editing like surgery: bounded scope, verified masks, disciplined prompts, and measured before/after consistency. It covers both edit paths in use today (mask-based inpainting and text-instruction editing) because the loop discipline is the same either way.

## Workflow

**1. Choose the edit path.**
- Bounded region, pixel-precise target (remove a logo, swap a face, fix one label): mask-based inpainting. Build the mask with `bin/make_mask.py` or an image editor.
- Holistic or language-described change (relight, restyle, "make it night"): text-instruction editing (e.g. FLUX Kontext, OpenAI edits without mask). No mask, so the prompt carries the full boundary.
- If unsure, start maskless for speed, then add a mask once the change region is clear.

**2. Pre-flight.**
- Save the source at full resolution. Record its dimensions and a content hash. This is the ground truth for every later comparison.
- Write down what must NOT change (brand text, faces, logos). If the edit path has a mask, those protected areas stay outside the mask.
- Verify mask polarity on the actual model before real work. Conventions flip between models: for dall-e-2-era APIs transparent (alpha 0) means edit, for gpt-image-1 per OpenAI staff guidance opaque (alpha 255) means edit. Run one trivial test edit on a scratch image and confirm which regions changed. Never assume.

**3. Build the mask.**
- PNG with an alpha channel, exactly the same dimensions as the source image. Image and mask must match or the call is rejected.
- Feather the edge 1 to 2 px for natural blending.
- Include margin: gpt-image-1 treats masks in 16x16 blocks and OpenAI confirms it does not do precise inpainting, so edits bleed past the mask edge. Leave a small margin around anything protected, and expect the boundary to be approximate, not surgical.

**4. Write the edit prompt with discipline.**
- Describe the desired final state of the edited region, not just the action. "Empty wooden table" beats "remove the cup".
- One change per iteration. Compound prompts drift.
- Add an explicit preservation clause: "keep everything outside the masked area exactly unchanged, same lighting, same camera angle".
- For maskless instruction models, also restate the anchor: "same photo, same person, same background, only change X". Multi-turn drift compounds, so re-anchor every turn.
- See `references/edit-prompt-patterns.md` for worked recipes.

**5. Run the edit, then evaluate before/after.**
- Run `bin/consistency_check.py source.png edited.png --mask mask.png` (omit --mask for maskless edits). It reports masked-region change strength and unmasked-region similarity.
- Read the numbers: masked-region SSIM should be LOW (the edit happened), unmasked-region SSIM should be HIGH (nothing else moved). If the unmasked region drifted, the edit is rejected, not shipped.
- Spot-check protected content by eye at 100 percent: brand text, faces, fine detail. Automated scores miss typography corruption.

**6. Iterate or accept.**
- Reject: rewrite the prompt more specifically (narrow the region, sharpen the preservation clause), then edit again from the LATEST accepted output.
- Accept: the edit is done when the change is correct AND the consistency check passes.
- Cap iterations at 3 on one prompt before regenerating from the source image. Past 3 turns, multi-turn drift usually exceeds the edit benefit. Log each attempt: prompt used, what changed, consistency scores.

## Output Contract

Every completed edit job produces:
- `source/`: the original image plus its recorded dimensions and hash.
- `attempts/`: every model output, numbered, each with the exact prompt and mask used.
- `consistency_report.md`: masked-region change score and unmasked-region similarity per attempt, plus the accept/reject verdict and reason.
- The accepted final image.

## Operating Rules

1. Never ship an edit without a consistency check. The model rewriting the background is the common case, not the exception.
2. Never edit from an edit for more than 3 consecutive turns. Return to the source.
3. Mask polarity is a per-model fact, verified by a test edit, never assumed from habit.
4. Cut unverifiable claims from edit prompts. A prompt that says "make it award-winning" gives the model license to redraw everything.
5. Keep all attempts. An edit that looks worse than attempt 1 is recoverable only if attempt 1 still exists.
6. Model-specific facts live in `references/model-notes.md`. Verify them against the source links before quoting limits or behavior to anyone.