Skip to content

SKILL.md

Latest commit

 

History

History
244 lines (188 loc) · 11.4 KB

SKILL.md

File metadata and controls

244 lines (188 loc) · 11.4 KB
name youtube-analysis
description Extract YouTube video transcripts and produce structured concept analysis with multi-level summaries, key concepts, and actionable takeaways. Pure Python, no API keys, no MCP dependency. Fetches transcripts via youtube-transcript-api with yt-dlp fallback, then Claude analyzes the content directly. Use this skill when the user mentions: analyze youtube video, youtube transcript, summarize this video, what does this video cover, extract concepts from video, video analysis, watch this for me, break down this talk, youtube URL, video summary, lecture notes from video, podcast transcript, conference talk notes, tech talk breakdown, video key points, TL;DR of video, video takeaways, or pastes any URL containing youtube.com or youtu.be.
metadata
version category tags difficulty
1.1.0
visualization
youtube
analysis
skill
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;DR: One to three sentences capturing the core message
  8. Suggest related topics: Based on concepts mentioned, what should the viewer explore next

For Deep Analysis

Use utils.chunk_transcript() to break the transcript into 5-minute segments, then analyze each chunk with timestamps:

from utils import chunk_transcript
chunks = chunk_transcript(data["transcript"], chunk_minutes=5)
for chunk in chunks:
    print(f"[{chunk['start_formatted']} - {chunk['end_formatted']}]")
    print(chunk["text"])

Or run the orchestrator with --depth deep:

python analyze_video.py "YOUTUBE_URL" --depth deep

Video Type Patterns

Type Key Extraction Focus See
Lecture Thesis, arguments, citations, definitions references/analysis-patterns.md
Tutorial Steps, tools, prerequisites, gotchas references/analysis-patterns.md
Interview Perspectives, disagreements, attributed positions references/analysis-patterns.md
Podcast Topic threads, opinions, recommendations references/analysis-patterns.md
Tech Talk Architecture, trade-offs, benchmarks, lessons references/analysis-patterns.md
Panel Consensus vs. disagreement, per-speaker views references/analysis-patterns.md

Read references/analysis-patterns.md for detailed extraction guidance per type.

Step 5: Export to Markdown

The orchestrator generates a scaffold:

cd <skill_dir>/scripts
python analyze_video.py "YOUTUBE_URL" --output ./analysis.md --depth standard --type auto

Flags:

  • --output PATH: Where to write (default: ./{sanitized_title}.md)
  • --depth quick|standard|deep: Analysis depth
  • --type auto|lecture|tutorial|interview|podcast|tech-talk|panel: Video type hint
  • --lang CODE: Transcript language (default: en)
  • --json: Output raw JSON instead of Markdown scaffold

The scaffold contains populated metadata and [TO BE ANALYZED] placeholders. Claude replaces these with actual analysis.

Preferred workflow: Run fetch_transcript.py to get JSON, analyze in context, then produce the final Markdown directly using assets/output-template.md as the structure guide. The orchestrator is useful for batch processing or when the user wants a file written.

Error Handling

Error Exit Code Cause Resolution
URL parse failure 1 Invalid or unsupported URL format Ask user for standard YouTube URL
No transcript 2 Video has no captions (manual or auto) Inform user; suggest a different video
Video unavailable 1 Private, deleted, or geo-blocked Inform user of the restriction
Age-restricted 1 Requires authentication Inform user; yt-dlp may work with cookies
Metadata fetch fail 0 yt-dlp network issue Transcript still works; metadata shows "Unknown"
Language unavailable 0 Requested lang not available Auto-falls back to available language
yt-dlp not installed 1 Missing dependency Run Step 0 dependency installation

Limitations

  • No visual analysis: Transcript-only; slides, diagrams, code on screen, and demos are not captured. Note this in output when relevant.
  • Auto-caption quality: Auto-generated captions may contain errors, especially for technical terms, proper nouns, and non-English accents.
  • Music videos: Lyrics may not be available as captions. Music-only content produces poor results.
  • Live streams: Ongoing live streams may have incomplete or unavailable transcripts.
  • Rate limiting: Excessive requests to YouTube may trigger temporary blocks. Space requests if processing multiple videos.
  • Language coverage: Best results for English. Other languages depend on caption availability and quality.
  • Speaker attribution: Transcripts rarely identify individual speakers. Claude infers from context where possible.