YouTube → atomic notes
Purpose
Turn one YouTube video into a source note plus a set of atomic notes in an Obsidian vault. The unit of extraction is a solid, transferable idea or concept — not a summary.
The note style (what an atomic note is, frontmatter, linking, a worked example) is fully codified in the bundled reference.md — this skill is self-contained and does not depend on any particular vault existing beforehand.
Configuration
The vault root is the YT_VAULT environment variable, defaulting to
~/Documents/obsidian/yt. The skill reads/writes three subfolders (created
automatically):
$YT_VAULT/Transcripts/— fetched transcript (provenance)$YT_VAULT/Sources/— one source note per video$YT_VAULT/Atoms/— the atomic notes
To target a different vault, set YT_VAULT before invoking (e.g.
export YT_VAULT=~/notes/myvault).
Instructions
1. Fetch the transcript
Run the bundled script with the URL the user gave you:
python3 "${CLAUDE_SKILL_DIR}/fetch_transcript.py" "<youtube url>"
It prints the absolute path of the transcript markdown file (or an ERROR: line
if the video has no English captions, or if YouTube throttled the request —
relay that to the user and stop). If a transcript for that video already exists,
it prints the existing path.
Requires
yt-dlp(python3 -m pip install yt-dlp). Auto-generated captions are used when no human captions exist — they extract fine.
2. Read the transcript IN FULL
Read the printed file completely (page through with offset/limit if it's long —
many videos run for hours). Do not extract from a partial read. The
frontmatter holds url, channel, duration; body paragraphs are prefixed
with **[MM:SS]** timestamps.
3. Learn the style, then extract
Read reference.md (in this skill's directory) — it is the authoritative guide for note shape, linking, and the worked example. Then extract atomic notes from the transcript following it. The essentials:
- Idea-driven, NO target count. Capture every distinct, solid, transferable idea the video genuinely contains — could be 2, could be 20+. Never pad to a number; never cut a real idea. Thin/promotional videos may yield very few.
- The bar: a real, transferable insight or concept. Skip sponsor reads, biography, small talk, and pure mechanics / play-by-play summary.
- One idea per note; declarative full-sentence titles (the filename is the claim).
- Always
[[wikilink]]every person and organization on every mention, plus concepts and 2–4 reusedtopics— even unresolved. These anchor the graph. - Source + clickable timestamp go in frontmatter, never in the body.
4. Write the files
Per the formats in reference.md:
- Each atom →
$YT_VAULT/Atoms/<the claim>.md - One source note →
$YT_VAULT/Sources/<Source Note Title>.md, listing every atom under## Atomic notes extracted. Every atom'ssource:must exactly match this title.
Use today's date for the created: field.
5. Mark the transcript processed
Edit the transcript file: change status: unprocessed to status: processed.
6. Report
Tell the user the source note title, how many atoms you wrote, and their titles.
Offer to run an indexing pass (e.g. an index-atomic-notes skill, if available)
to weave the new atoms' [[links]] into Topics/ maps of content.
Notes
- Batches: this skill is the per-video unit — drive it once per URL for multiple videos.
- Garbled caption names: auto-captions often misspell names; canonicalize people/org names to their correct spelling and flag any you're unsure about.
- Adapting: if a user's vault uses different conventions (tag names, folder
names), keep the principles in
reference.mdand adjust the specifics.