/claude-gif-convert

name: claude-gif-convert
description: >
  Convert video files, image sequences, and animated SVGs to optimized GIFs.
  Mode A: Video to GIF (FFmpeg two-pass palette). Mode B: Image sequence to GIF.
  Mode C: AI image sequence to GIF (Gemini/FLUX.2 progressive prompts).
  Mode D: Animated SVG to transparent GIF (Playwright + FFmpeg).
  Use when user says "video to gif", "convert to gif", "screen recording gif",
  "images to gif", "photo sequence gif", "stop motion", "frames to gif",
  "svg to gif", "transparent gif", "animated svg to gif".
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit

claude-gif-convert -- Video, Image, and SVG to GIF Conversion

Four conversion modes for turning any visual source into an optimized GIF.

Mode Detection

Determine the mode from the input:

| Input | Mode | Pipeline | |-------|------|----------| | `.mp4`, `.webm`, `.mov`, `.avi`, `.mkv` | A: Video to GIF | ffprobe analyze --> gif_convert.sh | | Directory of `.png`/`.jpg`/`.webp` images | B: Image Sequence | glob + sort --> gif_frames.py | | Text description of progressive scenes | C: AI Image Sequence | AI generate N frames --> gif_frames.py | | `.svg` file (animated or static to animate) | D: SVG to Transparent GIF | Playwright capture --> FFmpeg palette |

---

Mode A: Video to GIF

Convert a video file to an optimized GIF using FFmpeg two-pass palette generation.

Procedure

1. **Analyze source video**:

ffprobe -v error -show_entries format=duration,size -show_entries stream=width,height,r_frame_rate,codec_name -of json INPUT.mp4

2. **Determine segment** (if video is long, ask user which portion):

• Full video: omit `--start` and `--duration`
• Segment: specify `--start SS --duration SS`
• Recommendation: GIFs should be 1-5 seconds. Warn if duration > 10s.

3. **Pre-flight check**:

bash ~/.claude/skills/claude-gif/scripts/preflight.sh INPUT.mp4 OUTPUT.gif

4. **Convert**:

bash ~/.claude/skills/claude-gif/scripts/gif_convert.sh \
  --input INPUT.mp4 \
  --preset web \
  --output ~/Documents/gif_output/output.gif

5. **Report result** (gif_convert.sh outputs JSON with size, dimensions, settings).

Preset Selection Guide

• User says "for Discord" or file must be tiny --> `--preset discord`
• User says "for Slack" --> `--preset slack`
• User says "for Twitter/X" --> `--preset twitter`
• User says "high quality" or "best quality" --> `--preset hq`
• No preference stated --> `--preset web`
• User specifies exact dimensions/fps --> omit preset, pass explicit flags

Advanced Options

bash ~/.claude/skills/claude-gif/scripts/gif_convert.sh \
  --input INPUT.mp4 \
  --fps 12 \
  --width 320 \
  --start 5.5 \
  --duration 3 \
  --dither bayer:bayer_scale=3 \
  --stats-mode diff \
  --colors 128 \
  --loop 0 \
  --output ~/Documents/gif_output/output.gif

---

Mode B: Image Sequence to GIF

Assemble a directory of images (PNG, JPG, WebP) into a GIF.

Procedure

1. **Identify images**:

ls /path/to/frames/*.png | head -5
ls /path/to/frames/*.png | wc -l

2. **Verify order**: Images should be named with sequential numbering (e.g., `frame_001.png`, `frame_002.png`). If not, they will be sorted alphabetically.

3. **Pre-flight check**:

bash ~/.claude/skills/claude-gif/scripts/preflight.sh /path/to/frames/frame_001.png OUTPUT.gif

4. **Assemble**:

~/.video-skill/bin/python3 ~/.claude/skills/claude-gif/scripts/gif_frames.py \
  --input-dir /path/to/frames/ \
  --pattern "*.png" \
  --fps 15 \
  --width 480 \
  --preset web \
  --output ~/Documents/gif_output/sequence.gif

Options

• `--input-dir`: Directory containing frame images
• `--pattern`: Glob pattern to match frames (default: `*.png`)
• `--fps`: Playback frame rate
• `--width`: Output width (height auto-calculated)
• `--preset`: Quality preset (discord/slack/twitter/web/hq)
• `--output`: Output GIF path
• `--sort`: Sort order: `name` (default), `mtime`, `natural`

---

Mode C: AI Image Sequence to GIF

Generate N image frames using AI (Gemini via banana MCP or FLUX.2) with progressive prompt changes, then assemble into a stop-motion or animated GIF.

Procedure

1. **Plan the sequence**: Determine what changes between frames.

• Example: "sunrise over mountains" -- 8 frames from dark blue to golden yellow
• Example: "flower blooming" -- 12 frames from bud to full bloom

2. **Generate frames** using progressive prompts:

**Option A: Gemini via banana MCP tool** (recommended for consistency):

For each frame i (0 to N-1):
  gemini_generate_image with prompt:
    "Frame {i+1} of {N}: [base description], [progressive change at stage i/N],
     consistent style, flat illustration, limited color palette, square format"

**Option B: FLUX.2 via image_generate.py** (local, no API cost):

~/.video-skill/bin/python3 ~/.claude/skills/claude-video/scripts/image_generate.py \
  --prompt "Frame {i} of {N}: [description with progressive change]" \
  --width 512 \
  --height 512 \
  --output /tmp/claude-gif/frames/frame_{i:04d}.png

3. **Assemble frames**:

~/.video-skill/bin/python3 ~/.claude/skills/claude-gif/scripts/gif_frames.py \
  --input-dir /tmp/claude-gif/frames/ \
  --fps 4 \
  --width 480 \
  --preset web \
  --output ~/Documents/gif_output/ai_sequence.gif

Low FPS (2-6) works best for AI image sequences since each frame is a distinct "scene".

Tips for AI Image Sequences

• **Consistency is hard**: AI models may vary style between frames. Mitigate by:
• Including strong style anchors in every prompt ("pixel art style", "watercolor style")
• Using the same seed if the tool supports it
• Keeping the composition simple and consistent
• **Frame count**: 6-12 frames is the sweet spot (more = more variation = less consistent)
• **Low FPS**: 2-6 fps gives a charming stop-motion look and hides inter-frame inconsistency

---

Mode D: Animated SVG to Transparent GIF

Convert an animated SV