agentleFS
godot-fungodot-fun/gai/.agents/skills/video-compress-to-size/SKILL.md

video-compress-to-size

Skill210 starsChanged 2 days agoMITView on GitHub

Compresses a single video file to stay under a user-specified max file size using FFmpeg. Prefers GPU encoders (NVENC / AMF / QSV) with VBR bitrate targeting; falls back to CPU two-pass H.264/HEVC. Use when the user wants to compress video, reduce video file size, shrink MP4/MKV/MOV under N MB, GPU encode, NVENC compress, or re-encode a clip to a size limit.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When this skill applies, read and follow dependency-manager — run scripts as documented, install missing tools into .dependency/.

    line 14
  2. Very specific:

    Run compress.py through .dependency/python/python.exe.

    line 16
  3. Distinctive:

    Use the bundled script — do not hand-write equivalent FFmpeg commands.

    line 18
  4. Very specific:

    Use the bundled script, not hand-written ffmpeg commands.

    line 83
  5. Very specific:

    Always pass --max-size from the user (ask if missing).

    line 84
  6. Distinctive:

    Do not downscale or change fps unless the user asks.

    line 86

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Video Compress To Size

Re-encode a supported video so the output is at or under a given max file size.

Default: probe and use a GPU encoder when available (NVIDIA NVENC → AMD AMF → Intel QSV), single-pass VBR. If no GPU works, fall back to CPU two-pass (libx264 / libx265).

Rules

When this skill applies, read and follow dependency-manager — run scripts as documented, install missing tools into .dependency/.

  • Run compress.py through .dependency/python/python.exe. Never use host python / ffmpeg.
  • Never overwrite sources. Outputs go under video-compress-to-size/.
  • Use the bundled script — do not hand-write equivalent FFmpeg commands.
  • One file per run — pass --video with a single file; repeat for each clip in a batch.

Quick Start

.dependency/python/python .ai/video-compress-to-size/compress.py --video path/to/clip.mp4 --max-size 50MB

Bare numbers mean MB (--max-size 50 ≡ 50MB):

.dependency/python/python .ai/video-compress-to-size/compress.py --video assets/intro.mp4 --max-size 50

Example:

assets/video/intro.mp4
  → assets/video/video-compress-to-size/intro.mp4

Force CPU (slow, more precise two-pass):

.dependency/python/python .ai/video-compress-to-size/compress.py --video clip.mp4 --max-size 50MB --cpu

Size Syntax

InputMeaning
50 / 50MB / 50M50 mebibytes (1024² bytes)
500KB / 500K500 kibibytes
1GB / 1G1 gibibyte
52428800Bexact bytes

--max-size is required.

Format Defaults

SettingDefaultNotes
EncoderGPU firsth264_nvenc → h264_amf → h264_qsv → libx264
HEVC--hevcSame order with hevc_* / libx265
Container.mp4Always MP4
AudioAAC 128kLowered automatically on tiny budgets
PresetmediumMapped (e.g. NVENC p4); override with --preset
Already under limitSkipped[skip] … (already under limit)
Safety marginGPU ~90% / CPU ~92%Headroom for mux / VBR overshoot

Common Flags

--video · --max-size · -o / --output · --audio-bitrate · --preset · --hevc · --cpu

Custom output path:

.dependency/python/python .ai/video-compress-to-size/compress.py --video clip.mp4 --max-size 50MB -o out/clip.mp4

Never overwrite source files. Input must be a single video file (--video), not a directory. Supported inputs: .mp4, .mkv, .mov, .avi, .webm, .wmv, .flv, .m4v, .mpeg, .mpg, .ts, .mts, .m2ts, .3gp, .ogv.

Agent Notes

  1. Use the bundled script, not hand-written ffmpeg commands.
  2. Always pass --max-size from the user (ask if missing). Prefer their unit wording; bare numbers are MB.
  3. Prefer GPU — do not pass --cpu unless the user asks or GPU encode fails.
  4. Do not downscale or change fps unless the user asks.
  5. Sources already ≤ max size are skipped.
  6. Tell the user where video-compress-to-size/ files are; they swap assets manually when ready.
  7. Missing Python/FFmpeg → populate .dependency/ per dependency-manager, retry same command.
  8. Pipeline details: reference.md

Tests

From repo root:

.dependency/python/python .ai/video-compress-to-size/test_compress.py

Manual CLI examples: cli/video-compress-to-size.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.