| name | youtube-to-atoms |
| description | Given a YouTube URL, fetch its transcript and extract atomic notes into an Obsidian vault. Use when handed a YouTube link to mine for ideas, or asked to "turn this video into atomic notes / atoms". |
| allowed-tools | Bash, Read, Write, Edit |
| argument-hint | <youtube url> |
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 reused topics — 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's source: 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.md and adjust the specifics.
