video-to-gif

SKILL.md

Skill: Video to GIF

Convert a video file into multiple GIF variants with different parameters, so the user can visually compare and pick the best one.

Prerequisite: FFmpeg and uv must be installed. gifsicle is optional (enables lossy compression variants).

When to Use

The user wants to create a GIF from a video clip but isn't sure about the right parameters. GIF quality involves tradeoffs between:

File size — smaller is better for sharing/embedding

Color accuracy — fewer colors = smaller but may cause banding

Smoothness — higher FPS = smoother but larger

Resolution — wider = sharper detail but larger

Rather than guessing, this skill generates multiple variants and lets the user decide.

Default Workflow

When the user provides a video file:

uv run --python 3.12 /path/to/skills/video-to-gif/scripts/video_to_gif.py <input.mp4>

This generates GIFs in <input>_gifs/ directory with the full preset (18 variants):

3 FPS options: 10, 15, 20

3 widths: 480px, 640px, 800px

2 color counts: 128, 256

Output includes a sorted comparison table showing file size, FPS, width, and colors for each variant.

Presets

Preset
Variants
Best For

full
~18
General use — broad exploration of the parameter space

minimal
~4
Quick comparison — just a few key tradeoff points

lossy
~12
Smallest files — includes gifsicle lossy compression levels

quality
~12
Best visuals — higher res, includes bayer dithering

# Quick comparison with fewer variants
uv run --python 3.12 .../video_to_gif.py input.mp4 --presets minimal

# Include lossy compression (requires gifsicle)
uv run --python 3.12 .../video_to_gif.py input.mp4 --presets lossy

# Higher quality focus
uv run --python 3.12 .../video_to_gif.py input.mp4 --presets quality

Common Options

Flag
Default
Description

-o, --output-dir
<input>_gifs/
Output directory for all GIF variants

--start
none
Start time in seconds (trim source)

--end
none
End time in seconds (trim source)

--presets
full
Preset config: full, minimal, lossy, quality

--fps
preset
Override FPS values (e.g., --fps 10 15 20)

--width
preset
Override width values (e.g., --width 480 640)

--colors
preset
Override color counts (e.g., --colors 128 256)

--lossy
preset
Gifsicle lossy levels (e.g., --lossy 0 30 80)

Examples

# Convert first 10 seconds of a video
uv run --python 3.12 .../video_to_gif.py demo.mp4 --end 10

# Extract a specific segment
uv run --python 3.12 .../video_to_gif.py demo.mp4 --start 5 --end 15

# Custom parameter sweep
uv run --python 3.12 .../video_to_gif.py demo.mp4 --fps 12 15 --width 480 800 --colors 256

# Lossy compression comparison (needs gifsicle)
uv run --python 3.12 .../video_to_gif.py demo.mp4 --lossy 0 30 60 100

How to Choose

After running, open the output directory and compare:

Start with the smallest files — check if quality is acceptable

Look for color banding — if visible, try 256 colors or bayer dithering (quality preset)

Check smoothness — if too choppy, go up to 15 or 20 FPS

Check clarity — if text is unreadable, go up to 640 or 800px width

The sweet spot for most screen recordings is usually around 640px, 15fps, 256 colors.

Important Notes

Widths larger than the source video resolution are automatically skipped.

The script uses FFmpeg's two-pass palette generation for optimal GIF quality (much better than single-pass).

Lossy compression via gifsicle can reduce file size by 30-70% with minimal visual impact at level 30-60.

For very long clips, consider trimming with --start/--end first — GIFs over 10 seconds can get very large.