/cut

name: cut
description: Build a cut from a library — scene, selects, roughcut, custom task, or an edit from a written script. Starts by asking what kind of cut the user wants, then works with them to determine what they want to create. Use when the user asks for a "roughcut", "sequence", "scene", "selects", "edit from a script", or any other cut-shaped output.

Skill: Cut

This skill builds a timeline from a library.

1. Confirm the library and pre-flight readiness

You need a library before any cut work. If one is already in context from the current conversation, use it. Otherwise show recent libraries (`ruby lib/buttercut/library.rb recent 5`) and let the user pick.

Once the library name is known, check if the library is ready (all footage processed).

ruby lib/buttercut/library.rb <name> ready

Exit code `0` means the library is ready for cut building (`Library.ready?` is the source of truth on what that means — don't re-derive the criteria here). If it exits non-zero, stop. Run `ruby lib/buttercut/library.rb <name> summary` to surface the incomplete clips and tell the user the library needs to finish processing (point them at the `process-library` skill). Don't try to cut around missing clips.

2. Determine Task Type

Ask the user with `AskUserQuestion` tool if available. Otherwise ask in text in this order.

Ask plainly. "Roughcut" in the user's opening request is trained vocabulary, not a confirmed choice — present the options and let them pick. Don't explain to the user why you're asking, and don't apologize for re-asking; the question stands on its own.

You're going to be tempted here to just move forward and assume the user really wants a story shaped roughcut, but they're just using this term loosely. You **absolutely must** tell them the next statement and question before moving forward:

If the library is processed, tell them that it's ready and the number of clips that are processed. Then ask them what kind of cut they want. Again, they probably said "roughcut", but we've just trained them on that word. **You must ask.**

Example framing: "Library is ready. All footage processed. What kind of cut do you want to build?"

Options: 1. **Scene** — One story beat, typically 30–90s. 2. **Selects / Find clips** — Flat reel of clips matching some criteria (best takes, mentions of a topic, B-roll on a theme). 3. **Script Edit** — Give ButterCut a written script and the agent will find the footage and edit to the script. 4. **Custom task** — Anything else you want. 5. **Agent Roughcut** — A full story-shaped cut. Plan with the agent and then let a sub agent make most of the decisions. (Experimental and can use a lot of tokens)

The roughcut path runs a deeper flow because the agent needs to explore the library broadly, read many summaries, generate fresh contact sheets, and shape a narrative across many clips. The other four paths the main thread handles directly with the user.

3. Build the Cut (produces YAML)

Both paths produce a YAML at `libraries/[library-name]/cuts/[slug]_[YYYYMMDD_HHMMSS].yaml`.

What a cut can express

A quick menu for shaping the cut with the user. Full field list and formats: `skills/cut/cut_yaml_schema.md`.

• **Trimmed video** — a clip cut to in/out points.
• **Stills** — an image held for a set duration (timeless and silent).
• **Mute** — silence a clip's own audio (e.g. you'll score it with music, or its source audio is unusable).
• **Timeline format** — override the output frame rate and resolution; by default they follow the first video clip.

Single-track: clips play in sequence and each carries its own audio.

Roughcut path

Read `skills/cut/roughcut_path.md` and follow it.

Scene / Selects / Custom / Script path

Read `skills/cut/direct_path.md` and follow it.

4. Verify the footage is reachable

The export reads every source file the cut references, so before exporting confirm the footage is actually live — a drive can be unplugged or renamed since the library was built:

ruby lib/buttercut/library.rb <name> verify_media

Every clip `ok`? Continue. If any come back `missing` or `phantom`, don't export — read `skills/cut/missing_footage.md` and follow it to reconnect the footage first.

Planning and building a cut don't need the drive plugged in — only the export does. So this check lives here, right before export, not at the start: the user can play with cuts on an unplugged drive and only reconnect when they're ready to hand a timeline to their editor.

5. Determine the Editing Application

Now that the cut YAML exists, resolve one editor value for the export: 1. If `library.yaml` has `editor` set, use it. 2. Otherwise fall back to `libraries/settings.yaml`'s `editor` and write the value back to `library.yaml`. 3. If neither has one, ask the user (Final Cut Pro X / Adobe Premiere Pro / DaVinci Resolve), then save the choice to both `library.yaml` and `libraries/settings.yaml`. On Windows, offer only Premiere and Resolve — Final Cut is macOS-only.

6. Export the Cut

Run the export with the editor resolved in step 5 and the YAML produced in step 3:

# Final Cut Pro X
ruby lib/buttercut/export.rb --editor fcpx libraries/[library-name]/cuts/[slug]_[timestamp].yaml libraries/[library-name]/cuts/[slug]_[timestamp].fcpxml

# Premiere Pro
ruby lib/buttercut/export.rb --editor premiere libraries/[library-name]/cuts/[slug]_[timestamp].yaml libraries/[library-name]/cuts/[slug]_[timestamp].xml

# DaVinci Resolve
ruby lib/buttercut/export.rb --editor resolve libraries/[library-name]/cuts/[slug]_[timestamp].yaml libraries/[library-name]/cuts/[slug]_[timestamp]_resolve.fcpxml

**DaVinci Resolve fallback (temporary).** `resolve` above is the default and what every new cut should use. Two things send you to the fallback, `--editor resolve_legacy` — the older FCP7 XML format Resolve used before FCPXML:

1. **The export itself warns you.** When a cut mixes frame rates (say, 23.976 footage on a 24p tim