yt-pipeline

name	yt-pipeline
description	Research any topic via YouTube — search, curate 20 videos from reputable sources, push to NotebookLM for AI analysis, pull insights back, and output structured markdown. Trigger when user says "/yt-pipeline", "research this on YouTube", "find YouTube videos about", or wants YouTube-sourced knowledge synthesis.

YT Pipeline

Composable YouTube research pipeline: validate topic → search → curate → analyse via NotebookLM → deliver markdown.

Prerequisites

Dependencies are installed in the skill's venv at ~/.claude/skills/yt-pipeline/venv/.

To reinstall or update:

~/.claude/skills/yt-pipeline/venv/bin/pip install -U google-api-python-client youtube-transcript-api "notebooklm-py[browser]"

Authenticate NotebookLM (one-time — opens browser for Google sign-in):

~/.claude/skills/yt-pipeline/venv/bin/notebooklm login

YouTube Data API key is stored in 1Password (Private vault, item yt-data, field credential). Load it with:

export YOUTUBE_API_KEY=$(op read "op://Private/yt-data/credential")

All scripts in this skill MUST be run using the skill venv Python:

~/.claude/skills/yt-pipeline/venv/bin/python3

Command Interface

/yt-pipeline "<topic>" [--max_results=20] [--output=report] [--store=true]

Parameter	Default	Description
topic	—	Research query (required)
max_results	20	Videos to select after ranking
output	report	Format: summary, notes, report
store	false	Persist notebook in NotebookLM after completion

Pipeline Workflow

Stage 1: Validate Topic

Confirm the topic is:

• Non-empty and specific enough for meaningful search
• Not a single generic word — suggest refinements if too broad
• If ambiguous, ask the user to clarify scope before proceeding

Stage 2: Search YouTube

Run scripts/yt_search.py with the topic to fetch candidate videos.

YOUTUBE_API_KEY=$(op read "op://Private/yt-data/credential") ~/.claude/skills/yt-pipeline/venv/bin/python3 scripts/yt_search.py "<topic>" --max_results 50

Returns JSON array of candidates with: video_id, title, channel, views, duration, published_at, description.

Stage 3: Curate Top 20

From the search results, select the best 20 videos using these criteria:

1. Source credibility — Prefer established channels, verified creators, known institutions, conference talks, and channels with high subscriber counts
2. Relevance — Title and description must directly address the topic
3. Recency — Prefer recent content unless the topic is foundational
4. Diversity — Avoid multiple videos from the same channel; seek varied perspectives
5. Engagement — Higher view counts signal value, but don't override credibility
6. Duration — Prefer substantive content (8+ minutes) over shorts/clips

Present the curated list to the user with channel names and brief rationale. Ask for approval before proceeding to analysis.

Stage 4: Push to NotebookLM

Run scripts/yt_notebooklm.py to create a notebook and add the 20 YouTube URLs as sources.

~/.claude/skills/yt-pipeline/venv/bin/python3 scripts/yt_notebooklm.py create "<topic>" --urls urls.json

This creates a NotebookLM notebook, adds all 20 YouTube videos as sources, and waits for NotebookLM to process them.

Stage 5: Analyse via NotebookLM

Query the notebook for structured analysis. Run scripts/yt_notebooklm.py with analysis prompts:

~/.claude/skills/yt-pipeline/venv/bin/python3 scripts/yt_notebooklm.py ask <notebook_id> --prompt "analysis_prompt_here"

Run these queries sequentially:

1. Executive summary — "Provide a comprehensive summary of the key themes and findings across all sources"
2. Key insights — "List the top 10 most important insights, with source attribution"
3. Points of agreement — "What do the majority of sources agree on?"
4. Points of disagreement — "Where do sources contradict or disagree with each other?"
5. Notable quotes — "Extract the most impactful direct quotes with attribution"
6. Practical takeaways — "What actionable recommendations emerge from these sources?"

Stage 6: Deliver Markdown Output

Compile all NotebookLM responses into a structured markdown document. See references/output-templates.md for the exact templates per output format.

Write the output to ./yt-pipeline-output/<topic-slug>.md.

If --store=false (default), delete the NotebookLM notebook after extracting results. If --store=true, keep it and provide the notebook URL.

Error Handling

• No API key → Tell user to set YOUTUBE_API_KEY
• NotebookLM not authenticated → Tell user to run notebooklm login
• No results found → Suggest refined search terms
• NotebookLM source add fails → Skip that video, log warning, continue with remaining
• < 10 videos successfully added → Warn user about reduced analysis quality