BashCut agent kit
Editing skills for Claude Code and Codex that drive the BashCut
video editor. BashCut makes video editable by agents (CLI, MCP, undoable edits); this kit says how to edit
well: what to look at, where to cut, how to mix, which effect fits which moment.
Every edit goes through BashCut's own commands. The kit never pre-renders picture or sound; its scripts only
measure (grade.py: colour and LUT files) or fetch assets from official APIs (fetch_audio.py, fetch_stock.py,
fetch_font.py). The fetch_*.py files run the copies in BashCut's Online Resources plugin (bashcut.resources,
whose Online resources sheet uses the same scripts), so install it once: bashcut plugins install bashcut.resources.
Sound is measured by BashCut itself (audio measure, media sync).
Skills
| Skill | Use it for |
|---|
edit-workflow | The one engine for every edit: routing to a plugin recipe, ask-once intake, the quick path (the cut as one list, plan.cut: plan check without editing, then plan apply as one edit with captions, titles and ducking; batched calls; survey and draft audit in the bc:surveyor and bc:critic sub-agents on a cheaper model, media digest instead of whole transcripts; full path in FULL.md), 13 stages with a checklist backed by evidence (run append stage, run checklist), the user's workflow gates, strategy/draft/process audits, brief and plan (with the recipe's data) as project data, and the one skill to read per stage |
rough-cut | Selecting by quote (media resolve-range → selects set → selects place), never across a recording cue, the later take of a retake, padding and length ranges, a blind second pass, long → short with project derive |
review | The critic loop before export: pass/fail/incomplete, severities by what the viewer sees, 1–3 rounds, review verify before "fixed", review accept --reason, coverage in the report; the brief for the fresh critic of each audit (review packet --point strategy|draft|process) and the generic checks |
footage-survey | Inventory, contact sheets and shot descriptions before editing (media digest, media inventory, media frames --sheet, media describe); the surveyor brief (SURVEYOR.md); coverage, silent or broken clips, recording cues ("cut that", "take two", claps); camera ↔ screen sync (media sync) |
beat-cut | Cutting on the beat grid or on sentences, rhythm checked by measurement (review shots, review sync); punch-in reframes sized from each clip's zoom headroom |
audio-mix | The mix measured by role, then levels, fades, ducking, music choice, SFX and loudness per output; music and SFX found and downloaded with fetch_audio.py (Openverse music; Freesound SFX with FREESOUND_API_KEY, else Mixkit or Openverse) |
voiceover | Measured speaking rate and narration windows, text-to-speech lines that read right, checked against their text, placed, re-taken in place; dubbing |
captions-text | Captions from speech or a script, word timings, hook titles, place and chapter cards, text templates; fonts that draw the language (fetch_font.py: Fontsource search, whole files from Google Fonts) |
color-grade | Measured grading: probe, color measure, candidate looks and LUTs with ranges (grade.py measures and reports), check and back off; library looks |
effects | Which effect for which moment, made with native transitions, speed ramps, freeze, reframe |
visual-plan | What the viewer sees on every line of a talking video: one treatment per line (speaker, punch-in, own B-roll, stock, icon, text, designed graphic, generated, screen, nothing), anchored to a word, balanced over the video from the reference, researched, written as plan.visuals for the building skills; starts from the script beats' ON SCREEN notes when bashcut.vlog:hook-script wrote them |
motion-graphics | Designed graphics over footage (cards, counters, kinetic type, diagrams): whether a sentence needs one, anchoring to the payoff word, hold and density ranges; the graphic itself comes from a graphics.render plugin such as HyperFrames Graphics |
stock-images | Stock photos and video from Pixabay or Pexels (fetch_stock.py, keys from the environment) placed as illustration, never labelled on the video; Iconify icons as transparent PNG stickers; generated B-roll when a provider serves it |
style-study | Measuring a reference style and turning it into a memo, a library look and text presets |
library | Making a missing preset, effect, transition, look, sticker or sound; harvesting what to keep after an edit; fixing and pruning library items |
self-learn | Lessons (as cases with a check), preferences, facts and project skills in BashCut's knowledge; the user's corrections from the run log; folding repeats by occurrence; proposed kit changes |
setup | Installing the recommended plugins (at once while BashCut trusts plugins automatically, the default; otherwise with one approval in the app), then checking they work. Only runs when the user types /bc:setup (Codex: $bc-setup) |
Claude Code and Codex both show the skills under the plugin name: bc:audio-mix, bc:edit-workflow, …
Topic recipes (bashcut.vlog:plan, :travel, :hook-script, :publish, …) are not in this kit: they ship with
BashCut's Vlog plugin (bashcut-plugins) and load as plugin skills.
Kit 0.1.0 renamed them from bashcut:bashcut-<name>; BashCut's agent setup replaces the old bashcut plugin and
the old Codex links.
Requirements
- BashCut running (its MCP server talks to the open app), a version with
ui frame (BashCut PR #14).
- Claude Code or Codex.
- For the scripts:
ffmpeg and ffprobe; uv for grade.py (it installs numpy and Pillow on first run).
- Skills that use capabilities need the matching BashCut plugin: captions (
captions.transcribe), beats
(audio.beats, built in), loudness (audio.loudness, built in), voice (voice.synthesize, e.g. VieNeu TTS).
Install
Inside BashCut nothing is needed: BashCut ships the kit and loads it in its Claude and Codex tabs.
Settings › Agents (or bashcut agent setup claude|codex) also sets up Claude Code and Codex outside
BashCut from that copy, including configuration folders moved with CLAUDE_CONFIG_DIR or CODEX_HOME.
Claude Code
/plugin marketplace add dongnguyenvie/bashcut-agent-kit
/plugin install bc@bashcut-agent-kit
Skills appear as /bc:<name> (for example /bc:audio-mix), and the plugin starts BashCut's MCP server
(scripts/bashcut-mcp.sh finds bashcut-mcp in /Applications or ~/Applications; set BASHCUT_MCP to
override). To try a local checkout for one session: claude --plugin-dir /path/to/bashcut-agent-kit.
Codex
git clone https://github.com/dongnguyenvie/bashcut-agent-kit
sh bashcut-agent-kit/scripts/install-codex.sh # links skills as ~/.agents/skills/bc-<name>, adds the MCP server
sh bashcut-agent-kit/scripts/install-codex.sh --uninstall
Layout
.claude-plugin/plugin.json plugin "bc" (skills show as bc:<name> in Claude Code and Codex)
.claude-plugin/marketplace.json marketplace "bashcut-agent-kit"
.mcp.json BashCut MCP server for Claude Code
hooks/hooks.json Claude Code hooks (Codex has none): each bc:* skill read goes to BashCut's run log
(record-skill.sh); a user message that reads like a correction is logged as a
lesson candidate with one line of context (correction.sh, regexes only, silent
otherwise); a manual /compact with such corrections is held once (precompact.sh)
and the quotes come back after any compaction (after-compact.sh)
skills/*/SKILL.md the skills (Agent Skills format, shared by Claude Code and Codex)
skills/*/REFERENCE.md detail a skill reads on demand (kept out of SKILL.md's 250-line limit)
skills/*/SURVEYOR.md, CRITIC.md, sub-agent briefs (Codex gives them to its own sub-agent)
VOICE.md, GRAPHICS.md
agents/*.md Claude Code sub-agents bc:surveyor, bc:critic, bc:voice and bc:graphics (Sonnet),
generated from the briefs
scripts/bashcut-mcp.sh finds and starts bashcut-mcp
scripts/install-codex.sh Codex setup
skills/*/*.py asset and measurement scripts run with `uv run` (stdlib only, keys from the environment)
scripts/check.py checks every skill's frontmatter, size and referenced files, agents/ in sync, and
that this README's Skills table lists every skill
scripts/sync_agents.py writes agents/*.md from the briefs
Writing skills
- English instructions; trigger phrases in the description may be in any language users speak.
- Say what to do and why; leave command syntax to BashCut's own agent instructions.
- No personal presets, voices or download sources: those belong in a user's project memo.
- Only rules that were observed (a measurement, an error, a user's correction), with the number that proves it.
- Run
python3 scripts/check.py before committing.
Verification
CI runs skill checks, checker unit tests and explicit CLI example validation against the generated BashCut
command reference in reference/commands.md. Its source commit and sha256 are recorded in reference/source.json (CI fails when they do not match); it is
vended here because the app repository is private and the public kit's CI cannot check it out. Refresh both
files when adopting app command changes. In a sibling checkout, validate directly against the app with:
