/youtube-notes

name: youtube-notes
description: >-
  Pull captions from a YouTube video and turn them into chapter-aligned notes
  where every claim carries a clickable timestamp. Use this whenever a
  youtube.com or youtu.be link appears, including a bare pasted link with no
  instructions attached, and whenever the user wants to summarize, digest,
  triage, or take notes on a video, talk, lecture, keynote, podcast, or
  interview: "is this worth watching", "TL;DR this talk", "what do they say
  about X", "find the part where they discuss Y", "save this to my notes",
  "get me the transcript". Prefer this over generic web fetching or page
  readers for YouTube links, because the page HTML carries no transcript. Not
  for downloading video or audio files, and not for local media.

YouTube Notes

Turn a video into something citable. The bundled script does the mechanical work — fetching captions, aligning them to the uploader's chapters, merging caption slivers into readable blocks — so your job is synthesis and judgment.

Fetch

One TypeScript file, run directly by Node with no build step. The `--help` output is the authoritative flag reference:

node ${CLAUDE_PLUGIN_ROOT}/skills/youtube-notes/scripts/fetch_video.ts --help

It shells out to `uvx` for `youtube-transcript-api` (captions) and `yt-dlp` (metadata, chapters). Both run on demand; nothing is installed globally. If `uvx` is missing the script exits 2 and tells the user to `brew install uv`.

The transcript is cached, so re-running is free

The first fetch for a video is cached by id. Every later call for that video reads from disk and touches no network: 35s becomes 0.06s, and switching modes or pulling different chapters costs nothing.

This shapes how to work. Do not ration calls to avoid refetching, because after the first one there is no refetch. Pull `triage` to see the shape, then pull the chapters you actually need, then pull different ones when the next question lands. The only real budget is context, not network.

It is also the main defense against rate limiting, which is the failure mode this skill hits most. A request you never make cannot be throttled.

`--refresh` forces a refetch, which you need only if a video's captions were genuinely republished. `--no-cache` skips it entirely.

The main use: answering questions about a video

Most requests here are conversational. Someone wants to interrogate a video, not receive a document. Expect several questions across a conversation about one video.

Load once, properly, then answer from what you have:

1. Pull `--mode triage` to see the chapter map and size. 2. For a short or medium video, pull `--mode full` and keep it in context. Every follow-up is then answered without another call. 3. For something multi-hour, pull the chapters that bear on the question with `--chapters`, and pull more as the conversation moves. Cached, so cheap.

Answer with the deep links inline so the user can jump to the source. When the video does not address something, say so plainly rather than reaching for an adjacent passage.

Resist turning every question into a digest. If someone asks what the speaker thinks about X, answer that, cite it, and stop.

Mode by intent

| User intent | Mode | | --------------------------------------------------------------- | ------------------------------------------- | | "is this worth watching", "what's this about", bare pasted link | `triage` | | "summarize", "take notes", "digest this", "save to my notes" | `full` | | a question about the content, or a conversation about the video | `triage`, then `full` (or `--chapters <n>`) | | "give me the transcript" | `transcript` |

node ${CLAUDE_PLUGIN_ROOT}/skills/youtube-notes/scripts/fetch_video.ts "<url>" --mode triage

Long videos

Chapter indices are stable across calls, so an index from triage is safe to reuse later. A 3h45m podcast is ~75k tokens in `full` and ~2k in `triage`, so target chapters rather than loading everything:

node ${CLAUDE_PLUGIN_ROOT}/skills/youtube-notes/scripts/fetch_video.ts "<url>" \
  --mode full --chapters 3,7 --out /tmp/video.json

The script prints an estimated token count to stderr and warns when output is large. Above roughly 25k tokens, write to `--out` and read the file back rather than piping it through stdout.

When captions fail

Two failures, one remedy:

• **Exit 4, rate limited.** YouTube throttles the caption endpoint per IP. It is

transient and affects only captions; metadata, chapters, and the audio stream keep working.

• **Exit 3, no captions published.** Permanent for that video.

Both are answered by `--whisper-fallback`, which downloads the audio and transcribes it locally. It works during a block because the media CDN is not subject to the caption quota. Verified: `youtube-transcript-api`, `yt-dlp` subtitles, and `curl` with a real browser User-Agent all get 429 on the caption endpoint while audio downloads at full speed.

Ask before using it on the first video of a session. It costs a one-time model download of roughly 1.6 GB and a minute or two of compute, which is a real cost the user should agree to. Once they have agreed, keep using it for that conversation without asking again.

node ${CLAUDE_PLUGIN_ROOT}/skills/youtube-notes/scripts/fetch_video.ts "<url>" \
  --mode full --whisper-fallback

Do not suggest browser cookies as a workaround. Upstream warns that authenticating that way eventually gets the account permanently banned.

Whisper output is cached like any other transcript, so the cost is paid once per video.

What comes back

JSON modes return metadata plus a `chapters` array. Fields that drive decisions:

• `chapters_source` — `youtube` (the upl