# Human Aes Expert

> 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.

- Skill: `wwiiitt/human-aes-expert` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add wwiiitt/human-aes-expert`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wwiiitt/human-aes-expert/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: WWIIITT (https://skillmd.com/u/wwiiitt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wwiiitt/human-aes-expert

---


# 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

1. **Non-destructive**: Never remove/add/relocate background objects unless explicitly requested
2. **Precision targeting**: Only dimensions scoring below threshold get improvement prompts
3. **Identity preservation**: Subject must remain recognizable as the same person
4. **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

1. **Score** all 12 dimensions via Gemini vision analysis
2. **Filter** dimensions below threshold (default: 7.0)
3. **Rank** by priority weight (facial > body > environment)
4. **Map** each low dimension to a specific improvement instruction
5. **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

```bash
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](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.