Video Compressor Agent Skill

Install the skill · Get the iPhone app · videocompression.app

I built this Agent Skill to let your agent compress video files for you. It checks what your machine can do, decides which files are worth compressing, encodes them to HEVC (or H.264), verifies every result and leaves the original untouched.

It works with Claude Code, Cursor, Codex and any agent that reads SKILL.md. It is one Python 3 file with no dependencies, it makes no network calls unless you ask for one, and it sends nothing anywhere.

Do you have videos on an iPhone or iPad? The skill cannot reach the Photos library of a phone, so I built Video Compressor for that. It compresses the videos on the device itself, and the presets in this skill follow the same preset logic.

What it does

• Decides before it encodes. Files that are already efficient are skipped, so a re-encode never makes a file bigger.
• Four presets (premium, high, balanced, max-saving) that follow the preset logic of my Video Compressor iPhone app.
• Size targets. Fit a clip under Discord, WhatsApp, email or Slack limits, or any number of megabytes, with bitrate math and two-pass encoding.
• Verifies every output. Duration, audio, frame rate, resolution and size are checked. A failed output is deleted and the original is never touched.
• Handles iPhone footage. HEVC is tagged hvc1, HDR stays HDR, rotation and metadata are kept, and Live Photo, Cinematic and spatial videos are skipped instead of damaged.
• Works without ffmpeg when it has to. It falls back to macOS avconvert, and without any encoder it prints exact commands for you to run.
• Batch mode. Point it at a folder.

Install

skills.sh

npx skills@latest add AvdLee/Video-Compression-Agent-Skill

Claude Code

/plugin marketplace add AvdLee/Video-Compression-Agent-Skill
/plugin install video-compression@video-compression-agent-skill

Cursor

Load the plugin from a local clone by placing it in ~/.cursor/plugins/local. Cursor reads .cursor-plugin/plugin.json and the portable plugin.json in this repository.

Codex and OpenAI agents

Use the skills.sh command above, or copy skills/video-compression into the folder your agent reads skills from. The Codex manifest is .codex-plugin/plugin.json.

Other clients (pi, Gemini CLI, Autohand Code, manual installation) are listed in INSTALLATION.md.

Requirements

ffmpeg and ffprobe give you every feature. Install them yourself with brew install ffmpeg (macOS), winget install Gyan.FFmpeg (Windows) or your Linux package manager. The skill never installs software on its own. Without them it uses macOS avconvert or switches to advisor mode. See How it decides.

Example prompts

• Compress this video so it is much smaller but still looks the same.
• Fit this screen recording under the Discord upload limit.
• Compress every video in this folder and tell me which ones were not worth compressing.
• Why is this 4K clip 2 GB? Check the bitrate and shrink it without visible quality loss.
• Convert this video to H.264 so it plays on an old TV.

How it decides

The skill runs five steps: doctor, probe, plan, run, verify.

Tier	What is available	What the skill does
1	Local machine with ffmpeg and ffprobe	Everything, including size targets and batches.
1b	macOS with only avconvert	Four fixed presets. No size targets.
2	ffmpeg without ffprobe (hosted sandbox)	Short clips only, with a reduced probe.
3	No encoder	Advisor mode: bitrate math and exact commands for macOS, Linux and Windows.

A file is skipped, with a reason, when:

• it is already efficient for the chosen preset (already_efficient, below_bitrate_floor, premium_efficient_hevc),
• the saving would be under 10% (no_meaningful_savings),
• it is a Live Photo video, Cinematic or spatial video, or Dolby Vision profile 5 (the format would not survive a normal encode),
• or the result would not be smaller than the original (not_smaller, the output is deleted).

The rules, what I mirrored from the app and what is the skill's own calibration are documented in presets.md.

Benchmark

I measured this on 2026-10-30 with tools/benchmark.py on 8 real iPhone 15 Pro clips (H.264, 1080p, about 205 seconds in total) and on the 8 balanced outputs of those clips (already compressed once). I ran it on a Mac with hevc_videotoolbox, and quality is VMAF on a centered crop of the first 15 seconds. Full tables and the method are in benchmark.md, raw numbers in benchmark-results.json.

Clips as recorded (8 clips)

Mode	Size saving, median (min to max)	VMAF, median
premium	41.1% (40.0% to 42.4%)	94.8
high	52.5% (51.1% to 52.8%)	93.2
balanced	60.7% (58.7% to 61.5%)	91.8
max-saving	85.7% (84.8% to 86.0%)	80.6
balanced with --software (libx265)	62.1% (55.9% to 65.4%)	95.3
plain ffmpeg -crf 23 with libx264	67.2% (48.2% to 77.8%)	93.7
plain ffmpeg -crf 23 with libx265	73.3% (48.1% to 84.1%)	94.1

Clips that were already compressed once (8 clips)

Mode	Result
premium and high	8 of 8 skipped as already efficient
balanced	Re-encoded, median saving 35.0%
plain ffmpeg -crf 23 with libx264	3 of 8 files got bigger
plain ffmpeg -crf 23 with libx265	1 of 8 files got bigger

On fresh iPhone footage a plain -crf 23 re-encode saves as much or more than the presets. I did not build a better encoder. What the skill adds is the decision about whether to encode at all, size targets, correct tags and metadata, HDR handling and verification. On other content (screen recordings, animation, small web videos) results will differ.

FAQ

How do I compress a video with an AI coding agent?

Install the Video Compressor skill, then ask your agent to compress the file. The agent runs doctor, probe, plan, run and verify, and writes <name>.compressed.mp4 next to the original.

Does Video Compressor change or delete my original video?

No. The original is never modified, moved or deleted. Outputs are written as <name>.compressed.mp4, and an existing file with that name is never overwritten.

Will compressing make my video worse?

The presets aim for a smaller file at a similar look, and the benchmark above lists the measured VMAF per preset. max-saving is the softest preset on purpose. If you want quality first, use premium or high.

Can it compress a video to fit under a size limit?

Yes. Use --target discord, --target whatsapp, --target email, --target slack or --target-mb N. The limits and their sources are in platform-limits.md.

Does it work without ffmpeg?

Partly. On macOS the Video Compressor skill can use the built-in avconvert with fixed presets. Without any encoder it switches to advisor mode and prints the exact commands. It will not install ffmpeg unless you pass --allow-download and agree to a pip download into the skill folder.

Does it work with HDR and Dolby Vision iPhone videos?

Yes, with limits. HDR clips keep 10-bit HEVC and their color tags. Dolby Vision profile 8 keeps the HLG base layer and drops the Dolby Vision metadata. Dolby Vision profile 5 is skipped. Details are in apple-video.md.

Does it send my videos anywhere?

No. Everything runs locally. I did not add any telemetry, and the only network use is the optional --allow-download.

Compress on your iPhone

The skill works on files on a computer. For videos on an iPhone or iPad, use the Video Compressor app I built. Product page and guides: videocompression.app.

About me

I'm Antoine van der Lee, an indie developer who has been building iOS apps since 2009. I worked on Videoland, the Dutch streaming service, so playback, codecs and storage are familiar ground. I have also been editing video for a long time and have made several podcasts, including Going Indie, which I host in audio and video.

You can read more on my About page.

Development

python3 -m unittest discover -s tests -v
python3 -m compileall skills/video-compression/scripts tests tools

The tests need ffmpeg and ffprobe and generate their own clips in a temporary folder. See CONTRIBUTING.md. GitHub topics and listing notes are in docs/github-topics.md.

License

MIT. See LICENSE.