ai_image_editing_workflows v1.0.0

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.