adobe-retouch-portraits

Files (4)

• SKILL.md
• openai.yaml · agents/
• icon-large.svg · assets/
• icon-small.svg · assets/

SKILL.md (first lines)

# Adobe Retouch Portraits

A walk-away bulk retouching pipeline for photographers. The user selects their
images, optionally adds tweaks, and the agent runs the full batch using Adobe
for creativity tools.

> **Surface note:** The default flow uses Adobe's MCP App widgets — the `asset_add_file` picker (Step 1) and the `asset_preview_file` preview (Steps 2c and 8). Follow it as written. Only if a widget tool is **not available on this surface** (e.g. Codex) use the *No-widget fallback* attached to that step. Present `AskUserQuestion` prompts as plain-text labeled options wherever no question widget exists.

---

## Generative AI Policy

**This retouching pipeline is fully non-generative by default.** The core workflow — auto-straighten, auto-tone, adjustments, presets, blur, and crop — uses no generative AI, and that non-generative pipeline is the *only* behavior on surfaces that do not permit generative AI (**including Claude**).

**Generative editing runs only where the surface permits it.** A surface permits generative AI only when it exposes a generative tool such as `image_fill_area` (e.g. Codex). Where no such tool is available (e.g. Claude), perform **no** generative edits of any kind — do not call, attempt, offer, or mention them; run the non-generative pipeline only.

**Where generative AI is permitted, it is limited to backgrounds and kept minimal.** Only then may `image_fill_area` correct dust spots, sensor artifacts, or scratches on non-human areas (walls, floors, sky, props), and only when the fix is invisible at normal viewing size — remove a dust spot, not repaint a wall. **Never** apply generative tools to faces, skin, hair, bodies, or clothing on any surface. Do not alter the scene, remove objects, change the environment, or extend the frame.

If the user asks you to generatively modify a person (e.g. "change her hair color", "make him look younger"), clarify that this skill does not perform generative edits on people — and, on a surface with no generative capability at all, that generative editing isn't available here — then suggest a dedicated generative workflow instead.

---

## Tool Reference (Adobe for creativity connector)

| Step                  | Tool                                                        | Notes                                              |
| --------------------- | ----------------------------------------------------------- | -------------------------------------------------- |
| Ingest                | `asset_add_file` + `read_widget_context`                    | Interactive file picker; resolve URIs via `read_widget_context` |
| Ingest *(no-widget fallback)* | `asset_initialize_file_upload` + `asset_finalize_file_upload` | Only when `asset_add_file` is unavailable — stage a local file to CC |
| Discover presets      | `image_list_presets`                                        | Once at startup; builds the smart preset plan      |
| Straighten            | `image_auto_straighten`                                     | Per image                                          |
| Auto-Tone             | `image_apply_auto_tone` (cameraRawFilter)                   | Per image                                          |
| Tone adjustments      | `image_apply_adjustments`                                   | Batch — all tweaks in one call                     |
| Subject/body detect   | `image_select_subject`                                      | Face + body parts + clothes detection              |
| Adaptive Enhancements | `image_apply_preset`                                        | Per image, opt-in (see Step 5)                     |
| Background blur       | `image_apply_lens_blur`                                     | Per image, preferred — depth-aware bokeh           |
| Heavy/stylized blur   | `image_apply_gaussian_blur`                                 | Per image, only if user explicitly requests heavy  |
| Background cleanup    | `image_fill_area` (optional; generative)                    | Only where the surface permits generative AI (tool available, e.g. Codex) — backgrounds only, never people; **not used on Claude** |
| Crop                  | `image_crop_and_resize`                                     | Per image                                          |
| Sample preview        | `asset_preview_file`                                        | Before/after on image[0] only *(no-widget fallback: present the URLs directly)* |
| Final preview         | `asset_preview_file`                                        | All final URLs directly, no resize step *(no-widget fallback: present the URLs directly)* |
| Firefly Board         | `create_firefly_board`                                      | Source presigned URLs from ingestion               |

---

## Step 0 - prereq: Initialize Adobe Tools
Call `adobe_mandatory_init` first. This returns file handling rules and tool routing guidance required for the rest of the workflow.

```json
{ "skill_name": "adobe-retouch-portraits", "skill_version": "3.1.0" }
```

This also tells you which widgets this surface supports and whether egress is enabled. If `asset_add_file` and `asset_preview_file` are available, follow the default flow (Steps 1, 2c, and 8 as written). If one is not available (e.g. Codex), use that step's *No-widget fallback*. If a tool result carries an `importantNote`, or the connector injects "Asset Storage & Display" guidance for the current turn, follow it — it overrides the presentation defaults here.

---

## Step 0b: Discover Available Presets

Call `image_list_presets` immediately after init — before ingestion or user questions. This gives you the full pool of presets available to this user's plan, so you can build a smart, plan-aware preset selection for Step 5.

