Upscaler

---
name: upscaler
description: "Image upscaling utility — image in, upscaled image out (2× / 4× / 8×). Wraps Replicate upscalers (Real-ESRGAN default; GFPGAN for faces, SwinIR, clarity-upscaler). Optional --face-enhance for portrait restoration. Use when: 'upscale', 'enhance resolution', 'sharpen low-res image', 'make this bigger', 'улучши разрешение', 'увеличь фотку', 'апскейл'."

license: MIT
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
---

<objective>
Image upscaling utility. Single input image → output upscaled by 2× / 4× / 8× factor. Sharper, higher resolution, with AI-based detail interpolation (vs simple bilinear / bicubic).

This skill does NOT:
- Generate new content — it ENHANCES existing pixels via super-resolution models
- Magic-restore an image from junk-tier (16×16 thumbnail to 4K HD) — input quality matters; garbage in, garbage out
- Handle video — one frame at a time only
- Vectorize — output remains raster PNG
- Remove background (chain with `bg-remover`)
- Fix major artifacts (deep blur, motion blur, JPEG mosquito noise at extreme levels) — works best on mildly low-res / soft images
</objective>

## ROLE

Read input image → call a Replicate-hosted upscaler → save the upscaled output at the requested scale factor.

## PIPELINE

1. **Resolve input**:
   - `--image <path-or-url>` (required)

2. **Pick provider**:
   - Default: `nightmareai/real-esrgan` (popular general-purpose, ~$0.005/image at 4×)
   - Alternatives via `--replicate-model <id>`:
     - `nightmareai/real-esrgan` — default; best general
     - `tencentarc/gfpgan` — face-focused (best for portraits)
     - `jingyunliang/swinir` — alternative general
     - `philz1337x/clarity-upscaler` — high-fidelity preservation, slower
   - Other Replicate upscalers: pass via `--replicate-model <slug>`

3. **Scale**: `--scale 2|4|8` (default 4).

4. **Face enhance** (optional): `--face-enhance` enables face restoration (Real-ESRGAN supports GFPGAN-style face restoration as a flag).

5. **Execute** via the Replicate router (REPLICATE_API_TOKEN required).

6. **Save**:
   - Default: `./generated/upscaled/<input-stem>-4x.png` (or `-2x.png` / `-8x.png`)
   - Custom: `--output <path>`

## MODES

### Required

- `upscaler --image <path-or-url>`

### Options

- `--scale 2|4|8` — upscaling factor (default 4)
- `--output <path>` — explicit output path
- `--replicate-model <id>` — override default upscaler model
- `--face-enhance` — enable face restoration (works with Real-ESRGAN, GFPGAN)
- `--yes` — skip cost confirmation
- `--check` — verify REPLICATE_API_TOKEN + connectivity

## REFERENCES (load on demand)

| File | When to load |
|---|---|
| [references/providers.md](references/providers.md) | Replicate upscaler model comparison + when to pick which |
| [references/use-cases.md](references/use-cases.md) | Real-world scenarios (old photo restoration, product shots, low-res AI gen output) |
| [references/troubleshoot.md](references/troubleshoot.md) | When output is blurry, faces get distorted, artifacts appear |

## EXAMPLES

See [examples/before-after.md](examples/before-after.md) — 3 calibration runs: AI-gen image at higher resolution, old family photo restoration, product shot enhancement.

## CONSTRAINTS

- **Single image per call.** For batch: run in a shell loop.

- **Replicate API key required.** Set via `/skills-keys add REPLICATE_API_TOKEN r8_...`.

- **Cost**: ~$0.005-0.02 per image depending on model and scale. 4× cheapest; 8× ~3× more expensive.

- **Input quality matters.** Models can enhance mildly-low-res images (480p → 1920p, soft → sharp). They CANNOT magic-restore severely degraded images.

- **Face preservation**: use `--face-enhance` or switch to `--replicate-model tencentarc/gfpgan` for portraits. Without this, generic upscalers may distort facial features.

- **Output dimensions** = input × scale factor. A 512×512 input at `--scale 4` → 2048×2048 output. Plan disk space.

- **Output format is PNG by default.** Source format preserved when possible; transparent backgrounds maintained.

- **Default 4×** is the most-supported scale across all upscalers. Some models don't support 8×.

- **No re-encoding to JPEG by skill.** If you need JPEG: convert after via `magick` or Photoshop / Affinity.

- **Never print API keys.**

- **Output dir is `./generated/upscaled/`** by default.

## INVOCATION HINTS

When the user says any of:

- "upscale this image", "enhance the resolution"
- "make this bigger / sharper", "fix this low-res image"
- "4x upscale", "8x upscale"
- "улучши разрешение", "увеличь фотку", "апскейл", "повысь разрешение"
- "сделай четче"

Defaults: `--image <path>` (required); 4× via Real-ESRGAN; saves to `./generated/upscaled/<stem>-4x.png`.

For portrait / face photos: prefer `--face-enhance` or `--replicate-model tencentarc/gfpgan`.

For AI-gen output to upscale: default (Real-ESRGAN) works well; the model is trained on a mix of real + AI imagery.

This skill is distinct from:
- `image-prompt` / `cover-maker` / etc. — they GENERATE new images. This ENHANCES existing.
- `bg-remover` — that's segmentation (transparent BG). This is super-resolution.
- `style-transfer` (planned) — that's stylization. This is resolution.
- `style-check` etc. — those are text linters, not visual utilities.