# Optimize Gif

> 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.

- Skill: `warpdotdev/optimize-gif` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add warpdotdev/optimize-gif`
- Raw SKILL.md: https://api.skillmd.com/api/skills/warpdotdev/optimize-gif/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: warpdotdev (https://skillmd.com/u/warpdotdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/warpdotdev/optimize-gif

---


# 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:
```bash
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:
```bash
# 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:
   ```bash
   ./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:
```bash
# 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.