| name | youtube-topic-research |
| description | Find and summarize YouTube videos for topics where visual explanation, demos, tutorials, talks, walkthroughs, or screen recordings are useful. Can run standalone, or export transcript-backed video source notes into notebooklm-mode vaults for grounded research.
|
| version | 2.0.0 |
| author | moonlight-lupin |
| license | MIT |
| platforms | ["linux","macos","windows"] |
YouTube Topic Research Skill
When to Use
Use when the user wants to find and summarize YouTube videos on a specific
topic — not when they already have a URL (use a transcript extraction skill
for that). This skill searches, filters, fetches transcripts, and returns the
top relevant videos with summaries.
Examples:
- "Find YouTube videos on Python async programming"
- "Show me recent videos about LLM fine-tuning"
- "What are the best tutorials for React Server Components?"
- "Research this topic through YouTube, then build a vault" → feeder mode
Two Modes
Standalone mode (default)
Search YouTube, fetch transcripts, rank videos, and return the top
recommendations with summaries, freshness indicators, and watch/skip guidance.
NotebookLM feeder mode
After the user approves videos, save each selected video as a source file
compatible with notebooklm-mode, including metadata, URL, transcript
extracts, visual/demo notes, summary, and freshness status.
Trigger phrases for feeder mode:
- "add these to notebooklm"
- "make a source vault from these videos"
- "research this through YouTube first, then build a vault"
- "use videos as sources"
python scripts/search_and_summarize.py "docker networking" --export-vault /path/to/vault
This generates source files in sources/ inside the vault, formatted for
notebooklm-mode ingestion. The agent can then run notebooklm-mode for
grounded Q&A, notes, reports, or slides built on the video sources.
Architecture
youtube-topic-research
│
├── standalone recommendation output (default)
│
└── --export-vault: selected videos as source files
│
▼
notebooklm-mode vault
│
▼
grounded Q&A / notes / reports / slides
Relationship to notebooklm-mode
This skill can be used standalone or as a feeder into notebooklm-mode:
| Use case | Mode |
|---|
| "Find me good YouTube tutorials on Docker networking" | Standalone |
| "Find recent visual demos of Godot 4 agent workflows" | Standalone |
| "Research this topic using YouTube and save sources" | Feeder → notebooklm-mode |
| "Build me a grounded brief from videos and articles" | youtube-topic-research + notebooklm-mode |
| "Summarize this one YouTube URL" | Separate transcript extraction skill |
Most users asking for videos just want recommendations. Feeder mode is for
real research — when video sources should ground further Q&A and deliverables.
Prerequisites
pip install ddgs "youtube-transcript-api<1.0" jinja2 pyyaml
The ddgs CLI (DuckDuckGo search) is the primary search backend.
youtube-transcript-api is used for transcript fetching. Pin to <1.0:
the script uses the get_transcript() / list_transcripts() static-method
API, which was removed in youtube-transcript-api 1.0 (renamed to instance
methods .fetch() / .list()). An unpinned install pulls 1.x and transcript
fetching silently returns nothing.
Quick Start
python scripts/search_and_summarize.py "python async tutorial"
python scripts/search_and_summarize.py "LLM fine-tuning 2024" --top 3
python scripts/search_and_summarize.py "linux basics" --no-freshness
python scripts/search_and_summarize.py "rust ownership" --format json
python scripts/search_and_summarize.py "docker networking" --export-vault /path/to/vault
Pipeline
User Query
│
▼
┌─────────────────────────────────────┐
│ 1. SEARCH (ddgs videos) │
│ -q "query" -m 8 -o json │
│ Filter: publisher == "YouTube" │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 2. QUALIFY (heuristic or LLM) │
│ Score 0-100 per candidate │
│ Criteria: topic_match, authority,│
│ duration_signal, freshness │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 3. FETCH TRANSCRIPTS (top 3-4) │
│ youtube_transcript_api direct │
│ OR external fetch_transcript.py │
│ Health check: len > 500 chars │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 4. REVIEW (heuristic or LLM) │
│ Relevance score + summary bullets│
│ Chunk if > 40K chars │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 5. FORMAT & OUTPUT │
│ Standalone: output.md.j2 │
│ Feeder: notebooklm source files │
└─────────────────────────────────────┘
LLM Integration
Steps 2 and 4 have LLM prompt templates (references/qualify_prompt.md and
references/review_prompt.md). The script uses heuristic scoring by default.
To enable LLM qualification/review, an agent runtime overrides call_llm():
import search_and_summarize
def my_llm_call(prompt: str) -> dict | None:
response = my_llm_api.chat(prompt)
return json.loads(response)
search_and_summarize.LLM_CALL = my_llm_call
When call_llm() returns a valid JSON dict, the script uses LLM scoring. When
it returns None, the script falls back to heuristic scoring. The heuristic
uses keyword overlap (with stopwords removed), view count, duration, and age.
For long transcripts (>40K chars), the script chunks the transcript and reviews
each chunk individually via LLM, then merges the results.
Visual Analysis Caveat
This skill can identify likely visual/demo-rich videos from metadata, titles,
descriptions, and transcripts, but unless the runtime supports frame/image
inspection, it does not truly inspect the video visuals. Transcript-grounded
summary is not the same as visual analysis. The skill flags videos that likely
contain demos, walkthroughs, or visual explanations based on title/description
keywords, but cannot confirm what the viewer will actually see on screen.
Feeder Mode Source File Format
When --export-vault is used, each video is saved as a source file compatible
with notebooklm-mode:
# YouTube Source: [Video Title]
| Field | Value |
|------|-------|
| URL | https://youtube.com/watch?v=... |
| Uploader | Channel Name |
| Published | YYYY-MM-DD |
| Duration | 18:42 |
| Views | 1.2M |
| Retrieved | YYYY-MM-DD |
| Type | youtube |
| Transcript Quality | good |
| Freshness | fresh |
## Why Selected
[Short reason based on query fit, authority, freshness, and transcript relevance.]
## Visual / Demo Value
- Shows live coding / dashboard / product walkthrough / diagrams / UI demo.
- Useful because this topic benefits from visual explanation.
## Transcript Extracts
> "Relevant transcript quote..."
> — approx. timestamp: 04:12
> "Another relevant quote..."
> — approx. timestamp: 09:45
## Summary
- Key point 1
- Key point 2
- Key point 3
## Gaps
- Does not cover X
- Assumes Y
Configuration
Fast-Moving Domains (references/fast_moving_domains.yaml)
Defines freshness thresholds for topics where recent content matters more:
domains:
- name: ai_ml
keywords: ["ai", "llm", "fine-tuning", "gpt", "claude", ...]
stale_months: 12
aging_months: 6
Unmatched topics use defaults (stale > 36mo, aging > 24mo).
Defaults
| Parameter | Default | Override |
|---|
max_candidates | 8 | --max-candidates |
qualify_top_k | 4 | --qualify-top |
transcript_top_k | 3 | --transcript-top |
final_top_k | 2 | --top |
min_transcript_chars | 500 | --min-transcript |
chunk_size | 40000 | --chunk-size |
enable_freshness | true | --no-freshness |
Error Handling
| Failure Point | Behavior |
|---|
ddgs not installed | Exit with install instruction |
ddgs videos returns empty | Retry once with broader query; report if still empty |
| No YouTube results in DDG | Report "no YouTube videos found for query" |
| All transcripts fail/disabled | Return raw DDG list + "could not fetch transcripts" |
| LLM qualification fails | Fallback: heuristic scoring |
| Transcript > chunk_size | Auto-chunk with 2K overlap, review each, merge |
| Output formatting fails | Fallback to plain text summary |
| IP blocked (cloud VM) | See references/ip-blocking-workaround.md |
Limitations
- No YouTube API — relies on DuckDuckGo video index (may miss very new/unindexed videos)
- Transcript availability ~50-70% of videos; auto-captions may have errors
- Rate limits — DDG may throttle rapid requests; skill adds 1-2s delay between calls
- Token cost — Full transcript review via LLM uses ~5-15K tokens per video
- Language — Prefers English; falls back to any available transcript
- IP blocking — Cloud provider IPs may be blocked by YouTube; see workaround reference
- No visual inspection — identifies likely visual/demo videos from metadata, not frame analysis
Extending
- Add domains to
references/fast_moving_domains.yaml
- Customize
references/qualify_prompt.md / references/review_prompt.md
- Modify
templates/output.md.j2 for different output formats (Discord, Slack)
- Set
TRANSCRIPT_SCRIPT env var to point at an alternative transcript fetcher
- Override
call_llm() for LLM-driven qualification and review
Files
youtube-topic-research/
├── SKILL.md # This file
├── scripts/
│ └── search_and_summarize.py # Main entry point
├── references/
│ ├── qualify_prompt.md # LLM prompt for metadata qualification
│ ├── review_prompt.md # LLM prompt for transcript review
│ ├── fast_moving_domains.yaml # Freshness thresholds by domain
│ ├── debugging-patterns.md # DDG CLI quirks, date parsing, transcript cleaning
│ └── ip-blocking-workaround.md # YouTube IP blocking workarounds (cloud VMs)
└── templates/
└── output.md.j2 # Jinja2 template for standalone output
