# Image Forge

> Edit images with precision using ImageMagick 7, sips, transparent-background, and Pillow — with intelligent routing to AI semantic editing (Gemini/nano-banana-pro) for content-aware operations. Covers cropping, resizing, compositing, annotating, format conversion, color adjustment, background removal, batch processing, and montage creation. Triggers on image editing, crop, resize, composite, anno…

- **Type:** Skill
- **Install:** `agentstack add skill-tdimino-claude-code-minoan-image-forge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tdimino](https://agentstack.voostack.com/s/tdimino)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tdimino](https://github.com/tdimino)
- **Source:** https://github.com/tdimino/claude-code-minoan/tree/main/skills/design-media/image-forge
- **Website:** https://www.minoanmystery.org

## Install

```sh
agentstack add skill-tdimino-claude-code-minoan-image-forge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Image Forge

Pixel-precise image editing with three-tier routing: deterministic CLI tools for exact operations, AI models for semantic edits, vision models for analysis.

## Routing Decision

**Use AI when the edit requires understanding what is in the image. Use ImageMagick when the edit requires knowing exactly what to do to the pixels.**

### Tier 1: Deterministic (magick, sips, transparent-background)

Use for operations with exact, numeric parameters:

| Task | Tool | Command |
|------|------|---------|
| Resize to exact dimensions | magick | `magick in.jpg -resize 800x600! out.jpg` |
| Resize fit (preserve aspect) | magick | `magick in.jpg -resize 800x600 out.jpg` |
| Resize fill + crop | magick | `magick in.jpg -resize 800x600^ -gravity center -extent 800x600 out.jpg` |
| Resize shrink only | magick | `magick in.jpg -resize '800x600>' out.jpg` |
| Crop at offset | magick | `magick in.jpg -crop 600x400+100+50 +repage out.jpg` |
| Center crop | magick | `magick in.jpg -gravity center -crop 600x400+0+0 +repage out.jpg` |
| Auto-trim whitespace | magick | `magick in.jpg -fuzz 10% -trim +repage out.jpg` |
| Format convert | magick | `magick in.png -quality 85 out.jpg` |
| Add text | magick | `magick in.jpg -fill white -pointsize 36 -annotate +10+50 'Text' out.jpg` |
| Composite overlay | magick | `magick bg.png fg.png -geometry +50+100 -composite out.png` |
| Watermark | magick | `magick photo.jpg wm.png -gravity SouthEast -geometry +10+10 -compose Dissolve -define compose:args=25 -composite out.jpg` |
| Adjust brightness/contrast | magick | `magick in.jpg -brightness-contrast 10x20 out.jpg` |
| Adjust saturation | magick | `magick in.jpg -modulate 100,130,100 out.jpg` |
| Grayscale | magick | `magick in.jpg -colorspace Gray out.jpg` |
| Sepia | magick | `magick in.jpg -sepia-tone 80% out.jpg` |
| Blur | magick | `magick in.jpg -blur 0x3 out.jpg` |
| Sharpen | magick | `magick in.jpg -sharpen 0x1 out.jpg` |
| Remove background (AI) | transparent-background | See **Background Removal** section below |
| Remove background (simple) | magick | `magick in.jpg -fuzz 15% -transparent white -trim +repage out.png` |
| Strip metadata | magick | `magick in.jpg -strip out.jpg` |
| Set DPI | magick | `magick in.jpg -density 300 out.jpg` |
| Batch resize | `batch_ops.py` | `python3 scripts/batch_ops.py *.jpg --op resize --width 800 --output resized/` |
| Montage/contact sheet | magick | `magick montage *.jpg -geometry 200x200+5+5 -tile 4x out.jpg` |
| Quick format convert (macOS) | sips | `sips -s format jpeg in.png --out out.jpg` |
| Quick resize (macOS) | sips | `sips -Z 800 in.jpg --out out.jpg` |

### Tier 2: AI Semantic (nano-banana-pro / Gemini)

Delegate to the `nano-banana-pro` skill when the edit requires understanding image content:

- Remove a person/object from a photo
- Change sky, weather, time of day
- Apply artistic style transfer
- Inpaint/outpaint regions
- Generate new image from scratch
- Content-aware fill after object removal

**Nano Banana regenerates, it does not edit.** Every call re-rolls the entire frame, even when the prompt asks to preserve regions verbatim. Expect ~40% of pixels to drift outside the target area — measured empirically, not hypothesized. For surgical regional edits (change the face, keep everything else identical), use the hybrid pattern in `references/compositing.md` § Surgical Regional Edits: let NB produce a drifted reference, then composite only the target region onto the pristine original with a feathered alpha mask.

