agentleFS
tyler-berggrentyler-berggren/tb-claude-kit/.claude/skills/video-editor/SKILL.md

video-editor

Skill2 starsChanged 5 days agoMITView on GitHub

Edit video via Palmier Pro MCP — mlx-whisper transcribe, script review, timeline cuts, fades, captions, cleanup. Takes a video file path or "apply" to execute a reviewed script.

  • Installs packages

19 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. 0 are common, 8 are distinctive, and 10 are very specific to this project.

  • 0

    Common

    Most of the 12 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Palmier Pro: must be running with its MCP server connected (palmier-pro MCP)

    line 13
  2. Distinctive:

    Python 3: must be available (mlx-whisper installs into a cached venv)

    line 14
  3. Very specific:

    Call get_timeline to verify Palmier MCP is connected and the video is on the timeline.

    line 28
  4. Very specific:

    Ask the user for a project name (kebab-case, e.g., launch-walkthrough-short).

    line 29
  5. Distinctive:

    Run mlx-whisper with word-level timestamps on the source video:

    line 54
  6. Distinctive:

    Start frame and end frame (seconds × fps)

    line 80
  7. Very specific:

    Create $PROJECT_DIR/script.md — the editable script the user reviews before any cuts happen.

    line 92
  8. Distinctive:

    To build the initial script: Use the sentence index to select which sentences tell the story.

    line 113
  9. Distinctive:

    Prefer sentences that end with large gaps (400ms+) — these are natural chapter boundaries

    line 116
  10. Distinctive:

    Keep: value propositions, key demonstrations, payoff moments, the narrative arc

    line 118
  11. Distinctive:

    The script is the contract: No edits touch the timeline until the user approves.

    line 130
  12. Very specific:

    Look for the most recently modified script.md in cowork/video/*/.

    line 138
  13. Distinctive:

    Add the range from last keep-range end to total_frames

    line 160
  14. Very specific:

    Call get_timeline to confirm the timeline has a single video clip and single audio clip (the original, unedited state).

    line 164
  15. Very specific:

    Call ripple_delete_ranges with trackIndex: 1 (audio track, A1), units: "frames", and all delete ranges.

    line 168
  16. Very specific:

    After cutting, call get_timeline to get the new clip IDs for both video and audio tracks.

    line 172
  17. Very specific:

    Call get_timeline to read all caption clips from the caption track's captionGroups.

    line 204
  18. Very specific:

    If .claude/kit.json has a rules."video-editor" entry, read it and apply it as an additional instruction for this skill.

    line 275

“Common” is measured: kept by at least 6 in 10 of the 12 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Video Editor

Transcript-based video editing via Palmier Pro MCP. Transcribes with mlx-whisper for accurate word-level timestamps, generates a reviewable script, then executes cuts, fades, and captions.

Prerequisites

  • Palmier Pro must be running with its MCP server connected (palmier-pro MCP)
  • Python 3 must be available (mlx-whisper installs into a cached venv)
  • Source video must be imported into Palmier and on the timeline

Dispatch

  • <path-to-video.mp4> — Start a new edit: transcribe → generate script → stop for review
  • apply — Apply the reviewed script: cuts → fades → captions → cleanup
  • cleanup — Re-run caption cleanup only (after manual caption edits)

Phase 1–2: Transcribe + Script (on file path input)

Step 1 — Validate environment

  1. Confirm the source video file exists.
  2. Call get_timeline to verify Palmier MCP is connected and the video is on the timeline. Note the fps, total frames, and media ref.
  3. Ask the user for a project name (kebab-case, e.g., launch-walkthrough-short). Create cowork/video/<project-name>/ as the output directory.
  4. Store the project state:
    • PROJECT_DIR = cowork/video/<project-name>/
    • SOURCE_PATH = the input video path
    • FPS = timeline fps (typically 60)

Step 2 — Set up mlx-whisper

The venv is cached across sessions. Check if it exists, create if not:

VENV_DIR="$SCRATCHPAD_DIR/whisperx-env"
if [ ! -f "$VENV_DIR/bin/activate" ]; then
  python3 -m venv "$VENV_DIR"
  source "$VENV_DIR/bin/activate"
  pip install mlx-whisper
else
  source "$VENV_DIR/bin/activate"
fi

Where $SCRATCHPAD_DIR is the session's scratchpad directory.

Step 3 — Transcribe with mlx-whisper

Run mlx-whisper with word-level timestamps on the source video:

import mlx_whisper, json

result = mlx_whisper.transcribe(
    "<SOURCE_PATH>",
    path_or_hf_repo="mlx-community/whisper-large-v3-turbo",
    word_timestamps=True,
    language="en",
)

# Extract word-level data
words = [{"text": w["word"].strip(), "start": w["start"], "end": w["end"]}
         for seg in result["segments"] for w in seg.get("words", [])]

Save the raw transcript to $PROJECT_DIR/whisper-transcript.json.

Why mlx-whisper instead of Palmier's built-in transcription: Palmier's on-device transcription reports 0ms gaps between adjacent words — the timestamps touch with no silence represented. mlx-whisper with large-v3-turbo captures real silence gaps (100ms–3000ms+) between phrases, which is essential for identifying safe cut points.

Step 4 — Build sentence index

Parse the word-level transcript into sentences (splitting on ., ?, !). For each sentence, record:

  • Sentence number (S001, S002, ...)
  • Start frame and end frame (seconds × fps)
  • Full text
  • Gap to next sentence in milliseconds

Save to $PROJECT_DIR/sentences.txt in this format:

S001 [0:00.0] (1.2s) w0-2 f0-70 [gap:320ms]
  Hey, I'm Tyler.

Step 5 — Generate the script

Create $PROJECT_DIR/script.md — the editable script the user reviews before any cuts happen.

Format:

# <Project Name> — Edit Script

> Source: `<source path>`
> Generated: <date>
> Sentence index: sentences.txt

---

## Scene 1: <label>
**Sentences:** S001–S005 | **Source:** 0:00–0:33 (33s)

> <full text of kept sentences>

## Scene 2: <label>
...

To build the initial script: Use the sentence index to select which sentences tell the story. Group consecutive sentences into scenes with descriptive labels. Every scene must start and end on a complete sentence boundary — never mid-sentence.

Rules for scene selection:

  • Prefer sentences that end with large gaps (400ms+) — these are natural chapter boundaries
  • Skip filler content: setup/waiting time, error debugging, consent dialogs, OAuth flows, detailed UI walkthroughs
  • Keep: value propositions, key demonstrations, payoff moments, the narrative arc
  • Target duration: whatever the user specifies (default 3–5 minutes for social, 5–8 for YouTube)

Step 6 — Stop for review

Present the script summary to the user:

  • Total duration estimate
  • Number of scenes
  • Compression ratio (original → cut)

Tell the user: "Review and edit <PROJECT_DIR>/script.md. You can add/remove scenes, change sentence ranges, or add notes. When ready, run /video-editor apply to execute the cuts."

The script is the contract. No edits touch the timeline until the user approves.


Phase 3–4: Apply (on "apply" input)

Step 7 — Find the active project

Look for the most recently modified script.md in cowork/video/*/. Confirm with the user which project to apply.

