/youtube-analysis

name: youtube-analysis
description: 'Extract YouTube transcripts and produce structured concept analysis with multi-level summaries, key concepts, takeaways. Uses youtube-transcript-api with yt-dlp fallback. Triggers on: "analyze youtube video", "youtube transcript", "summarize this video", "extract concepts from video", "video key points", or any youtube.com/youtu.be URL.'
metadata:
  version: 1.1.1
  category: visualization
  tags: [youtube, analysis, skill]
  difficulty: intermediate

YouTube Analysis

Extract transcripts from YouTube videos and produce structured concept analysis — key ideas, arguments, technical terms, takeaways, and multi-level summaries — all without API keys or MCP servers.

Reference Files

| File | Purpose | | --------------------------------- | ------------------------------------------------------ | | `scripts/fetch_transcript.py` | Core transcript + metadata fetcher (CLI + importable) | | `scripts/analyze_video.py` | Orchestrator: fetch → structure → export scaffold | | `scripts/utils.py` | URL parsing, timestamp formatting, transcript chunking | | `references/analysis-patterns.md` | Prompt patterns for each video type | | `assets/output-template.md` | Markdown template for final output |

Workflow

User provides YouTube URL
        │
        ▼
┌─────────────────────┐
│  Step 0: Deps check │
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 1: Parse URL  │
└────────┬────────────┘
         ▼
┌─────────────────────┐     ┌──────────────┐
│  Step 2: Transcript │────▶│  yt-dlp      │
│  (youtube-t-api)    │fail │  (fallback)  │
└────────┬────────────┘     └──────┬───────┘
         │◀───────────────-────────┘
         ▼
┌─────────────────────┐
│  Step 3: Metadata   │
│  (yt-dlp --dump-json│
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 4: Claude     │
│  analyzes transcript│
└────────┬────────────┘
         ▼
┌─────────────────────┐
│  Step 5: Export MD  │
└─────────────────────┘

Step 0: Ensure Dependencies

Before running any script, verify dependencies are installed:

uv pip install youtube-transcript-api yt-dlp -q

Or run scripts directly with `uv run`:

uv run --with youtube-transcript-api --no-project python scripts/fetch_transcript.py "URL"

Verify:

python -c "from youtube_transcript_api import YouTubeTranscriptApi; print('OK')"
yt-dlp --version

Step 1: URL Parsing and Validation

Use `scripts/utils.py:parse_youtube_url()` to extract the video ID. Supported formats:

| Format | Example | | -------------- | -------------------------------------------------- | | Standard watch | `youtube.com/watch?v=dQw4w9WgXcQ` | | Short URL | `youtu.be/dQw4w9WgXcQ` | | Shorts | `youtube.com/shorts/dQw4w9WgXcQ` | | Embed | `youtube.com/embed/dQw4w9WgXcQ` | | Live | `youtube.com/live/dQw4w9WgXcQ` | | With params | `youtube.com/watch?v=dQw4w9WgXcQ&t=120&list=PLxxx` | | Bare ID | `dQw4w9WgXcQ` | | Mobile | `m.youtube.com/watch?v=dQw4w9WgXcQ` | | Music | `music.youtube.com/watch?v=dQw4w9WgXcQ` |

If parsing fails, ask the user to provide the URL in a standard format.

Step 2: Transcript Extraction

Run `fetch_transcript.py` to get the transcript:

cd <skill_dir>/scripts
python fetch_transcript.py "YOUTUBE_URL" --lang en

This outputs JSON to stdout. The script:

1. **Primary path**: Uses `youtube-transcript-api` to scrape captions directly (no API key) 2. **Fallback path**: If primary fails, uses `yt-dlp --write-sub --write-auto-sub` to extract subtitle files 3. **Language handling**: Tries requested language first, falls back to any available transcript

The returned JSON contains both individual timestamped segments and a joined `transcript_text` field.

**Or import as a module** (used by `analyze_video.py`):

from fetch_transcript import fetch_video
data = fetch_video("https://youtube.com/watch?v=VIDEO_ID", lang="en")

Step 3: Metadata Extraction

Metadata is fetched automatically by `fetch_transcript.py` via `yt-dlp --dump-json`:

• Title, channel name
• Duration (seconds)
• Upload date (YYYY-MM-DD)
• Description (first 500 chars in scaffold)
• View count
• Tags

No separate step needed — `fetch_video()` returns everything.

Step 4: Concept Analysis

**This is where you (Claude) do the work.** The scripts provide raw data; you perform the analysis.

Analysis Depth

Choose based on user request or video duration:

| Depth | When to Use | Sections to Fill | | ---------- | ------------------------------------------------ | --------------------------------------------- | | `quick` | User wants fast overview, or video < 10 min | TL;DR, Key Concepts, Takeaways | | `standard` | Default for most videos | All template sections | | `deep` | User wants thorough breakdown, or video > 30 min | All sections + timestamped section-by-section |

Analysis Process

1. **Read the full transcript** from the JSON output 2. **Identify the video type** (or use user-provided hint). See `references/analysis-patterns.md` for type-specific guidance 3. **Extract key concepts**: Main ideas, arguments, claims — each as a bullet with brief explanation 4. **Identify technical terms**: Definitions as presented in the video 5. **Pull notable statements**: Paraphrase key quotes with approximate timestamps 6. **Synthesize takeaways**: Actionable items the viewer should consider 7. **Write the TL;D