| name | format-convert |
| description | Convert images between formats: PNG, JPG/JPEG, WebP, TIFF, BMP, GIF, HEIC, and AVIF. Performs high-quality lossless conversion by default. Handles alpha channel transparency automatically — compositing against a configurable background color when converting to formats that lack alpha support (JPG, BMP). Supports single-file and batch directory conversion with optional recursive subdirectory scanning. Uses ImageMagick. Use this skill whenever the user wants to: convert an image to another format, change image format, save as PNG/JPG/WebP/TIFF, convert HEIC photos to JPG or PNG, batch convert images, make images web-compatible, convert to WebP for web optimization, or anything involving image format conversion. Also trigger when the user mentions format names in the context of converting, exporting, or saving images.
|
Format Convert — Lossless Image Format Converter
Convert any image between PNG, JPG, WebP, TIFF, BMP, GIF, HEIC, and AVIF using ImageMagick. Lossless by default — preserves maximum quality and original dimensions.
Prerequisites
ImageMagick is required. For HEIC/AVIF support, ensure delegates are installed.
brew install imagemagick
sudo apt install imagemagick
How to use
Run the bundled script:
bash "${CLAUDE_SKILL_DIR}/scripts/convert.sh" <input-image> --to FORMAT [OPTIONS]
Options
| Flag | Description | Default |
|---|
--to FORMAT | Target format (png, jpg, webp, tiff, bmp, gif, heic, avif) | (required) |
--output DIR | Output directory | ./converted/ |
--quality N | Quality for lossy formats 1-100 | 100 |
--bg-color HEX | Background color when removing alpha (6-digit hex, no #) | FFFFFF |
--batch DIR | Convert all supported images in a directory | — |
--recursive | Include subdirectories in batch mode | off |
--formats | List supported formats and exit | — |
Supported formats
For the full reference with alpha support, lossy/lossless details, and conversion notes, read references/formats.md.
| Format | Alpha | Quality |
|---|
| PNG | yes | lossless |
| JPG | no | lossy |
| WebP | yes | both |
| TIFF | yes | lossless |
| BMP | no | lossless |
| GIF | yes (1-bit) | lossless |
| HEIC | yes | lossy |
| AVIF | yes | both |
Examples
Convert PNG to JPG:
bash "${CLAUDE_SKILL_DIR}/scripts/convert.sh" screenshot.png --to jpg
Convert HEIC photos to PNG:
bash "${CLAUDE_SKILL_DIR}/scripts/convert.sh" photo.heic --to png
Convert to WebP for web optimization:
bash "${CLAUDE_SKILL_DIR}/scripts/convert.sh" banner.png --to webp --quality 90
Batch convert all images in a folder to WebP:
bash "${CLAUDE_SKILL_DIR}/scripts/convert.sh" --batch ./images/ --to webp --output ./web-images/
Batch convert recursively:
bash "${CLAUDE_SKILL_DIR}/scripts/convert.sh" --batch ./photos/ --to jpg --recursive --output ./exported/
Transparent PNG to JPG with custom background:
bash "${CLAUDE_SKILL_DIR}/scripts/convert.sh" logo.png --to jpg --bg-color 000000
List supported formats:
bash "${CLAUDE_SKILL_DIR}/scripts/convert.sh" --formats
How it works
The script uses ImageMagick for all conversions with a lossless-first strategy:
-
Alpha detection — Before converting to a non-alpha format (JPG, BMP), the script checks whether the source image actually has transparency using magick identify -format "%A". Only images with real alpha data get flattened against the background color.
-
Quality maximization — The default quality is 100. For formats that support true lossless encoding:
- WebP at quality 100 enables
webp:lossless=true
- AVIF at quality 100 enables
heif:lossless=true
- PNG always uses lossless encoding (quality controls compression level only)
- TIFF uses uncompressed output (
-compress None)
-
Dimension preservation — The script never resizes. Output dimensions always match the source.
-
Same-format skip — If the source is already the target format, the file is skipped rather than re-encoded.
Format notes
- Animated GIFs — Only the first frame is converted. Full animation conversion is not supported.
- HEIC/AVIF — Require ImageMagick delegates (
libheif). If not installed, conversion will fail with a clear error.
- JPG/BMP from transparent sources — Alpha is composited against
--bg-color (default white). Opaque sources pass through unchanged.
Output naming
Files are saved as <original-name>.<target-ext> in the output directory. For example:
converted/screenshot.jpgconverted/photo.pngconverted/banner.webp