```
Tool: image_list_presets
Params: {}
```

From the returned list, build a **Preset Plan** by categorizing presets into four buckets. Use the naming signals below to classify each preset — these are heuristics, not hardcoded names, so apply judgment:

### Preset Plan Buckets

**1. Adaptive Person Presets** — target the subject's body, skin, clothing, or teeth
Naming signals: `Adaptive`, `Subject`, `Portrait`, `Person`, `Skin`, `Body`, `Clothes`, `Outfit`, `Pop`, `Warm Pop`, `Enhance`, `Teeth`, `Whiten`, `Smile`, `Brighten`
Goal: pick 1–3 presets that best boost the human subject. Prefer presets that target skin/body or offer subject-level contrast/warmth lift. Avoid presets that affect only sky or background. Any preset with teeth/smile/whiten signals should be included here so it is available when Whiten Teeth is selected in Step 2.

**2. Global Mood / Tone Preset** — overall tonal character of the image
Naming signals: `Mood`, `Tone`, `Warm`, `Cool`, `Golden`, `Cinematic`, `Film`, `Natural`, `Airy`, `Fade`, `Matte`, `Classic`
Goal: pick exactly **1** preset. Choose the most portrait-friendly neutral or warm look — avoid heavy stylisation (neon, surreal) unless the user requested an editorial style.

**3. Global Toon / Look Preset** — stylistic look treatment
Naming signals: `Toon`, `Style`, `Look`, `Preset`, `Vintage`, `Retro`, `B&W`, `Mono`, `Haze`, `Glow`, `Edit`, `Creative`
Goal: pick exactly **1** preset. Choose something complementary to the mood preset — not a duplicate effect. If the mood preset is already cinematic/warm, choose a lighter stylistic touch.

**4. Background Blur Preset** — softens background to flatter the subject
Naming signals: `Blur Background`, `BG Blur`, `Bokeh`, `Depth`, `Focus`, `Defocus`
Goal: pick exactly **1** blur-background preset. This replaces `image_apply_gaussian_blur` when the user opts into it.

**Fallback strategy:**
- If no preset matches a bucket, leave that bucket empty rather than forcing a poor fit.
- If the plan returns no presets at all (403 or empty list), skip Step 5 entirely and note it in the summary: "Adaptive enhancements not available — no presets found on this plan." **This is a non-blocking error — all other pipeline steps (tone adjustments, preview gate, full batch) continue exactly as normal. Only Step 5 is skipped.**
- Buckets 2 and 3 are global mood/style layers — skip them if you cannot find a clearly portrait-appropriate match. It's better to skip than to apply an ill-fitting preset.

Store the chosen presets as your **Preset Plan** before Step 2. The user's mood/style selection (collected in Step 2a) may refine which preset is chosen within each bucket — see Step 2a for guidance. Show the final plan to the user in the confirmation message (Step 2).

---

## Step 1: Image Ingestion

Call `asset_add_file` with no parameters. This renders an interactive UI where
the user can:
- **Browse CC storage** and select a folder or individual files
- **Upload from device** (local files)
- **In Cowork**: select a local folder path directly
```
Tool: asset_add_file
Params: {}
```

**Important:** `asset_add_file` returns `imageURIs: []` — this is expected and
NOT an error. The actual URIs arrive in the **next user message** after the
user selects files. Wait for that follow-up before continuing.

After receiving the URIs, call `read_widget_context` with `asset_add_file` to resolve them to correct presigned S3 URLs. Use those resolved URLs for all subsequent tool calls — `dcx-stage.adobe.io` URIs are network-blocked and must be resolved via `read_widget_context` first.

Collect the resulting presigned URLs as `sourceURIs[]` and continue to Step 2a.

> **No-widget fallback** *(only if `asset_add_file` is unavailable on this surface, e.g. Codex)* — don't ask the user to pick; get the source URIs from where the files are. `image_*` tools only accept Creative Cloud storage URIs — never raw local paths.
>
> | Source | Action |
> |--------|--------|
> | File(s) at a local path (e.g. `/mnt/user-data/uploads/…`) | **Check egress status from `adobe_mandatory_init` first.** If egress is enabled: stage each file programmatically — get file size and MIME type, call `asset_initialize_file_upload({ path: "<filename>", media_type: "<mime>" })`, PUT the bytes to the returned upload URL, then `asset_finalize_file_upload({ filename: "<filename>", transfer_document: <from initialize response> })`; use each returned presigned CC URL for downstream calls. If egress is disabled or programmatic upload fails, this fallback cannot proceed on this surface — surface the limitation to the user. |
> | File(s) already in Creative Cloud | Reference them directly by their CC presigned URL. |

From xixu-me/scps, Apache-2.0.

More from xixu-me/scps