halfsize — Claude Code skill: video compression and setup
The halfsize Claude Code skill compresses videos to a target size and measures quality with VMAF and SSIM. It activates when a file must fit a platform limit or its quality loss needs measuring.
MIT ★ 116 updated 2026-11-15
npx skills add YKLovePython/halfsize --skill halfsize -a claude-codeWhat halfsize does
halfsize compresses video to a requested size with a local CLI. It calculates the bitrate, selects a resolution, encodes the file twice, then reports VMAF and SSIM scores. The video stays on the machine and is never uploaded.
A single command can process several files. The --no-downscale flag keeps the original resolution, while --no-audio removes the soundtrack. Use --dry-run to inspect the plan before encoding, or request JSON output. H.264 is the default; H.265 trades away some compatibility. FFmpeg is required. If its binary was not downloaded, repair the installation with npx halfsize@latest --fix and retry. Output files go beside their inputs.
What it helps with
- compress a video to an exact size limit
- fit a clip within Discord or Gmail file caps
- measure quality loss after compression
- process several videos with one command
Example prompts for the agent
- Compress
input.mp4to 25 MB and report its quality score. - Make
clip.mp4small enough to send through Discord. - Compare the compressed video's quality using VMAF and SSIM.
How to install halfsize
1Skills CLI (Vercel)
npx skills add YKLovePython/halfsize --skill halfsize -a claude-code2Manually: put the files in place
~/.claude/skills/halfsize/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/halfsize/
1Skills CLI (Vercel)
npx skills add YKLovePython/halfsize --skill halfsize -a codex2Manually: put the files in place
.agents/skills/halfsize/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add YKLovePython/halfsize --skill halfsize -a cursor2Manually: put the files in place
.cursor/skills/halfsize/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install YKLovePython/halfsize skills/halfsize2Manually: put the files in place
.github/skills/halfsize/SKILL.md1Skills CLI (Vercel)
npx skills add YKLovePython/halfsize --skill halfsize -a gemini-cli2Platform CLI
gemini skills install https://github.com/YKLovePython/halfsize --path skills/halfsizeManually: put the files in place
.devin/skills/halfsize/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about halfsize
How do I install halfsize in Claude Code?
Run npx skills add YKLovePython/halfsize --skill halfsize -a claude-code. The skill file is placed at ~/.claude/skills/halfsize/SKILL.md.
What does halfsize do?
It compresses videos locally with FFmpeg to a requested size, then measures quality using VMAF and SSIM. The video is not uploaded.
What does halfsize need to run?
FFmpeg is required. If its binary download fails, run npx halfsize@latest --fix and retry the command.
Source text
SKILL.md · MIT
---
name: halfsize
description: Compress a video to an exact target size (20 MB, 16 MB, 700k, ...) on the local machine with FFmpeg, then verify quality with VMAF/SSIM. Use when a user needs a video to fit a platform cap, asks to "make this smaller", or wants to know what a size cut costs in quality.
---
# halfsize
`halfsize` is a local CLI. It does the bitrate math, picks a resolution, encodes twice,
and reports the measured quality. It never uploads the file.
## When to use this
- "Make this fit in 25 MB" / "Discord won't take it" / "WeChat says the file is too big"
- "Compress this but don't ruin it" — run it and report VMAF instead of guessing
- "How small can this go?" — try a target and read the verdict
## Commands
```bash
# exact size
npx halfsize input.mp4 --to 25mb
# let a platform cap pick the size
npx halfsize input.mp4 --for discord
npx halfsize input.mp4 --for gmail # 18 MB, safe under the 25 MB message cap
npx halfsize input.mp4 --for outlook # 15 MB, safe under the 20 MB message cap
# several files, one command
npx halfsize a.mp4 b.mp4 c.mp4 --to 10mb
# smaller, at the cost of compatibility
npx halfsize input.mp4 --to 10mb --codec h265
# keep resolution, accept a worse ratio
npx halfsize input.mp4 --to 25mb --no-downscale
# no soundtrack
npx halfsize input.mp4 --to 10mb --no-audio
# inspect the plan without encoding
npx halfsize input.mp4 --to 25mb --dry-run --json
# machine-readable result (plan, accuracy, VMAF, SSIM)
npx halfsize input.mp4 --to 25mb --json
```
With more than one input, `--json` returns `{ "files": [ ... ] }`.
If `npx halfsize` is unavailable, use `npx github:YKLovePython/halfsize` with the same flags.
If a run fails with "FFmpeg was not found" (npm sometimes skips the binary download
behind a proxy), repair it in place, then retry the same command:
```bash
npx halfsize@latest --fix
```
## How to read the result
- `0.3% under target` — good; it deliberately aims slightly under hard caps
- `VMAF >= 90` — looks the same; `80-90` — slight softening; `< 70` — visible loss
- The JSON result includes `output.file`, `output.bytes`, `quality.vmaf`, `quality.ssim`,
`accuracy`, and `verdict`.
## Rules
- Do not upload the user's video anywhere, and do not suggest an online compressor as a first step.
- Do not promise "no quality loss". Report the measured VMAF/SSIM and the verdict.
- If the source is already smaller than the target, stop and tell the user instead of re-encoding.
- HDR sources (iPhone HLG, HDR10/PQ) are tone-mapped to SDR automatically. Do not warn about washed-out colors unless the user asks to keep HDR.
- If the target is below the minimum the duration can hold, the CLI exits with the smallest achievable size. Report that number and suggest a larger target or trimming, instead of rerunning with `--force`.
- Prefer H.264 unless the user asks for smaller files or accepts H.265 compatibility tradeoffs.
- Write the output next to the input unless the user asks for a specific `--out` path.
© YKLovePython · MIT · YKLovePython/halfsize