---

name: image-convert description: Convert images between formats (PNG, JPEG, WebP, GIF, BMP, TIFF, AVIF, HEIC) with quality control and resizing. Use when the user needs to convert images, batch process multiple files, optimize image sizes, or convert to modern formats like WebP or AVIF.

Image Convert

Convert images between formats with quality control, resizing, and batch processing support.

Supported Formats

Format	Extension	Notes
PNG	.png	Lossless, supports transparency
JPEG	.jpg, .jpeg	Lossy compression, no transparency
WebP	.webp	Modern format, good compression
GIF	.gif	Animation support (first frame only)
BMP	.bmp	Uncompressed, large files
TIFF	.tiff, .tif	High quality, large files
AVIF	.avif	Next-gen format, best compression
HEIC	.heic, .heif	Apple format

Quick Start

Single File Conversion

Convert by specifying output extension:

scripts/convert.sh input.png output.jpg

Or specify format explicitly:

scripts/convert.sh -f webp input.png output.webp

With Quality and Resize

# Convert to JPEG with 90% quality and resize to 1920px width
scripts/convert.sh -f jpg -q 90 -r 1920x input.png output.jpg

# Convert to WebP at 50% of original size
scripts/convert.sh -f webp -q 85 -r 50% input.png output.webp

Batch Conversion

Convert all PNG files to WebP:

scripts/convert.sh -f webp *.png

Output files will have the same basename with the new extension.

Command Options

Option	Description	Example
-f, --format	Output format	-f webp
-q, --quality	Quality 1-100 (default: 85)	-q 90
-r, --resize	Resize geometry	-r 800x600, -r 50%
-v, --verbose	Show conversion commands	-v
-h, --help	Show help	-h

Resize Geometry

Syntax	Description	Example
WxH	Exact dimensions (may crop)	800x600
Wx	Width only, height proportional	1920x
xH	Height only, width proportional	x1080
W%	Percentage of original	50%

Tool Dependencies

The script uses available tools in this priority:

1. ImageMagick (magick or convert): Primary tool for all formats
   • Prefers magick (ImageMagick 7+)
   • Falls back to convert (legacy ImageMagick 6) if needed
2. cwebp/dwebp: Optimized WebP conversion when available
3. sips (macOS): Can be used as fallback on macOS

Install ImageMagick for full functionality:

# macOS
brew install imagemagick webp

# Ubuntu/Debian
sudo apt-get install imagemagick webp

# Arch
sudo pacman -S imagemagick libwebp

Common Workflows

Optimize Images for Web

Convert to WebP with good quality and reasonable size:

scripts/convert.sh -f webp -q 80 -r 1200x *.png

Create Thumbnails

Generate 300px wide thumbnails:

for img in *.jpg; do
    scripts/convert.sh -f jpg -q 75 -r 300x "$img" "thumbs/$img"
done

Convert HEIC to JPEG

scripts/convert.sh -f jpg -q 95 IMG_1234.HEIC output.jpg

PNG to Lossy for Smaller Size

scripts/convert.sh -f webp -q 85 large.png small.webp

Related Skills

• Video → animated WebP: Use the video-to-webp skill. It handles fps, trimming, looping, and scaling with ffmpeg + img2webp.

Tips

• WebP: Best for web - 25-35% smaller than JPEG with same quality
• AVIF: Best compression but slower encoding, limited support
• PNG: Use for graphics with transparency or when lossless is required
• JPEG: Good for photos when WebP/AVIF aren't options
• Quality 80-85: Good balance of size and quality
• Quality 90-95: High quality for important images
• Quality 60-75: Acceptable for thumbnails/previews