/bg-remover

name: bg-remover
description: "Background removal utility — image in, transparent PNG out. Wraps Replicate-hosted models (851-labs/background-remover default; alternatives via --replicate-model). Use when: 'remove the background', 'cut out the subject', 'transparent PNG', 'убери фон', 'вырежи фон с фотки'."

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

<objective> Remove the background from a photo. Single input image → output PNG with transparent (alpha channel) background. Subject preserved as-is; everything else becomes transparent.

This skill does NOT:

• Replace the background with a new image — for that, use the transparent PNG output + paste into a new background in your image editor, OR use `image-prompt --execute --model flux-kontext --image-url <photo> --prompt "subject in new setting"` for full reimagining
• Remove specific objects from a complex scene — only removes BACKGROUND (everything not the main subject)
• Process video — single image only (per call)
• Restore / upscale / sharpen — see future `upscaler` skill

</objective>

ROLE

Read the input image → call a Replicate-hosted bg-removal model → save the transparent PNG.

PIPELINE

1. **Resolve input**:

• `--image <path-or-url>` (required)
• Local file or remote URL

2. **Pick provider**:

• Default: `851-labs/background-remover` (popular, accurate on photos)
• Alternatives via `--replicate-model <id>`:
• `851-labs/background-remover` — default; best general
• `lucataco/remove-bg` — alternative
• `cjwbw/rembg` — Python `rembg` library hosted
• `pollinations/modnet` — MODNet (good for portraits)
• Other Replicate bg-removers: pass via `--replicate-model <slug>`

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

4. **Save**:

• Default: `./generated/bg-removed/<input-stem>-nobg.png` (transparent)
• Custom: `--output <path>`

MODES

Required

• `bg-remover --image <path-or-url>`

Options

• `--output <path>` — explicit output path
• `--replicate-model <id>` — override default bg-remover model
• `--execute` — defaults to true (this skill always executes; no prompt-only mode for a utility)
• `--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 bg-removal model comparison + when to pick which | | [references/output-format.md](references/output-format.md) | Transparent PNG handling, alpha channel, downstream usage | | [references/troubleshoot.md](references/troubleshoot.md) | When subject loses edges, hair gets cropped, etc. |

EXAMPLES

See [examples/before-after.md](examples/before-after.md) — 2 calibration runs: portrait photo → transparent for avatar use; product shot → transparent for e-commerce listing.

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.001-0.005 per image depending on model. Very cheap.

• **Default model handles most photos well.** Switch to `pollinations/modnet` for portraits if hair edges are critical.

• **Subject must be CLEARLY distinguishable from background.** Models struggle with:
• Subjects that match background color
• Multiple subjects (picks one or merges)
• Transparent objects (glass / water)
• Hair against busy backgrounds (some loss of fine detail expected)

• **Output is always PNG with alpha channel.** RGB → RGBA conversion automatic.

• **Source resolution preserved.** Output dimensions match input.

• **No re-encoding to JPEG.** Transparent backgrounds require PNG (or WebP) — JPEG doesn't support transparency.

• **Never print API keys.**

• **Output dir is `./generated/bg-removed/`** by default.

INVOCATION HINTS

When the user says any of:

• "remove the background", "cut out the subject"
• "transparent PNG", "no background version"
• "убери фон", "вырежи фон с фотки", "сделай прозрачный фон"
• "make the background transparent"

Defaults: `--image <path>` (required); auto-saves to `./generated/bg-removed/<stem>-nobg.png`.

If the user wants to REPLACE the background (not just remove), suggest: 1. Use this skill to get a transparent PNG. 2. Then use `image-prompt --execute --model flux-kontext --image-url <photo>` for AI-driven replacement. 3. OR open the transparent PNG in an image editor and composite with a new background manually.

This skill is distinct from:

• `image-prompt` / `avatar-maker` — they generate NEW images. This is a utility on EXISTING images.
• `subtitle-burner` — that's video utility. This is image utility.
• `upscaler` (planned) — that's resolution. This is background removal.