Video Merge
Merges multiple videos from a folder (sorted by filename) into one clip with a random xfade transition (0.5s) between each pair; freeze-pads so total duration equals the sum of sources. Exports 3840×2160 60fps H.265 Main10 40Mbps + AAC 320kbps. Use when the user wants video merge, concatenate videos, video concat, transition animation, xfade, join clips, or batch stitch clips with transitions.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Video Merge when an AI agent needs a reusable SKILL.md workflow for this job: Merges multiple videos from a folder (sorted by filename) into one clip with a random xfade transition (0.5s) between each pair; freeze-pads so total duration equals the sum of sources. Exports 3840×2160 60fps H.265 Main10 40Mbps + AAC 320kbps. Use when the user wants video merge, concatenate videos, video concat, transition animation, xfade, join clips, or batch stitch clips with transitions.
When not to use it
Skip Video Merge when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/video-merge # Save SKILL.md to ~/.claude/skills/video-merge/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/video-merge/SKILL.md. For a shared project, commit the folder at .claude/skills/video-merge/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Video Merge skill for this task: Use Video Merge when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 61/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Video Merge
Concatenate every video in a folder (filename sort) into **one** high-quality MP4. Between each pair, pick a **random** FFmpeg `xfade` transition (0.5s). Audio uses matching `acrossfade`.
**Duration is preserved:** each cut freeze-pads the outgoing clip by 0.5s (last frame + silence) before the overlap, so output length equals the sum of source clip durations (not shortened by transitions).
## Rules
When this skill applies, read and follow [skill-dependency-manager](../skill-dependency-manager.md) — run scripts as documented, install missing tools into `.dependency/`.
- Run `merge.py` through **`.dependency/python/python.exe`**. Never use host `python` / `ffmpeg`. - **Never overwrite sources.** Outputs go under `video-merge/`. - Use the bundled script — do not hand-write equivalent FFmpeg commands. - **Folder input only** — pass `--folder` with a directory of clips (top-level files; no recurse).
## Quick Start
```bash .dependency/python/python .ai/video-merge/merge.py --folder path/to/clips ```
Example:
``` assets/shots/ 01.mp4 02.mp4 03.mp4 → assets/shots/video-merge/shots.mp4 ```
## Output Spec (fixed)
| Setting | Value | |---------|-------| | Resolution | 3840×2160 (scale + letterbox pad) | | Frame rate | 60 fps | | Video | H.265 Main10 (`libx265`, `yuv420p10le`) @ **40 Mbps** | | Audio | AAC **320 kbps**, 48 kHz stereo | | Transition | **0.5 s**, random from the pool below (freeze-pad; duration preserved) | | Container | `.mp4` (`hvc1` tag) |
## Transition Pool (random per cut)
`fade` · `dissolve` · `wipeleft` · `wiperight` · `wipeup` · `wipedown` · `slideleft` · `slideright` · `circlecrop` · `pixelize` · `distance` · `radial` · `smoothleft` · `smoothright` · `circleopen` · `circleclose` · `diagtl` · `diagtr` · `hblur` · `zoomin`
Each cut independently samples one transition. Printed in the run log.
## Common Flags
`--folder` · `-o` / `--output`
```bash .dependency/python/python .ai/video-merge/merge.py --folder clips .dependency/python/python .ai/video-merge/merge.py --folder clips -o out/final.mp4 ```
**Never overwrite source files.** Input must be a folder (`--folder`), not a single video file. Only top-level videos in the folder (no recurse). Supported: `.mp4`, `.mkv`, `.mov`, `.avi`, `.webm`, `.wmv`, `.flv`, `.m4v`, `.mpeg`, `.mpg`, `.ts`, `.mts`, `.m2ts`, `.3gp`, `.ogv`.
## Agent Notes
1. Use the bundled script — do **not** hand-write `ffmpeg` xfade chains. 2. Transition duration is fixed at **0.5s** — no duration override flag. 3. Every clip **except the first** must be **longer than 0.5s** (incoming side of `xfade`). 4. Single file in the folder → re-encode to the output spec with no transition. 5. Many clips (4K10) auto-chunk (max 4 inputs per filtergraph) to avoid OOM; transitions stay correct across chunk boundaries. 6. Missing Python/FFmpeg → populate `.dependency/` per skill-dependency-manager, retry. 7. FFmpeg filter details: [reference.md](reference.md)
## Tests
From repo root:
```bash .dependency/python/python .ai/video-merge/test_merge.py ```
Manual CLI examples: [cli/video-merge.md](../../../cli/video-merge.md)
Intended uses
- Use Video Merge when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.