optimize-gif

name	optimize-gif
description	Optimize GIF files or convert video files (MP4, MOV, WebM) into compact, high-quality GIFs suitable for email, docs, or the web. Uses gifsicle, ffmpeg, and gifski on macOS via Homebrew. Use this skill whenever the user wants to compress a GIF, shrink a GIF, convert a video to GIF, make a GIF smaller, prepare GIFs for email, or batch-process screen recordings into GIFs.

optimize-gif

Purpose

Convert videos or optimize existing GIFs into the smallest possible file while preserving visual quality. Designed for email use cases but works for any context where GIF size matters.

Dependencies

All installable via Homebrew. Install any that are missing before proceeding:

brew install gifsicle ffmpeg gifski

• gifsicle — GIF optimization (lossy compression, color reduction, frame optimization)
• ffmpeg — Video-to-GIF conversion with palette optimization
• gifski — Highest-quality video-to-GIF encoder (perceptual quantization in CIELAB color space)

Quick Reference

The bundled script handles everything. Run it from this skill's scripts/ directory:

# Single file
./scripts/optimize-gif-for-email.sh input.mp4

# Batch
./scripts/optimize-gif-for-email.sh *.mp4

# With options
./scripts/optimize-gif-for-email.sh -w 600 -f 25 -c 128 -l 60 -e gifski input.mov

When to Use Which Encoder

• gifski (default): Best quality-per-byte. Uses perceptual color quantization. Ideal for screen recordings and product demos where visual fidelity matters. Slower.
• ffmpeg: More aggressive compression, sometimes produces smaller files. Better control over dithering. Use when file size is the top priority over quality. Faster.

Both encoders are followed by a gifsicle optimization pass (only applied when it actually reduces size).

Workflow

Video → GIF (preferred path)

Always start from video when possible — it preserves full color information and lets our tools generate an optimal palette. If the user has a screen recording tool (like Screen Studio), they should export as high-quality video (ProRes or high-bitrate H.264), not GIF.

1. Run the script with video input:

   ./scripts/optimize-gif-for-email.sh -w 600 -f 25 input.mov
   

2. Output goes to optimized/ subfolder next to the input (or use -o for custom output dir).
3. Review the size report. If too large, try:
   • Reducing width: -w 480
   • Switching to ffmpeg encoder: -e ffmpeg
   • Increasing lossy level: -l 100
   • Reducing colors: -c 64

Existing GIF → Smaller GIF

For GIFs that already exist and can't be re-created from video, use gifsicle directly:

# Lossless optimization
gifsicle -O3 input.gif -o optimized.gif

# Lossy + resize + color reduction
gifsicle --resize-width 600 --lossy=80 --colors 128 -O3 input.gif -o optimized.gif

Optimization Levers (Ordered by Impact)

1. Reduce dimensions — Biggest win. 1000px → 600px = ~64% fewer pixels. Email standard is 600px wide.
2. Reduce frame rate — Linear impact. 30fps → 15fps ≈ 50% reduction. But below 20fps may look choppy for product demos.
3. Reduce color palette — 256 → 128 colors is nearly imperceptible. 64 colors works for simple UI animations.
4. Lossy compression — gifsicle --lossy=60 gives 30-60% reduction with minimal visible artifacts.
5. LZW optimization — gifsicle -O3 is free (lossless, 5-20% reduction).

Script Options

Flag	Default	Description
-w	600	Target width in pixels
-f	25	Frame rate
-c	128	Max colors for palette
-l	60	Gifsicle lossy level (0-200)
-e	gifski	Encoder: "gifski" (quality) or "ffmpeg" (smaller)
-o	<input_dir>/optimized/	Output directory

Email Size Guidelines

• Under 1MB: Ideal for email. Fast loading on all connections.
• 1-3MB: Acceptable. Loads fine on wifi/4G. May be slow on 3G.
• 3-5MB: Heavy but workable. Gmail/Apple Mail load images asynchronously so it won't block the email.
• Over 5MB: Too large for email. Reduce dimensions or frame rate.

Failure Handling

• Missing dependencies → script reports which tool is missing and the brew install command.
• Encoder failure → reported per-file, other files continue processing.
• gifsicle makes file larger → script automatically keeps the encoder's output instead.