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 qualityCommon 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 100How 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/--endfirst — GIFs over 10 seconds can get very large.