Bashcut Agent Kit README

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

Code

.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:

python3 scripts/check_commands.py --reference ../bash-cut/docs/reference/commands.md
python3 -m unittest discover -s tests

tests/test_e2e_bashcut.py checks the skills' claims against a live BashCut on synthetic media with known answers (sync offsets, band shares, --focus framing, crop, ranged captions, the loop review). It opens its own project in a temporary folder and reopens yours afterwards; it skips when BashCut is not running or the open project has unsaved changes, and per test when the CLI lacks a command or no ready plugin provides the capability it needs. BASHCUT_CLI points it at a specific bashcut binary.

Pull requests that change skills/ must increase .claude-plugin/plugin.json's semantic version. The version check compares against the PR base; it never rewrites a contributor's branch. Claude Code caches an installed plugin per version, so an unchanged version keeps serving the old skills even after BashCut refreshes its copy. Codex links the skill folders and sees changes at once.

Releases and in-app updates

BashCut's Settings › Agents checks releases.json on main and offers newer kits as Download & Update (bashcut agent kit-check, bashcut agent kit-update). To publish one, merge the version bump, then push its tag:

git tag v0.0.2 && git push origin v0.0.2

The catalog entry's minAppVersion (the oldest BashCut whose commands the kit uses; older apps are not offered it) comes from the repository variable KIT_MIN_APP, 0.0.1 when it is unset: gh variable set KIT_MIN_APP --body 0.0.4.

.github/workflows/release.yml checks the skills, runs scripts/release.py to zip the committed kit files, signs the archive digest with the BashCut publisher key (repository secret BASHCUT_SIGNING_KEY, the same key as bashcut-plugins), attaches it to the GitHub Release and adds the version to releases.json. BashCut installs only archives whose SHA-256 and first-party signature match. python3 scripts/release.py builds the archive locally without signing.

License

MIT. See LICENSE.