Photo → Watercolor

Overview

Convert any photograph into a hand-painted watercolor illustration while preserving every detail of the original. Using image-to-image generation with input_fidelity: high, the transformation swaps the entire visual language (pixel-perfect realism → pigment on paper) while keeping all semantic content identical. Handles single subjects and multi-subject scenes through a three-tier complexity system, gates output on both accuracy and painterly quality, and improves itself across uses by logging each run to evolution/.

When to use this skill

Use when a user provides a photo and asks for a watercolor / hand-painted version, regardless of subject or subject count. Common triggers:

• "把这张照片变成水彩画" / "做个水彩版本" / "watercolor version"
• "把它水彩化 / 颜料感处理一下"
• "想要这种手绘水彩的感觉" (when paired with a photo)
• "保留所有细节但换成水彩"

Do not use if:
- The user wants a different style (oil, anime, pencil, pixel art) — different prompt needed.
- There is no input photo — this skill is image-to-image only.
- The user wants a photo with a light watercolor filter rather than a full re-render.

How it works

The skill is a prompt-engineering workflow, not a script. Generation runs through the ImageGen tool in image-to-image mode (passing image1). The skill provides:

1. A three-tier complexity system so multi-subject scenes get the structural scaffolding they need.
2. A library of verified prompt patterns (evolution/LEARNED-PATTERNS.md) that grows with each use.
3. A fidelity rule (input_fidelity: high) — the reason original detail survives.
4. Two quality gates — accuracy (fidelity) and painterly quality (aesthetic rubric).
5. An evolution protocol that writes every run back into the skill.

Complexity triage — do this first

Count the identifiable subjects in the photo and pick the tier. This determines the prompt skeleton and what "good" means.

Tier 2 and 3 require reading references/multi-subject.md before writing the prompt. Single-subject prompts fail on groups in predictable ways — count drift, feature bleed, flat hierarchy, lost occlusion. That file has the counters.

Quick Start Workflow

Step 1 — Read the input photo

Use the Read tool. Identify:

• Tier: how many identifiable subjects? (see triage above)
• Subject class: pet / person / landscape / food / still life / architecture / group / dense scene
• Key details to preserve: faces, distinguishing marks, signature colors, accessories, text
• Composition: framing, angle, arrangement, foreground/background relationship
• Lighting direction: which side is lit. This must not flip.
• If multi-subject: positional arrangement, physical contact, gaze convergence, occlusion

Do not skip the detail pass. If you cannot list at least 5 distinguishing anchors, look at the photo again. Anchor quality drives output quality more than any other factor.

Step 2 — Compose the prompt

Build from evolution/LEARNED-PATTERNS.md rather than writing from scratch — it holds verified fragments (P1–P13) and ready-made recipes (R1–R4). Combine with the tier skeleton and the subject variant.

Minimum composition for any prompt:
- P3 fidelity opener (protects before style words appear)
- P4 anchor enumeration (5+ specific features)
- P5 lighting lock
- P1 closing re-anchor (last sentence, after all style language)
- P2 weighted fidelity tag — 1.4 for faces, 1.3 for pets/objects

Step 3 — Call ImageGen

{
  "prompt": "<composed prompt>",
  "image1": "<absolute path to the input photo>",
  "input_fidelity": "high",
  "quality": "high",
  "style": "natural",
  "output_dir": "<absolute path to a folder you created>"
}

Size by aspect ratio — wrong ratio crops the composition:
- Horizontal (3:2, 4:3, 16:9) → 1536x1024
- Square → 1024x1024
- Vertical (2:3, 9:16) → 1024x1536

Always input_fidelity: high — this is why detail survives. Never omit.

Step 4 — Gate 1: fidelity

Open the output with Read. Check against:

Multi-subject adds (from references/multi-subject.md): exact count match · no feature bleed · clear focal hierarchy · relationships preserved · unified light · occlusion intact · reads as one space, not a collage.

