Summarize

Summarize

Universal content summarizer. Takes any input — YouTube video, web article, whitepaper/PDF, epub book, podcast, lecture — and produces a rich, interlinked Obsidian summary note with reference notes for every concept mentioned.

Requirements

Vault structure — the skill expects these folders inside your Obsidian vault. Folder names are the defaults; override them in the Configuration block below if your vault uses different names.

CLI tools — install these before first use, or let Step 0 walk you through it:

Alternative to mlx_whisper: set ELEVENLABS_API_KEY to use ElevenLabs Scribe for transcription.

Configuration

The skill reads these variables at runtime. Override any of them via environment variables, or edit the defaults here:

VAULT_ROOT     = $VAULT_ROOT        # auto-detected if not set (see Step 0a)
SUMMARIES_DIR  = 08 Summaries
REFERENCES_DIR = 07 References
PEOPLE_DIR     = 04 People
DAILY_DIR      = 02 Daily
TEMPLATES_DIR  = _Templates
BASES_DIR      = _Bases

All paths below are relative to $VAULT_ROOT.

Trigger

When the user provides content to summarize: a URL (YouTube, article, blog), a PDF/file path, pasted text, or a reference to content already in the vault.

Inputs

• Source: URL, file path, or pasted text
• Audience (optional): defaults to "general reader." User may specify (e.g. "high school student", "expert", "5-year-old")
• Depth (optional): defaults to "full." User may request "tldr only", "section-by-section", or "deep dive"

Step 0: Bootstrap check (first run)

Before doing any work, verify the environment is ready. Skip any check that already passes — only prompt the user when something is actually missing. Do not re-run Step 0 on subsequent invocations if the initial setup succeeded; you can tell it already ran if $VAULT_ROOT resolves and the required folders + tools are present.

0a. Resolve the vault root

vault=""
if [ -n "$VAULT_ROOT" ]; then
  vault="$VAULT_ROOT"
else
  dir="$PWD"
  while [ "$dir" != "/" ]; do
    if [ -d "$dir/.obsidian" ]; then vault="$dir"; break; fi
    dir="$(dirname "$dir")"
  done
fi
echo "Vault: ${vault:-NOT FOUND}"

If no vault is found, ask the user:

What's the absolute path to your Obsidian vault? Recommended: use a new, dedicated Obsidian vault for this skill — not your existing personal vault. The skill creates and modifies many notes and folders, and a clean vault avoids polluting your existing notes. If you don't have one yet, create an empty folder, open it in Obsidian (File → Open vault as folder), and paste that path here.

After they answer, validate that <answer>/.obsidian/ exists before using it — if not, warn that the path doesn't look like an Obsidian vault (they may need to open it in Obsidian first) and ask them to confirm or re-enter. Use the validated answer as $VAULT_ROOT for the session (and suggest they set it permanently in their shell profile).

0b. Check required folders

for d in "$SUMMARIES_DIR" "$REFERENCES_DIR" "$PEOPLE_DIR" "$DAILY_DIR" "$TEMPLATES_DIR"; do
  [ -d "$VAULT_ROOT/$d" ] || echo "MISSING: $d"
done

For each missing folder, ask the user: "Create <folder> in your vault? [y/N]" — if yes, mkdir -p "$VAULT_ROOT/<folder>".

0c. Check required CLI tools

for tool in yt-dlp defuddle pdftotext pandoc; do
  command -v "$tool" >/dev/null 2>&1 || echo "MISSING: $tool"
done

For each missing tool, tell the user what's missing and ask before installing — installs touch the user's system. Use the install commands from the Requirements table above. If the user declines, note which tools are missing and warn that the corresponding content types (YouTube, web articles, PDFs, EPUBs) will fail until installed.

0d. Install the person template if missing

The skill ships two person templates in the repo's templates/ folder (shared with summarize-call):

• new person template.md — full version with Dataview callouts (current age, total hours talked) and Obsidian Bases embeds (posts.base, books.base, meetings.base). Requires the Dataview plugin and Obsidian Bases.
• new person template (minimal).md — stripped version. Just frontmatter, a > [!info] summary callout, and an ## updates section. Works in any vault.

