Image

Still-image processing with ImageMagick, exiftool, and Tesseract. Use this skill when you need to modify or inspect raster images (PNG, JPEG, WebP, TIFF, etc.).

When to use

• This skill — format conversion, geometry edits (resize/crop/rotate/flip), compression, EXIF read/strip, OCR.
• inspect — probe video/audio/image containers with ffprobe without changing files. Run first if you are unsure of dimensions or format.
• download — fetch remote media before local image processing.

Gotchas

• ImageMagick v7 — some systems expose magick instead of convert. These scripts call convert; install the imagemagick package or symlink convert → magick if needed.
• Resize without height — --width 800 with no --height preserves aspect ratio (800x geometry). Specifying both forces exact dimensions (may distort).
• Crop geometry — width x height + x + y is in pixels from the top-left. Values outside the image bounds fail or return partial crops depending on ImageMagick policy.
• Optimize outputs JPEG — optimize.py always writes JPEG at quality 85 with metadata stripped. Use convert.py for lossless PNG/WebP output.
• EXIF on PNG/WebP — read_exif.py returns whatever exiftool finds; synthetic or ffmpeg-generated images often have minimal metadata.
• OCR quality — Tesseract works best on high-contrast, deskewed text. Preprocess with convert (grayscale, threshold) for noisy scans. Use --lang for non-English (e.g. deu, fra).
• Policy restrictions — ImageMagick policy.xml may block PDF/PS reads on some Linux installs. Error mentions "not authorized".

Running scripts

This skill's scripts live in scripts/ alongside this file. Before running any script, resolve its absolute path from this skill's own directory — do not assume the shell cwd is the skill folder, the repo root, or the workspace. Stay in the workspace (so media paths resolve) and pass the absolute script path to uv run:

uv run <skill_directory>/scripts/convert.py --input "<path-to-image>" --format jpg

<skill_directory> is a placeholder. Never pass those angle brackets to the shell — the command will fail. Replace it with a real absolute directory before invoking uv run.

How to get that directory (do this yourself; do not ask the user first; do not skip the skill):

1. If your tools showed a filesystem path when loading this SKILL.md, strip SKILL.md and use that folder.
2. If you already ran another mediaskills script (for example .../audio/scripts/extract.py), this skill is a sibling of that folder: same parent, directory name image.
3. Otherwise search standard install locations and confirm the script exists:

NAME=image
for d in \
  "$HOME/.agents/skills/$NAME" \
  "$HOME/.cursor/skills/$NAME" \
  "$HOME/.codex/skills/$NAME" \
  "$HOME/.claude/skills/$NAME" \
  "$PWD/.agents/skills/$NAME" \
  "$PWD/.cursor/skills/$NAME" \
  "$PWD/skills/$NAME"
do
  if [ -f "$d/SKILL.md" ] && [ -e "$d/scripts/convert.py" ]; then
    SKILL_DIR=$(cd "$d" && pwd)
    break
  fi
done
[ -n "$SKILL_DIR" ] || { echo "mediaskills: $NAME not found" >&2; exit 1; }
uv run "$SKILL_DIR/scripts/convert.py" --input "<path-to-image>" --format jpg

Prefer absolute paths for --input / --output when cwd is uncertain.

Missing binaries vs permissions

Before running any script, treat these two failures differently:

• If a required binary (uv, convert, exiftool, tesseract) reports No such file or directory or command not found: this is a missing or unreachable binary, not a permissions issue. Escalating sandbox permissions will not fix it. Run command -v uv, command -v convert, command -v exiftool, and command -v tesseract to see whether they resolve at all. If not, install or re-link them (install-media-tools doctor/install) rather than retrying with wider permissions. tesseract is required for ocr.py; other scripts need ImageMagick convert and/or exiftool.
• Only escalate sandbox permissions if the error is explicitly a permission denial (e.g. Operation not permitted, Permission denied).

Recipes

Convert PNG to JPEG

uv run <skill_directory>/scripts/convert.py --input photo.png --format jpg

Resize for web (max width 1200, keep aspect)

uv run <skill_directory>/scripts/resize.py --input hero.png --width 1200

Crop a thumbnail from coordinates

uv run <skill_directory>/scripts/crop.py --input photo.jpg --width 400 --height 400 --x 100 --y 50

Rotate 90° clockwise

uv run <skill_directory>/scripts/rotate.py --input scan.png --degrees 90

Mirror horizontally

uv run <skill_directory>/scripts/flip.py --input photo.png --direction horizontal

Shrink file size for sharing

uv run <skill_directory>/scripts/optimize.py --input large.png

Read camera metadata before editing

uv run <skill_directory>/scripts/read_exif.py --input IMG_1234.jpg

Strip GPS and camera info before upload

uv run <skill_directory>/scripts/strip_metadata.py --input IMG_1234.jpg

OCR text from a screenshot

uv run <skill_directory>/scripts/ocr.py --input screenshot.png

Troubleshooting

Available scripts

Acceptance checks (agent must pass before delivery)

1. Contract: exit 0, ok: true, every output_paths entry exists and is non-empty.
2. Spot-check: open the output still — dimensions/format match request; OCR text is readable for the intended region when using ocr.py.
3. On failure: fix or escalate; do not present zero-byte or wrong-geometry images as complete.

Do not use for

• Video timeline edits (use video-transformation)
• PDF or vector graphics
• RAW/developed photo workflows (develop first, then convert.py)

Related skills

• inspect — probe dimensions and format before editing
• download — fetch images from URLs
• install-media-tools — install ImageMagick, exiftool, tesseract