Portrait Retouch Skill
Intelligent portrait retouching that analyzes before editing — only fixes what's broken, preserves everything else.
When to Activate
- User wants to retouch or enhance a portrait photo
- User mentions "skin", "lighting", "wrinkles", "blemishes", "clothing fit"
- User asks for "aesthetic analysis" or "portrait improvement"
- User wants style transfer between portrait images
Architecture
Input Portrait ──► Gemini Analysis (12-Dim Scoring) ──► Aesthetic Score Report
│
▼
Enhanced Portrait ◄── Gemini Image Edit ◄── Targeted Prompt (only low dimensions)
Core Principles
- Non-destructive: Never remove/add/relocate background objects unless explicitly requested
- Precision targeting: Only dimensions scoring below threshold get improvement prompts
- Identity preservation: Subject must remain recognizable as the same person
- Professional specificity: Name exact techniques ("fill light on face") not vague goals ("make it better")
The 12 Aesthetic Dimensions
| Dimension |
What It Measures |
Priority |
| Facial Skin Tone |
Skin color naturalness, uniformity, color cast |
1.5x |
| Facial Brightness |
Face illumination, shadow/highlight balance |
1.3x |
| Outfit |
Clothing fit, wrinkle-free, visual coherence |
1.2x |
| Environment |
Background lighting consistency |
1.1x |
| Facial Feature Clarity |
Sharpness of eyes, nose, lips, eyebrows |
1.0x |
| Facial Aesthetic |
Overall facial harmony and proportion |
0.95x |
| Facial Contour Clarity |
Edge sharpness of face outline |
0.9x |
| Overall Aesthetic |
Holistic image quality |
0.85x |
| Looks |
Expression engagement, eye contact |
0.8x |
| Facial Structure |
Bone structure visibility, symmetry |
0.7x |
| General Appearance |
Grooming, tidiness |
0.6x |
| Composition |
Subject placement, headroom |
0.5x |
| Body Shape |
Posture quality, proportion in frame |
0.4x |
Scoring Criteria
Scoring is STRICT — most casual photos score 5-7, only professional-grade gets 8+.
| Score |
Rating |
Action |
| 8-10 |
Excellent |
Minor refinements only |
| 7 |
Good |
Enhancement recommended |
| 5-6 |
Acceptable |
Targeted improvement needed |
| 0-4 |
Poor |
Priority correction required |
Prompt Construction Logic
- Score all 12 dimensions via Gemini vision analysis
- Filter dimensions below threshold (default: 7.0)
- Rank by priority weight (facial > body > environment)
- Map each low dimension to a specific improvement instruction
- Wrap in preservation rules that lock identity, pose, and background
Preservation Rules (Always Enforced)
- Background objects: Never removed, added, or relocated
- Identity: Face and recognizable features preserved exactly
- Pose & body: Same body position, hand gestures, head/body angle
- Clothing & accessories: Unchanged unless explicitly requested
- Expression: Facial expression, eye gaze, smile must remain pixel-identical
- No new dots: NEVER add any new black/dark dots, specks, points, acne, or marks on the face
Intensity Levels
| Level |
Skin |
Face Shape |
Eyes/Lips |
Body Skin |
| Subtle |
Remove obvious blemishes/acne (keep pores/texture) |
NO slimming |
NO eye changes |
Light evening |
| Moderate |
Smooth wrinkles, even tone, remove temporary blemishes/acne (preserve natural skin texture) |
NO slimming |
Reduce eye bags, NO eye changes |
MUST match face |
| Aggressive |
Strongly smooth, clean skin, remove temporary blemishes/acne (still preserve some pore texture) |
NO slimming |
Remove eye bags, NO eye changes |
IDENTICAL to face |
All levels FORBID: Any face reshaping/slimming, over-brightening, expression changes, adding new black dots/moles/acne, making person unrecognizable, altering eyes/pupils/gaze.
Usage Modes
1. Auto-Enhance Mode
Analyzes all 12 dimensions, applies non-destructive enhancements to low-scoring areas.
2. Analysis-Only Mode
Returns aesthetic scores without applying changes. Useful for preview.
3. User-Guided Mode
User instructions integrated alongside auto improvements while respecting preservation rules.
Running the Server
cd /path/to/PortraitRetouch
source .venv/bin/activate # or .venv\Scripts\activate on Windows
python server.py
Server runs at http://127.0.0.1:8000
API Reference
See references/API.md for complete endpoint documentation.
Key Files
| File |
Purpose |
src/agents/aesthetic_analyzer.py |
12-dimension scoring engine |
src/agents/retouch_planner.py |
Prompt construction with constraints |
src/agents/interaction_memory.py |
Multi-turn session memory |
src/processors/face_local_retouch.py |
High-resolution face region processing |
src/prompts/system_prompts.py |
All system prompts and improvement maps |
Example: Low Environment Score
If environment scores 5/10, the constructed prompt will say:
"Improve environmental lighting and color consistency: correct any color cast in the background, balance ambient lighting with facial lighting. Do NOT remove, add, or relocate any background objects."
It will NOT say "clean up background" — vague instructions cause destructive edits.
1---2name: human-aes-expert3description: Analyzes portrait images across 12 aesthetic dimensions using Gemini Vision, then constructs precise non-destructive retouching prompts. Use when retouching portraits, enhancing facial features, improving skin tone, adjusting lighting, or cleaning up clothing wrinkles while preserving identity and background.4license: MIT5---67# Portrait Retouch Skill89Intelligent portrait retouching that **analyzes before editing** — only fixes what's broken, preserves everything else.1011## When to Activate1213- User wants to retouch or enhance a portrait photo14- User mentions "skin", "lighting", "wrinkles", "blemishes", "clothing fit"15- User asks for "aesthetic analysis" or "portrait improvement"16- User wants style transfer between portrait images1718## Architecture1920```21Input Portrait ──► Gemini Analysis (12-Dim Scoring) ──► Aesthetic Score Report22 │23 ▼24Enhanced Portrait ◄── Gemini Image Edit ◄── Targeted Prompt (only low dimensions)25```2627## Core Principles28291. **Non-destructive**: Never remove/add/relocate background objects unless explicitly requested302. **Precision targeting**: Only dimensions scoring below threshold get improvement prompts313. **Identity preservation**: Subject must remain recognizable as the same person324. **Professional specificity**: Name exact techniques ("fill light on face") not vague goals ("make it better")3334## The 12 Aesthetic Dimensions3536| Dimension | What It Measures | Priority |37|-----------|-----------------|----------|38| **Facial Skin Tone** | Skin color naturalness, uniformity, color cast | 1.5x |39| **Facial Brightness** | Face illumination, shadow/highlight balance | 1.3x |40| **Outfit** | Clothing fit, wrinkle-free, visual coherence | 1.2x |41| **Environment** | Background lighting consistency | 1.1x |42| **Facial Feature Clarity** | Sharpness of eyes, nose, lips, eyebrows | 1.0x |43| **Facial Aesthetic** | Overall facial harmony and proportion | 0.95x |44| **Facial Contour Clarity** | Edge sharpness of face outline | 0.9x |45| **Overall Aesthetic** | Holistic image quality | 0.85x |46| **Looks** | Expression engagement, eye contact | 0.8x |47| **Facial Structure** | Bone structure visibility, symmetry | 0.7x |48| **General Appearance** | Grooming, tidiness | 0.6x |49| **Composition** | Subject placement, headroom | 0.5x |50| **Body Shape** | Posture quality, proportion in frame | 0.4x |5152## Scoring Criteria5354Scoring is **STRICT** — most casual photos score 5-7, only professional-grade gets 8+.5556| Score | Rating | Action |57|-------|--------|--------|58| 8-10 | Excellent | Minor refinements only |59| 7 | Good | Enhancement recommended |60| 5-6 | Acceptable | Targeted improvement needed |61| 0-4 | Poor | Priority correction required |6263## Prompt Construction Logic64651. **Score** all 12 dimensions via Gemini vision analysis662. **Filter** dimensions below threshold (default: 7.0)673. **Rank** by priority weight (facial > body > environment)684. **Map** each low dimension to a specific improvement instruction695. **Wrap** in preservation rules that lock identity, pose, and background7071### Preservation Rules (Always Enforced)7273- **Background objects**: Never removed, added, or relocated74- **Identity**: Face and recognizable features preserved exactly75- **Pose & body**: Same body position, hand gestures, head/body angle76- **Clothing & accessories**: Unchanged unless explicitly requested77- **Expression**: Facial expression, eye gaze, smile must remain pixel-identical78- **No new dots**: NEVER add any new black/dark dots, specks, points, acne, or marks on the face7980## Intensity Levels8182| Level | Skin | Face Shape | Eyes/Lips | Body Skin |83|-------|------|------------|-----------|-----------|84| **Subtle** | Remove obvious blemishes/acne (keep pores/texture) | NO slimming | NO eye changes | Light evening |85| **Moderate** | Smooth wrinkles, even tone, remove temporary blemishes/acne (preserve natural skin texture) | NO slimming | Reduce eye bags, NO eye changes | MUST match face |86| **Aggressive** | Strongly smooth, clean skin, remove temporary blemishes/acne (still preserve some pore texture) | NO slimming | Remove eye bags, NO eye changes | IDENTICAL to face |8788**All levels FORBID**: Any face reshaping/slimming, over-brightening, expression changes, adding new black dots/moles/acne, making person unrecognizable, altering eyes/pupils/gaze.8990## Usage Modes9192### 1. Auto-Enhance Mode93Analyzes all 12 dimensions, applies non-destructive enhancements to low-scoring areas.9495### 2. Analysis-Only Mode96Returns aesthetic scores without applying changes. Useful for preview.9798### 3. User-Guided Mode99User instructions integrated alongside auto improvements while respecting preservation rules.100101## Running the Server102103```bash104cd /path/to/PortraitRetouch105source .venv/bin/activate # or .venv\Scripts\activate on Windows106python server.py107```108109Server runs at `http://127.0.0.1:8000`110111## API Reference112113See [references/API.md](references/API.md) for complete endpoint documentation.114115## Key Files116117| File | Purpose |118|------|---------|119| `src/agents/aesthetic_analyzer.py` | 12-dimension scoring engine |120| `src/agents/retouch_planner.py` | Prompt construction with constraints |121| `src/agents/interaction_memory.py` | Multi-turn session memory |122| `src/processors/face_local_retouch.py` | High-resolution face region processing |123| `src/prompts/system_prompts.py` | All system prompts and improvement maps |124125## Example: Low Environment Score126127If environment scores 5/10, the constructed prompt will say:128129> "Improve environmental lighting and color consistency: correct any color cast in the background, balance ambient lighting with facial lighting. Do NOT remove, add, or relocate any background objects."130131It will **NOT** say "clean up background" — vague instructions cause destructive edits.
WWIIITT