If $VAULT_ROOT/$TEMPLATES_DIR/new person template.md already exists, leave it alone — the user may have their own customized version.

Otherwise, ask the user which version to install:

Install person template — which version?

1. Minimal (default, works in any vault)
2. Full (requires Dataview plugin + Obsidian Bases)

Then copy the chosen template into the user's _Templates/ folder:

skill_dir="$(dirname "$0")"   # or wherever this SKILL.md lives
target="$VAULT_ROOT/$TEMPLATES_DIR/new person template.md"

if [ ! -f "$target" ]; then
  # Use the user's choice — default to minimal
  src="$skill_dir/../templates/new person template (minimal).md"
  # if user picked full: src="$skill_dir/../templates/new person template.md"
  cp "$src" "$target"
fi

Note: whichever version gets installed lands at _Templates/new person template.md (no (minimal) suffix) so the skill's later references work uniformly.

Once Step 0 passes, proceed to Step 0.5.

Step 0.5: Determine depth mode

Before extraction, establish which depth the user wants:

1. Scan the invocation first. If the user's request already specifies a mode, use it and skip the prompt:
   • Words like minimal, fast, quick, --minimal, -m → minimal mode
   • Words like detailed, deep, full, --detailed, -d → detailed mode
2. Otherwise, prompt. No default — if unspecified, ask every time:

Depth?

1. Detailed (best results) — full reference notes for every wikilinked concept, person notes for every mentioned person, parallel highest-available-model subagents per section, base updates
2. Minimal (fast) — summary note only, wikilinks left dangling, person notes for creators/guests only, Sonnet summary

This keeps interactive runs explicit while letting scheduled tasks / cron / /loop pass the mode in the invocation (e.g. /summarize <url> minimal) without blocking on input.

The chosen mode determines which steps run:

For book chapter-by-chapter depth (Step 1 book section), detailed mode gets the full 300-600 words per chapter; minimal mode gets a flatter single summary regardless of chapter count.

Step 1: Detect content type and extract text

YouTube video

# Get metadata
yt-dlp --cookies-from-browser chrome \
  --print "%(id)s|%(title)s|%(duration)s|%(upload_date)s|%(view_count)s|%(channel)s|%(channel_id)s" \
  --no-download "<URL>"

# Try auto-subtitles first (fastest, free)
yt-dlp --cookies-from-browser chrome \
  --write-auto-sub --sub-lang en --sub-format json3 \
  --skip-download -o "/tmp/summarize/%(id)s" "<URL>"

If auto-subs exist, extract text from the JSON3 file. If not, or if quality is poor:

• Download audio and transcribe (same as youtube-transcribe skill — ask user: local mlx_whisper or ElevenLabs Scribe)

Web article / blog post

defuddle parse "<URL>" --md -o /tmp/summarize/article.md

If defuddle is not installed: npm install -g defuddle

Extract title, author, date, domain from defuddle metadata:

defuddle parse "<URL>" -p title
defuddle parse "<URL>" -p domain

PDF

pdftotext "<path>" /tmp/summarize/paper.txt

If pdftotext is not available: brew install poppler

EPUB (books)

# Extract full text as markdown (preserves chapter structure)
pandoc "<path>" -t markdown --wrap=none -o /tmp/summarize/book.md

# If you need chapter boundaries, extract the TOC:
pandoc "<path>" -t json | python3 -c "
import json, sys
doc = json.load(sys.stdin)
for block in doc['blocks']:
    if block['t'] == 'Header':
        level = block['c'][0]
        text = ''.join(
            item['c'] if item['t'] == 'Str' else ' ' if item['t'] == 'Space' else ''
            for item in block['c'][2]
        )
        print(f'L{level}: {text}')
"

Chapter splitting strategy for books:

