yt-transcript

Quick start

Extract a transcript (saves two files under ./output/):

python ~/.claude/skills/yt-transcript/scripts/fetch.py "https://www.youtube.com/watch?v=VIDEO_ID"

Extract and apply an action:

python ~/.claude/skills/yt-transcript/scripts/fetch.py --action summarize "https://www.youtube.com/watch?v=VIDEO_ID"

On Windows PowerShell, expand the home path manually:

python "$HOME\.claude\skills\yt-transcript\scripts\fetch.py" --action summarize "https://www.youtube.com/watch?v=VIDEO_ID"

Run the script from the directory where the user wants the output/ folder; paths are relative to the current working directory and the folder is created if missing.

Actions

--action <id> (alias -a). Valid ids: summarize, bullets, criticize (alias critique), questions. The script does not call any LLM — you (the agent) produce the action output yourself. The script saves the transcript, then prints a final line:

ACTION_REQUEST {"action":"summarize","instruction":"...","transcript_file":"<abs .md>","output_file":"<abs .md>"}

What each action produces (the exact instruction rides in the JSON — follow it verbatim):

• summarize — 3-5 paragraph markdown summary, one-sentence TL;DR first.
• bullets — 8-15 key points as a markdown bullet list.
• criticize — per-claim critique (what's supported / weak / counter-evidence), H3 per claim.
• questions — 8-12 grouped follow-up questions.

Workflow

1. Confirm the user's intended working directory so ./output/ lands where they expect.
2. Run the script from that directory with the URL as a single quoted argument. Add --action <id> if the user asked to summarize / bullet / critique / generate questions.
3. Read the script's stdout — the first two lines are the saved transcript paths (.md, .txt).
4. If no action: report both transcript paths to the user. Done.
5. If an ACTION_REQUEST line is printed:
   • Read the transcript from transcript_file.
   • Apply the instruction to that transcript using your own reasoning (do not shell out to another model). Output clean markdown.
   • Write the result to output_file (e.g. output/<title>.summarize.md).
   • Report the transcript paths and the action output path to the user.

File contents

Transcript files (<title>.md / <title>.txt) contain:

1. The video title (H1 in the .md, plain in the .txt)
2. The canonical https://www.youtube.com/watch?v=<id> URL
3. The full transcript as one prose block

Action output (<title>.<action>.md) contains only the action result as markdown, written by you.

Requirements

• Python 3 on PATH (or set $PYTHON / $env:PYTHON).
• youtube-transcript-api: pip install youtube-transcript-api
• Network access (transcript API + YouTube's public oEmbed endpoint for the title).
• No API key — actions are performed by you, the agent, not by the script.

Edge cases

• Unknown action — script exits 1 with a JSON error listing valid actions, before any network call.
• No captions / video unavailable — script exits 1 with a JSON error line on stderr. Surface it; suggest verifying the video has captions.
• Title fetch fails — script falls back to the 11-char video ID as the filename rather than aborting.
• Filename safety — strips characters illegal on Windows (<>:"/\|?*), control chars, and excess whitespace; truncates to 150 chars.
• URL formats accepted — watch?v=<id>, youtu.be/<id>, /embed/<id>, /shorts/<id>, and raw 11-char video IDs.
• Name collisions — existing files at the same path are overwritten without prompt.