Clips
Paths: ${CLAUDE_SKILL_DIR} means the folder containing this SKILL.md, and ${CLAUDE_SKILL_DIR}/../.. the editor folder (this repo's .claude/) two levels above it.
Read ${CLAUDE_SKILL_DIR}/../../PRINCIPLES.md first: the rules every video follows (asking, looking real, motion, story and framing, privacy, cost).
Every question to the user goes in the question box: call the AskUserQuestion tool (2-4 options, the recommended one first). Only in an agent without that tool, ask numbered questions in text.
One long video in. The best few short clips out, each a finished vertical edit in the user's style.
clips/<name>/
source.mp4 the long video (a symlink for a local file; never modify the original)
source.mp3, cover.jpg instead, for an audio-only podcast: its audio and the show's artwork
words.raw.json one transcript of the whole thing (never read it)
candidates.json every candidate with its features (never read it)
shortlist.md the top 8 that do not overlap, about 1,500 tokens: the only file you read
shortlist.json the same, for the page
picks.html the page the user picks from
edits/<name>-clip<N>/ one edit per chosen clip: source.mp4, words.raw.json (re-timed), clip.json
Run the scripts with python3 on Mac and Linux, py on Windows.
PY="${CLAUDE_SKILL_DIR}/../../lib/ai_editor/run.py"; python3 "$PY" below runs the editor's venv Python (py "$PY" on Windows).
If it is missing, run the setup skill first. K="${CLAUDE_SKILL_DIR}/scripts/clips.py",
C="${CLAUDE_SKILL_DIR}/../../skills/cut/scripts", S="${CLAUDE_SKILL_DIR}/../../skills/style-edit/scripts".
0. Ask, once
Read the profile and taste first (python3 "${CLAUDE_SKILL_DIR}/../../lib/ai_editor/profile.py" show,
python3 "${CLAUDE_SKILL_DIR}/../../skills/taste/scripts/taste.py" show). No profile yet: run the
start skill's style intake first, so the clips come out in the user's look.
Then one question box call, the recommended option first:
| question | options |
|---|---|
| How many clips? | 3 (Recommended) / 5 / 1 |
| How long should each be? | 20-40 s (Recommended) / 40-60 s / 60-90 s |
| How many people talk in it? | one (Recommended) / two (a podcast or interview) |
Skip any the user already answered. These replace the cut skill's "cut first or everything at once" question: clips run straight through, and the user approves the picks and the stills sheets.
1. The video
A local file (a hard link on the same drive, else a symlink, a copy only as the last resort):
python3 "${CLAUDE_SKILL_DIR}/../../skills/clips/scripts/clips.py" link "<absolute path>" clips/<name>
A link:
python3 "${CLAUDE_SKILL_DIR}/../../lib/ai_editor/links.py" fetch "<url>" clips/<name> --max-height 1080
It uses the venv's yt-dlp (setup installs it there, not on the PATH), caps the download at 1080p (a
1080x1920 clip needs no 4K; a 20-minute talk at 4K is several GB) and prints the file path:
clips/<name>/source.mp4. Exit 3: the site wants a login (YouTube's "confirm you're not a bot").
Ask in the question box before re-running with --cookies-from-browser chrome (or their browser).
A podcast (RSS feed or Apple Podcasts show link): route lists its newest episodes as ask options; ask
which one in the question box (newest first), then fetch "<option url>" clips/<option name> --direct --cover "<option image>":
the audio lands as source.mp3 (or its own extension) and the show's artwork as cover.jpg.
Only download what the user has the right to reuse: their own video, or one
they have permission for. Say so once if the link is someone else's.
2. Transcribe once
python3 "$PY" "$C/transcribe.py" clips/<name>/source.mp4 clips/<name>/words.raw.json # the file fetch printed: source.mp3 for audio
Say the time first: Whisper takes 1-4 minutes per 3 minutes of video on a laptop (free), Scribe about 20 s for a 13-minute video. Same engines as the cut skill. Scribe adds laughter and other audio events, which the score uses. Every clip reuses this transcript: nothing is transcribed twice.
3. Candidates and the shortlist
python3 "$K" candidates clips/<name> --min 20 --max 40 [--speakers 2] [--style creator-teardowns/<handle>/style.json]
Pass the length the user picked. --style is the profile's first creator: the "what works" moves
measured there are listed in the shortlist. Code splits the transcript into sentences and makes every run of
whole sentences inside the length a candidate (never starting on "Mm-hmm" or ending mid-word),
measures each, ranks them by the features, and writes shortlist.md.
Read shortlist.md only. Each entry has the hook, the opening words of every middle sentence, the
last sentence and the measured features. Judge each entry on four questions: does the hook work
alone, can a stranger follow it, does it pay off, is there a concrete claim, number or story.
Never read words.raw.json or candidates.json. Pick the user's number of clips from the
shortlist, best first. Drop, whatever the score:
- an ad read, a sponsor segment, an intro or a sign-off;
- a hook that leans on earlier context ("as I said", "that's why", "this one");
- a clip whose point is a dated claim ("at the time I'm recording this, it's number 40") when the claim has since changed: a live capture of today's page would contradict it.
4. The picks page, then the question box
python3 "$K" page clips/<name> --recommend c12,c40,c7
open clips/<name>/picks.html # Windows: start "" ..., Linux: xdg-open ...
One page: every shortlisted clip with a 360 px preview, its transcript (the hook in bold), the score breakdown and the measured features, your picks marked. Then ask in the question box (multi-select): your picks first, each labelled with its time and its hook, plus "a different one from the page". Wait for the answer.
5. Each chosen clip
python3 "$K" trim clips/<name> c12 c40 c7 # -> edits/<name>-clip1, -clip2, -clip3
Each edit folder gets source.mp4 (frame-accurate, padded without catching the next word) and
words.raw.json re-timed to it. An audio-only source (source.mp3) has no picture: trim makes each
clip's source.mp4 its audio over the podcast's own cover (the cover blurred and dimmed to fill 1080x1920,
the sharp cover above the captions; no artwork: black), and clip.json says audio_only. With a cover, the
render moves it: a slow push on the cover, the ground drifting against it, a small punch on each sentence start. For those,
don't ask a layout: overlay, reframe no, no cutout, captions on (profile.py style keeps them on). Say once
that each clip is the audio over the show's cover with the speaker's words as captions. Before the clips run, settle music once for all of them
(style-edit references/plan.md "Music"; the style decides unless the user set sound.music).
All clips at once (Claude Code, or any agent with subagents): launch one clip-editor agent
(clip-editor) per clip, all in one message so they run at the same time. Give each
EDIT (the clip's folder, absolute), ROOT (${CLAUDE_SKILL_DIR}/../..), the PY line, and the answers:
aspect, layout, music, the transcription engine, and reframe yes (a wide source, unless the platform is
YouTube) or no, and whether the source has captions burned in. Each takes its clip through the cut and style-edit to the stills sheet and returns a
short JSON: status, cut_s, verify, cut_page, sheet, error. Merge those; never open a clip's
transcript or paper edit. Then run the stills-critic agent on every ready clip's sheet, again all in
one message, and fix what they fail (plan and stills again for that clip). A failed clip: run it by
hand as below.
One at a time (no subagents), for each clip in order:
- Vertical from a wide video:
python3 "$PY" "$K" reframe edits/<name>-clip<N>crops to 9:16 with the crop following the speaker's head shot by shot (camera cuts found with ffmpeg). Skip it when the profile's platform is YouTube or the source is already vertical. - Cut: the cut skill from its step 2 (
retakes.py propose): the transcript is already there. Then build, render, verify and the cut page, as that skill says. Music under the voice is measured per file:build_timeline.pytrims only between words there. - Style:
python3 "${CLAUDE_SKILL_DIR}/../../lib/ai_editor/profile.py" style edits/<name>-clip<N>, then the style-edit skill from its step 2. If the source already has captions burned in, set"captions": {"present": false}in that edit'sstyle.json, or the captions stack.
Either way, open every clip's cut-check.html and show all the stills sheets together for one
approval, ask the render question once for all of them, and render. After approval, run
python3 "${CLAUDE_SKILL_DIR}/../../skills/cut/scripts/judge_cut.py" score on each clip's folder (cut
references/judge.md). Hand the renders over on one
review page, each clip a tab (start with clip 1, alt for the rest, folder clips/<name>; see
${CLAUDE_SKILL_DIR}/../../skills/style-edit/references/review.md), then serve and wait in the background.
If a script stops
| message | do |
|---|---|
no run of whole sentences lasts <lo>-<hi> s | ask in the question box for a wider length, run candidates again |
no candidate <id> | use an id from shortlist.md |
links.py fetch exit 3 (a login or "confirm you're not a bot") | ask before re-running with --cookies-from-browser <browser> |
| any cut or style-edit message | that skill's "If a script stops" table |
Rules
- Every word, number and name on screen comes from that clip's own words. Nothing from the rest of the video, and nothing the speaker did not say.
- No AI-tell looks:
${CLAUDE_SKILL_DIR}/../../skills/style-edit/references/ai-tells.mdapplies to every clip. - A close-up podcast frame has no free space: no card or logo goes over the head. Fewer visuals is right; captions and zooms carry it.
- Never cut a clip mid-sentence. Shorter or longer than asked beats a broken thought.
Cost per long video
Measured on a 13-minute two-person podcast and a 12-minute talking-head video (2026-10):
- Transcription: Scribe took 16-18 s; Whisper is free and slower. Once per long video.
- Candidates and features: 4-6 s of code, $0.
- Claude reads
shortlist.md(about 1,500 tokens), never the transcript (about 20,000). - The picks page: 30-40 s of ffmpeg for 8 previews, 7-9 MB.
- Each clip then costs what one cut and one style edit cost.
Self-check
python3 "$K" demo
Files
scripts/clips.py: candidates, page, trim, reframe and the offline demo (synthetic transcript). Stdlib only, exceptreframe(OpenCV, through the venv).${CLAUDE_SKILL_DIR}/../../agents/clip-editor.md: one clip through the cut and style-edit to its stills sheet.