1. Extract full text with pandoc → markdown
2. Identify chapter boundaries from headers (epubs have built-in TOC structure that pandoc preserves as #/## headers)
3. Split into one chunk per chapter
4. Dispatch parallel Opus subagents — one per chapter — same as any other long content
5. A typical book (60-100k words, 15-30 chapters) produces chapters of ~3-5k words each — well within subagent context limits

For very long books (>30 chapters): batch chapters into groups of ~5 per subagent to keep the number of parallel agents manageable. Each subagent summarizes its batch and returns section summaries.

CRITICAL — Book summary depth requirement:

• Each chapter MUST get its own dedicated ## Chapter N: Title section with a substantial summary (300-600 words per chapter depending on chapter length)
• Do NOT batch multiple chapters into a single brief paragraph — every chapter gets its own detailed treatment
• Include key arguments, data points, examples, and quotes from each chapter
• A 10-chapter book should produce ~3000-6000 words of summary content (excluding frontmatter/tldr)
• A 30-chapter book should produce ~5000-10000 words
• Think of each chapter summary as a standalone mini-essay that captures the chapter's core contribution
• The goal is that someone reading the summary should understand what each chapter argues, not just what the book is "about" at a high level

Output structure for books:

• Location: 08 Summaries/<Book Title>.md (or 08 Summaries/<Author>/<Book Title>.md if summarizing multiple books by one author)
• Frontmatter tag: book
• Extra fields: creator (author wikilink), published (year), isbn (if known), source (wikilink to the epub file if it's in the vault, e.g. "[[Book Title.epub]]")
• Each chapter gets its own ## Chapter N: Title section in the summary
• Add a ## Chapter Navigation callout at the top if the book has many chapters

Other files (txt, docx, etc.)

For .docx: pandoc "<path>" -t markdown --wrap=none -o /tmp/summarize/doc.md

For plain text: read directly.

Pasted text / vault note

Read directly from user message or vault path.

Step 1b: Save transcript (audio/video content only)

For any content that has audio — YouTube videos, podcast episodes, lectures/talks with recordings — save the extracted transcript as a permanent vault note.

When to create a transcript note:

• YouTube videos (from auto-subs or whisper transcription)
• Podcast episodes (from transcription)
• Lectures/talks with audio/video recordings
• Any content where the source is spoken word

Do NOT create transcript notes for: articles, blog posts, PDFs, books, pasted text — these are already text.

Location: Same folder as the summary note, with Transcript appended to the filename.

Format:

---
date: YYYY-MM-DD
duration: <seconds>
recording: "<source URL>"
meeting: "[[<Summary Note Title>]]"
unread: true
---

[Full timestamped transcript text, one line per segment]

Link from summary: Add transcript: "[[<Title> Transcript]]" to the summary note's frontmatter.

This step happens immediately after text extraction (Step 1) and before output structure planning (Step 2). The transcript is the raw source material — always preserve it.

Step 1c: Archive audio to the vault + enable click-to-play timestamps (audio/video content only)

If the user has the Media Extended Obsidian plugin installed (assume YES unless proven otherwise — it's a common companion plugin for this workflow), move the downloaded source audio into the vault and wire up click-to-play timestamps throughout the summary.

1c-i. Archive the audio

Copy (or move) the downloaded mp3/wav/mp4 into $VAULT_ROOT/_Attachments/ with a descriptive, human-scannable filename that includes the date and — if cropped — the segment range.

<Creator> x <Guest> <YYYY-MM-DD>.mp3
<Creator> x <Guest> <YYYY-MM-DD> (HhMMm-HhMMm).mp3   # if cropped

Add audio: "[[<filename>.mp3]]" to the summary note's frontmatter so the attachment is a first-class property on the note (parallel to transcript:, source:, etc.).

1c-ii. Embed ONE pinned player at the top

Place a single full-length audio/video embed at the top of the summary, just above the > [!tldr] callout:

> [!abstract] Audio — full interview (cropped H:MM:SS – H:MM:SS of the VOD)
> ![[<filename>.mp3]]

Do not scatter multiple ![[audio.mp3#t=...]] embeds through the note — every embed spawns a fresh player. Media Extended's pattern is one pinned player + many text-link jump-points.

Do NOT add:

• A "Pin this player / Media Extended: right-click → Pin" instruction underneath the embed. The user knows how their plugin works. Don't narrate it.
• A "Key moments" / "Jump to" / "Chapters" callout listing timestamped highlights. The per-quote inline jumps (Step 1c-iii) already give every notable moment a click-to-play entry point; a separate highlights list is redundant and repeats the same timestamps twice.

1c-iii. Add inline click-to-play links next to every quote

For every > [!quote] callout that embeds a transcript line (![[...Transcript#^block-id]]), add a sibling line inside the same callout:

> [!quote] Who — what they said
> ![[<Transcript Note>#^block-id]]
> ▶ [[<filename>.mp3#t=<seconds>|jump player to H:MM:SS]]

• The #t=<seconds> fragment is audio-local seconds, not wall-clock VOD time. If the audio was cropped (e.g. starting at VOD 1:17:00), subtract the crop offset from the VOD timestamp before emitting.
• The |jump player to H:MM:SS alias is what the user reads — format it H:MM:SS when ≥1 hour, else M:SS.
• The leading ▶ (U+25B6) is a visual cue — keep it.
• These are text links (no ! prefix), not embeds. Media Extended routes the click to the pinned player instead of creating a new one.

1c-iv. Math for audio-local offsets

audio_sec = (vod_h * 3600 + vod_m * 60 + vod_s) - crop_start_sec

If the transcript already uses block IDs of the form ^p1-H-MM-SS (absolute VOD timestamps), this regex transformation converts every quote-embed into one with an audio-local jump link appended:

import re
AUDIO = "<filename>.mp3"
CROP_OFFSET_SEC = <crop start seconds>   # 0 if audio starts at beginning of the source

pattern = re.compile(
    r'^(> !\[\[[^\]]*Transcript#\^p1-(\d+)-(\d+)-(\d+)(?:-\d+)?\]\])$',
    re.MULTILINE,
)

def repl(m):
    block_line = m.group(1)
    h, mm, ss = int(m.group(2)), int(m.group(3)), int(m.group(4))
    audio_sec = (h*3600 + mm*60 + ss) - CROP_OFFSET_SEC
    if audio_sec < 0:
        return block_line
    hh = audio_sec // 3600
    mm2 = (audio_sec % 3600) // 60
    ss2 = audio_sec % 60
    label = f"{hh}:{mm2:02d}:{ss2:02d}" if hh else f"{mm2}:{ss2:02d}"
    return f"{block_line}\n> ▶ [[{AUDIO}#t={audio_sec}|jump player to {label}]]"

text = pattern.sub(repl, text)

Run this after Step 4 assembles the summary — it's a pure string transform.

1c-v. If the user does NOT have Media Extended

Fall back to native Obsidian syntax: one top-of-note ![[audio.mp3]] embed only. Do not scatter ![[audio.mp3#t=N]] embeds inline — they each spawn a separate player, which clutters the note. Inline timestamp references in that case should just be the VOD timestamp as plain text.

Step 2: Determine output structure

Based on content type, choose the appropriate format:

All notes get: created, updated, date, summary, categories: ["[[posts.base]]"], unread: true

summary field length — HARD LIMIT: ≤70 characters. One tight line, no wikilinks, no paragraph-length blurbs. The > [!tldr] callout at the top of the body is where the long-form overview lives. The frontmatter summary is just a scannable hint for base views — think newspaper subhead, not abstract. Examples that are the right size:

• "Ledger interviews Cobie — 3h 51m UpOnly career retrospective" (60 chars)
• "Cobie on ThreadGuy — first interview since joining Coinbase" (59 chars)
• "Lex x Karpathy — state of AI, RLHF, self-driving, education" (60 chars)

If it's longer than 70 characters, cut it. Do not paste the tldr into the summary field.

If a channel/show folder is needed, check if it already exists before creating.