Youtube Summary

youtube-summary

Turn a YouTube video into a structured note in the user's Obsidian vault.

When to use

• User pastes a YouTube URL and asks for a summary / takeaways / notes
• User invokes /youtube-summary
• User says something like "write this up", "save this video", etc. with a YouTube link

By default, summaries are built from the transcript only. If the user says the video has important slides (or asks to "include the slides", "the slides matter", a slide-heavy conference talk, etc.), also run the opt-in slide flow in the section below. Do not extract slides unless the user asks for this video specifically — it downloads the full video (~hundreds of MB) and is slow.

Configuration (optional)

The output location is not hardcoded — resolve it at runtime:

~/.claude/skills/youtube-summary/resolve-config.sh

It always succeeds and prints a MODE plus a NOTES_DIR (the absolute folder to write the note into). Two modes:

• MODE=obsidian — an Obsidian vault is configured; it also prints

VAULT_NAME, VAULT_PATH, NOTES_SUBFOLDER. The note goes into the vault and is opened in Obsidian; slide images embed via ![[wikilinks]].

• MODE=plain — no vault configured (works out-of-the-box); the note is

printed in the reply to the user, not saved to a file. (If slides are being embedded, it's saved to NOTES_DIR = the current directory instead, since the images need to live on disk; slides embed via standard Markdown image links.)

Use the resolver's values as placeholders below ($NOTES_DIR, $VAULT_NAME, …).

Offer Obsidian mode if the user uses Obsidian and you're in MODE=plain: help them create ~/.config/youtube-summary/config.sh (template: config.example.sh next to this SKILL.md) with their vault name, absolute path, and notes subfolder — or set env vars OBSIDIAN_VAULT_NAME / OBSIDIAN_VAULT_PATH / NOTES_SUBFOLDER for a one-off run.

• Filename: .md (sanitize: replace / with -, strip leading/trailing whitespace, no quotes)

Procedure

0. Resolve config

Run resolve-config.sh (above) and note MODE and NOTES_DIR (plus the vault vars in obsidian mode) for the steps below.

1. Fetch transcript + metadata

Run the helper script next to this SKILL.md:

~/.claude/skills/youtube-summary/fetch-transcript.sh ""

It writes the output to ~/.cache/yt-summary/latest.txt (and also prints to stdout). Format:

• Line 1: ID|TITLE|CHANNEL|UPLOAD_DATE|DURATION_SECONDS|URL
• ---CHAPTERS---
• A chapters JSON array ([{"start_time","end_time","title"}, ...]) or NA if the video has no chapters
• ---TRANSCRIPT---
• Rest: cleaned transcript text

Cookies are cached at ~/.cache/yt-summary/cookies.txt so the macOS Keychain only prompts on first run or when cookies expire. If YouTube auth fails, the script auto-refreshes from $BROWSER (default chrome). Override with BROWSER=safari ~/.claude/skills/youtube-summary/fetch-transcript.sh "" if Chrome isn't your primary browser.

2. Read the transcript

Use the Read tool on ~/.cache/yt-summary/latest.txt (already allowlisted — no permission prompt). The transcript is auto-captioned so expect typos — fix obvious ones in the summary using context (e.g. "Cloud Code" → "Claude Code", "JGC" → "ZGC", brand/product names, technical terms).

Chapters: if the ---CHAPTERS--- section is a JSON array (not NA), use the chapter titles (in order) as the section structure for the "Key takeaways" headings — they're the author's own outline. Map transcript content into each chapter's [start_time, end_time) window, and (for slide videos) align slides by their timestamp too. If chapters are NA, fall back to inferring 3-6 topical headings yourself.

3. Write the note

Build the note using the template below. Where it goes depends on MODE:

• MODE=obsidian — write the file to $NOTES_DIR/.md (create $NOTES_DIR if needed).
• MODE=plain — do not write a file; print the full note directly in your

reply to the user (the whole Markdown document). Exception: if you're embedding slides, the images must live on disk — so in that case write the note + slides folder to $NOTES_DIR and tell the user the path instead of printing.

Template:

---
title: 
speaker: 
channel: 
url: 
published: 
duration: 
watched: 
tags:
  - youtube
  - 
---

# 

## TL;DR

## Key takeaways

### 
- 
- 

### 
- ...

(Headings = the video's chapter titles when it has them; otherwise 3-6 topical headings you infer from the talk structure.)

## Read more / related

- **** — : 
- ... (5-12 items: official docs, JEPs, blog posts the speaker referenced, related Obsidian notes via [[wikilinks]])

## Open questions / things to dig into
- 
- 

4. Open / report

• MODE=obsidian — open it in Obsidian (URL-encode the path):

``bash open "obsidian://open?vault=$VAULT_NAME&file=$NOTES_SUBFOLDER/.md" ` Or, if the Obsidian CLI is installed and enabled, obsidian open path="$NOTES_SUBFOLDER/.md"`.

• MODE=plain — nothing to open; you already printed the note in your reply.

(Only if slides forced a file: tell the user the path you wrote to.)

Slide-aware summaries (opt-in)

Only when the user asks to include slides for a specific video. Slides capture diagrams, code, charts, and bullet text the speaker shows but never says — and they're a safety net when the auto-caption transcript is truncated.

Prereqs: ffmpeg + ffprobe (e.g. brew install ffmpeg). The helper reuses the same cookie cache as fetch-transcript.sh.

S1. Probe the layout

~/.claude/skills/youtube-summary/fetch-slides.sh "" --probe

Downloads a 1080p copy (cached) and dumps ~6 sample frames to ~/.cache/yt-summary/slides//probe/. Read those frames with the Read tool to determine the recording's layout, then choose two crop rectangles (ffmpeg W:H:X:Y = width:height:x-offset:y-offset):

• --detect-crop: a tight interior slide sub-region with no speaker

picture-in-picture and no animated background. Used only for change detection; a moving speaker or animated border makes every frame look "changed".

• --save-crop: the full slide region to save as the image (exclude the

speaker PiP and any fiery/animated chrome, but keep the whole slide).

If slides fill the frame edge-to-edge with no PiP/animation, you can omit the crops (defaults to full frame).

S2. Extract slides + contact sheets

~/.claude/skills/youtube-summary/fetch-slides.sh "" \
  --detect-crop W:H:X:Y --save-crop W:H:X:Y

Writes one image per unique slide to final/, 2x3 contact sheets to sheets/, and manifest.txt ( ). Tune with --gap N (collapse changes -slides/-NN-description.jpg

Embed inline at the relevant point in the note, using the syntax for the mode:
- **`MODE=obsidian`**: `![[-NN-description.jpg]]` (Obsidian resolves by filename)
- **`MODE=plain`**: `` (standard Markdown relative link, so it renders in any viewer)

Put the slide image next to its transcription — e.g. the diagram image followed
by a short prose description, or the code-slide image followed by the same code
in a fenced block.

### S5. Cleanup
Delete the cached `video1080.mp4` (and any `slides_out`/`detect`/`probe` scratch)
when done — keep `final/` and `sheets/` only if useful. The video is the large
artifact.

Note in the front-matter or a callout that slides were merged in, and if the
transcript was truncated say which sections came from slides only.

## Style rules for the summary

- **Be specific, not generic.** Concrete library names, version numbers, latency numbers, JEP numbers. If the speaker says "we saw lower errors", quantify if they did; if not, say "significantly" not "much".
- **Capture the *interesting* parts.** What's the non-obvious insight, the counter-intuitive trade-off, the gotcha? Skip filler ("they have many users", "they use microservices") unless it's load-bearing.
- **Fix auto-caption errors.** Watch for: product names ("Cloud Code" → "Claude Code"), acronyms ("JGC" → "ZGC"), homophones ("there/their"), hallucinated punctuation.
- **Read more links must be real.** Only include URLs you're confident exist — official docs, JEPs, well-known project pages. If the speaker referenced a blog post you can't verify the URL for, write the search query instead: `search "Spring One Paul Bakker testing" on YouTube`.
- **Use `[[wikilinks]]`** to seed connections to existing or future notes in the vault.
- **One-line YAML tags** — lowercase, kebab-case, 2-5 topic tags beyond the always-present `youtube`.

## Notes
- All paths come from `resolve-config.sh` (env vars or `~/.config/youtube-summary/config.sh`). Nothing vault-specific is hardcoded in this skill — keep it that way so it stays publishable.
- On macOS the filesystem is case-insensitive, so match the casing of `NOTES_SUBFOLDER` to the user's existing folder to avoid creating a near-duplicate.
- Opening via the `obsidian://` URI works without extra setup. The `obsidian open` CLI alternative requires the Obsidian CLI enabled (Settings → General → CLI) with the `obsidian` binary on `$PATH`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ParthGanatra](https://github.com/ParthGanatra)
- **Source:** [ParthGanatra/agent-skills](https://github.com/ParthGanatra/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.