Count drift and feature bleed are non-negotiable — regenerate, and add the missing structural language first.

Step 5 — Gate 2: aesthetic quality

Accuracy alone is not enough. A faithful but artistically dead image must not ship. Score the output against references/aesthetic-rubric.md:

Each 1–5, total /25:

• 20–25 → deliver
• 15–19 → note the weakest dimension, regenerate once with its matching prompt handle
• <15 → do not deliver. Diagnose against the "eight tells of cheap watercolor" in the rubric, fix, regenerate.

Also check evolution/FAILURES.md — if the symptom matches a recorded failure, apply that fix instead of re-rolling blindly.

Maximum 3 regeneration attempts. If still failing, show the best of 3 and ask the user how they want to proceed.

Step 6 — Remove the AI watermark

ImageGen output carries a faint watermark bottom-right. Crop before delivering:

from PIL import Image
img = Image.open("<output.png>")
w, h = img.size
img.crop((0, 0, w, int(h * 0.93))).save("<output-clean.png>")

Bottom 7% is enough. Cleanup step, never part of the prompt.

Step 7 — Deliver

• Save the final PNG to the user's requested location (or the workspace's generated-images/).
• Call present_files to show it.
• Briefly state: what was preserved + the watercolor language applied + aesthetic score.

Step 8 — Evolution Protocol (mandatory, never skip)

The skill only improves if each run is written down. After every generation, append an entry to evolution/CHANGELOG.md using the format documented there:

## YYYY-MM-DD | <scene type> | tier <n> | outcome: <success|partial|failure> | attempts: <n>

**Scene**: ...
**Subject handling**: ...
**Prompt DNA used**: ...
**Result**: ...
**Delta**: <one concrete thing to do differently next time>
**Promote**: <yes/no>

Then:
- Delta → FAILURES.md if a fixable failure mode appeared (new entry, or increment an existing one).
- Promote: yes → LEARNED-PATTERNS.md if a prompt fragment measurably worked. Add it with a verification count and confidence rating.
- Every ~8 entries: run a distillation pass — review the changelog, promote recurring wins into LEARNED-PATTERNS.md, recurring losses into FAILURES.md, and log the pass in the distillation table at the bottom of CHANGELOG.md.

Before generating, read evolution/LEARNED-PATTERNS.md and evolution/FAILURES.md. Respecting accumulated experience is the difference between a fresh skill and a seasoned one.

> Persistence warning: evolution/ lives inside the skill directory. Reinstalling or updating the skill overwrites it. Before any reinstall, copy evolution/ somewhere safe and restore it after. Losing it resets the skill to novice.

Special case: portraits

Faces are far more brittle than pets or landscapes — the model preserves composition while subtly shifting identity (eye shape, nose bridge, lip fullness), which reads as "not her anymore". Before generating a portrait, read "Portrait / Likeness-Sensitive Subjects" in references/fidelity-rules.md. Covers mark anchoring, lighting locks, and retry protocol.

Resources

references/

• prompt-variants.md — Tier 1 templates by subject class (pet, person, landscape, food, architecture, mixed)
• multi-subject.md — Tier 2 / Tier 3: group photos, couples, multiple objects, dense scenes. The four counters (count lock, positional coding, focal hierarchy, occlusion).
• style-vocabulary.md — watercolor term glossary with intensity guidance
• fidelity-rules.md — input_fidelity semantics, size/aspect mapping, portrait special handling
• aesthetic-rubric.md — the beauty gate: five qualities of good watercolor, eight tells of cheap watercolor, scoring thresholds, advanced art-direction handles

evolution/ — the skill's memory

• CHANGELOG.md — append-only log of every generation (raw experience)
• LEARNED-PATTERNS.md — distilled, verified prompt DNA (P1–P13) + recipes (R1–R4)
• FAILURES.md — failure modes with fixes; check before regenerating