Load:

  • script.md — the reviewed script
  • whisper-transcript.json — word-level timestamps
  • sentences.txt — sentence index (for reference)

Step 8 — Parse script into frame ranges

For each scene in the script, extract the sentence range (e.g., S001–S005). Look up each sentence's start and end frames from the whisper transcript data.

Padding rules (from research — see cowork/research/060):

  • Lead: 5 frames (83ms) before the first sentence's first word
  • Tail: variable, up to 18 frames (300ms) after the last sentence's last word
  • Tail is capped at: min(300ms, gap_to_next_word - 50ms safety margin)
  • For the first scene: no lead padding (start at frame 0 if scene starts there)
  • For the last scene: no tail cap needed

Computing delete ranges:

  1. Build keep-ranges from the parsed scenes (with padding)
  2. Merge keep-ranges that overlap or are within 10 frames of each other
  3. Invert: everything between keep-ranges becomes a delete range
  4. Add the range from last keep-range end to total_frames

Step 9 — Verify the timeline is clean

Call get_timeline to confirm the timeline has a single video clip and single audio clip (the original, unedited state). If edits are already present, warn the user and ask them to undo to the original before proceeding.

Step 10 — Execute cuts

Call ripple_delete_ranges with trackIndex: 1 (audio track, A1), units: "frames", and all delete ranges. The tool handles linked video/audio sync automatically.

