| name | yt-chapters |
| description | Generate accurate YouTube chapters from a final edited video. Extracts audio with ffmpeg, transcribes it, then updates the video package description with real timestamps. Triggers on: generate chapters, update chapters, finalize description, chapters from video, update timestamps, post-edit description. |
Generate accurate YouTube chapters from the final edited video at $ARGUMENTS.
Workflow Context
Final step of the weekly content pipeline — runs post-edit when the editor delivers the final .mp4. Do NOT run this before filming or editing. After this, the description is ready to copy-paste into YouTube.
Flow
Step 1: Parse Input
From $ARGUMENTS, extract:
- Video path: The local
.mp4 file (required)
- Slug (optional):
--slug <video-slug> to identify the video package at ~/content/youtube/<slug>/
If no slug is provided:
- Check if the video filename or parent folder matches an existing
~/content/youtube/<slug>/ package
- If not, ask the user: "Which video package does this belong to?" and list existing packages from
~/content/youtube/
If the video path doesn't exist, ask the user for the correct path.
Step 2: Extract Audio
Extract the audio track from the video using ffmpeg:
ffmpeg -i "<video_path>" -vn -acodec libmp3lame -q:a 2 ~/content/transcripts/chapters_audio_<slug>.mp3 -y
This is faster and smaller than processing the full video file.
Step 3: Transcribe
Transcribe the extracted audio using the transcribe skill's script:
python3 ~/.claude/skills/transcribe/transcribe_video.py ~/content/transcripts/chapters_audio_<slug>.mp3
Read the resulting transcript file. It should contain timestamped segments.
Step 4: Identify Chapters
Analyze the transcript to identify natural chapter breaks. Look for:
- Topic transitions — When the speaker shifts to a new subject
- Section markers — Phrases like "next", "now let's", "moving on", "the first thing", "step one"
- Demo transitions — Shifts between talking and showing something
- Energy shifts — New introductions of concepts after a conclusion of the previous one
Generate 5-15 chapters depending on video length:
- Videos under 5 min: 3-5 chapters
- Videos 5-15 min: 5-10 chapters
- Videos 15+ min: 8-15 chapters
For each chapter:
- Timestamp in
MM:SS format (or H:MM:SS for videos over 1 hour)
- Title — Short, descriptive, 2-6 words
The first chapter MUST be 0:00 - Introduction (or a more specific hook title).
Step 5: Read Existing Description
Read ~/content/youtube/<slug>/description.md if it exists. Identify:
- Is there an existing chapters section with
[UPDATE] placeholders?
- What's the overall structure of the description?
Step 6: Present Chapters to User
Show the user the generated chapters:
0:00 - Introduction
0:45 - Setting Up the Project
2:12 - First Demo
...
Ask: "Do these chapters look right? Want to adjust any timestamps or titles?"
Step 7: Update Description
After the user approves (or after revisions):
If description.md exists with placeholder chapters:
- Replace the entire chapters section (the
[UPDATE] placeholders) with the real timestamps
If description.md exists without a chapters section:
- Add a chapters section in the appropriate location (after the main body, before the CTA/links). Do not add a tags or hashtag line to the description — tags belong in
tags.txt (YouTube tags field) only.
If no description.md exists:
- Create
~/content/youtube/<slug>/description.md with just the chapters section and a note to fill in the rest
Show the user the updated description and confirm the file was saved.
Step 8: Cleanup
Delete the temporary audio file:
rm ~/content/transcripts/chapters_audio_<slug>.mp3
Report what was done:
- Transcript location
- Updated description path
- Number of chapters generated
Rules
- Always extract audio first — don't try to transcribe the full video file directly (it's slower and larger)
- Chapters must start at
0:00 — YouTube requires this
- Chapter titles should be concise (2-6 words) — they appear in the progress bar
- Minimum 3 chapters for YouTube to recognize them as chapters
- Timestamps must be accurate to within ~5 seconds — round to clean numbers when the transition isn't instant
- Don't create chapters shorter than 10 seconds — YouTube may not display them
- When updating
description.md, preserve all existing content outside the chapters section
- Clean up the temporary mp3 after transcription
- If the transcription doesn't have clear timestamps, estimate based on word count (~150 words per minute of speech)