Nano Banana also supports only discrete aspect ratios (1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9). For inputs at other ratios (e.g. 3:1 panoramics), see `references/recipes.md` § Aspect Ratio Padding for the pad-generate-crop recipe.

### Tier 3: Vision Analysis (Claude Read tool)

Use the Read tool to inspect images before/after edits:

- Verify an edit succeeded
- Describe image contents
- Check composition and framing
- Identify colors, objects, text in image

## Background Removal

Use `transparent-background` (InSPyReNet model) for AI background removal. It produces clean alpha mattes with smooth anti-aliased edges — far superior to ImageMagick's `-transparent`/`-fuzz` approach, which leaves white fringing in concave regions and jagged edges.

**When to use each:**

| Method | When | Quality |
|--------|------|---------|
| `transparent-background` | Any photo/render with complex foreground (hair, translucent edges, concave regions) | Smooth alpha, no fringing |
| `magick -transparent white -fuzz N%` | Simple shapes on pure white, quick-and-dirty | Fast but aliased edges, misses interior white |
| `magick floodfill` | Remove background from corners only, preserve interior white | Only hits connected regions |

**Python API (recommended):**

```python
from transparent_background import Remover
from PIL import Image

remover = Remover()
img = Image.open("input.jpg").convert("RGB")
out = remover.process(img, type="rgba")
out.save("output.png")
```

**With trim (most common workflow):**

```bash
python3 -c "
from transparent_background import Remover
from PIL import Image
remover = Remover()
img = Image.open('input.jpg').convert('RGB')
remover.process(img, type='rgba').save('/tmp/nobg.png')
"
magick /tmp/nobg.png -trim +repage output.png
```

**Install:** `uv pip install --system transparent-background`

**Performance:** ~2-3s per image on Apple Silicon (MPS). First run downloads the InSPyReNet model (~170MB).

**Note:** `rembg` is an alternative but has a broken `gradio` dependency as of May 2026. `transparent-background` is the more reliable option.

## Scripts

All scripts are in `~/.claude/skills/image-forge/scripts/`. Run with `python3`.

### image_info.py — Inspect Image Metadata

```bash
python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg
python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg --field dimensions
python3 ~/.claude/skills/image-forge/scripts/image_info.py photo.jpg --field width
```

Returns clean JSON: dimensions, format, color space, depth, alpha, DPI, ICC profile, EXIF.

### image_pipeline.py — Declarative Edit Pipeline

Write a JSON spec, get a single chained `magick` command. No intermediate files.

```bash
# Create spec
cat > /tmp/pipeline.json ` | Shrink only if larger |
| `800x600`, `' out.jpg
```

## Critical Reminders

1. **Always `+repage` after `-crop`** — Virtual canvas offset persists without it
2. **`-modulate` order is B,S,H** — Brightness, Saturation, Hue (not H,S,L)
3. **Settings persist, operators execute immediately** — Order matters in magick commands
4. **Use `rembg` for background removal** — `rembg i input.jpg output.png` (add `-a` for alpha matting)
5. **Quote geometry** — `>`, `<`, `^` are shell metacharacters
6. **`-alpha off` is permanent in IM7** — Use `-alpha deactivate`/`-alpha activate` for temporary toggle
7. **Inspect before editing** — Run `image_info.py` first to know dimensions, format, alpha state
8. **Pipeline for multi-step** — Use `image_pipeline.py` instead of chaining shell commands
9. **Nano Banana drifts the whole frame** — Never trust NB to leave regions unchanged. For regional edits, use the surgical composite pattern (see `compositing.md` § Surgical Regional Edits). Verify with `magick compare -metric AE -fuzz 5% before after diff.png` — low AE means clean, ~40%+ means full regeneration.

## References

Detailed references in `~/.claude/skills/image-forge/references/`:

- `magick-reference.md` — Complete ImageMagick 7 command reference (resize, crop, color, text, drawing, batch, identify)
- `compositing.md` — All compositing operators (Duff-Porter, mathematical, lighting, HSL, special)
- `recipes.md` — 30+ recipes (borders, shadows, watermarks, social sizing, color effects, sprites, batch patterns)

## Dependencies

| Tool | Version | Install |
|------|---------|---------|
| ImageMagick | 7.1.2-7 (Q16-HDRI) | `brew install imagemagick` |
| rembg | 2.0.72 | `uv pip install rembg` |
| sips | macOS built-in | — |
| Pillow | 10.4.0 | `uv pip install Pillow` |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tdimino](https://github.com/tdimino)
- **Source:** [tdimino/claude-code-minoan](https://github.com/tdimino/claude-code-minoan)
- **License:** MIT
- **Homepage:** https://www.minoanmystery.org

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tdimino-claude-code-minoan-image-forge
- Seller: https://agentstack.voostack.com/s/tdimino
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.