Step 11 — Apply fades

After cutting, call get_timeline to get the new clip IDs for both video and audio tracks.

Apply opacity keyframes to every video clip:

  • First clip: fade-out only (4 frames at end)
  • Last clip: fade-in only (8 frames at start)
  • Middle clips: fade-in 8 frames + fade-out 4 frames
  • Interpolation: "linear"

Apply volume keyframes to every audio clip:

  • First clip: fade-out only (6 frames at end)
  • Last clip: fade-in only (4 frames at start)
  • Middle clips: fade-in 4 frames + fade-out 6 frames
  • Interpolation: "linear"

Why separate video and audio fades: Video fades (opacity) create visual transitions between scenes — slightly longer for a smooth look. Audio fades (volume) prevent clicks and pops at cut points — shorter, just enough to eliminate artifacts. These are independent concerns with different optimal durations.

Step 12 — Add captions

Call add_captions with:

  • fontSize: 52
  • fontName: "Helvetica-Bold"
  • color: "#FFFFFF"
  • centerY: 0.88
  • textCase: "auto"

Step 13 — Caption cleanup

Load cowork/video/caption-dictionary.json — a project-owned file. The kit ships an empty template; each project fills in its own brand terms, transcription corrections, and capitalization. It lives outside the skill folder because the skill directory is shared across projects (symlinked in outside-repo mode), and this data must not be.

Call get_timeline to read all caption clips from the caption track's captionGroups.

For each caption clip, apply fixes in order:

  1. Replacements — exact phrase substitution (e.g., "mug.org" → "mug.work"). Use set_clip_properties with content to update.
  2. Capitalize — for each word in the capitalize list, find caption clips containing that word in any case and fix to the specified case. Only match whole words (e.g., "mug" → "Mug" but not "smuggle"). Use set_clip_properties.
  3. Remove fillers — find caption clips whose entire text matches a filler entry (e.g., "uh," or "um,"). Remove them with remove_clips.

Report the fixes applied: N replacements, N capitalizations, N fillers removed.

Step 14 — Report

Present the final result:

  • Duration (original → cut)
  • Number of clips, scenes
  • Fades applied (video + audio)
  • Captions added and cleaned
  • Remind: "Play through in Palmier to verify. Any manual adjustments can be made directly in the editor."

Cleanup-only mode (on "cleanup" input)

Re-runs Step 13 only — useful after manual caption edits in Palmier. Reads the current timeline captions and applies the dictionary fixes again.


Reference

Fade defaults

PropertyFade-inFade-outApplies to
Opacity8 frames (133ms)4 frames (67ms)Video clips
Volume4 frames (67ms)6 frames (100ms)Audio clips

Caption style defaults

PropertyValue
FontHelvetica-Bold
Size52pt
Color#FFFFFF
PositioncenterY 0.88 (near bottom)
Caseauto

Research backing

Full analysis in cowork/research/060_2026-06-29_ai-agent-video-editing-transcript-best-practices.md:

  • Silence gap classification: ≥400ms clean cut, 150-400ms cautious, <150ms never
  • 0.2s padding is community-validated sweet spot
  • 600ms most natural pause duration (PMC/NIH linguistics research)
  • 4-10ms audio crossfade prevents clicks (Punch Track)
  • Sentence boundaries > silence boundaries for cut points
  • mlx-whisper large-v3-turbo for accurate word timestamps on Apple Silicon

Palmier MCP tools used

  • get_timeline — read timeline state
  • get_media — verify media assets
  • get_transcript — read post-edit transcript (verification)
  • ripple_delete_ranges — execute cuts
  • set_keyframes — opacity and volume fades
  • add_captions — auto-caption from audio
  • set_clip_properties — fix caption text
  • remove_clips — delete filler captions
  • add_clips — add segments to timeline
  • add_texts — add manual caption clips

Project overrides

If .claude/kit.json has a rules."video-editor" entry, read it and apply it as an additional instruction for this skill. Absent file or key means no overrides — that is the normal case.

jq -r '.rules."video-editor" // empty' .claude/kit.json 2>/dev/null

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.