Youtube Analyzer

YouTubeAnalyzer Skill

Purpose: Comprehensive YouTube video analysis with content-type detection, specialized format workflows (tutorial/finance/general/etc.), multi-agent orchestration for long videos, and optional GitHub repo cross-referencing for tutorial content.

Architecture: This file is the orchestration spine — 4 phases with blocking gates. Mechanical detail is progressively disclosed via references/*.md (loaded by phase) and content-analysis rules live in workflows/*.md (passed into sub-agents).

Invocation Flags

Parse the user's invocation BEFORE Phase 1. Flags pre-set Phase 2 outputs and suppress the matching prompt.

Syntax accepted (any of these forms):

• --chat <url> — deliver inline, no file written
• --chat: <url> / --chat=<url>
• --document <url> (explicit; default behavior)

Parsing rules:

1. Strip the flag token (and any trailing : or =value) before extracting the URL
2. If a flag was passed: set mode and SKIP Q5
3. Both flags present → last one wins
4. Unknown flags (--foo) → warn user inline, proceed without it

When a flag was detected, surface it: "Flag detected: --chat → mode preset to chat (Q5 skipped)."

Required External Tools

Verify these are installed before Phase 1. If missing, surface a single install message and stop:

• yt-dlp — pip install yt-dlp or brew install yt-dlp
• youtube_transcript_api — pip install youtube-transcript-api
• bun — curl -fsSL https://bun.sh/install | bash

command -v yt-dlp && command -v youtube_transcript_api && command -v bun

Capture invocation cwd

BEFORE Phase 1, capture the working directory the user invoked the skill from. Store as invocationCwd. Used by Step 4.7 (post-save copy prompt).

pwd

Persist that value through all phases. Sub-agents may run elsewhere — only the orchestrator's initial cwd counts.

Runtime Requirements

This skill runs from any agent context (the primary thread, or a delegated agent like general-purpose) provided the calling agent has: Agent/Task, AskUserQuestion, Write/Edit, Bash, Read, Grep. Agents lacking any of these (e.g. Explore) should defer — auto-detect via tool availability, not by name.

The terms "the orchestrator" and "the calling agent" both refer to whatever agent is executing this skill.

Orchestration Model

The orchestrator NEVER does analysis work directly. All content extraction, processing, and writing is delegated to specialized sub-agents via the Task tool. The orchestrator coordinates, routes, and writes files (in mode == "document") once results return.

EVERY phase has a BLOCKING GATE. Do not proceed until the gate checklist is satisfied.

PHASE 1: SOURCE SELECTION

BLOCKING GATE 1

PRE-CONDITIONS: External tools verified
MANDATORY OUTPUTS:
  - transcriptPath: string     # Path to loaded clean transcript file
  - transcriptSource: string   # "yt-dlp" | "youtube_transcript_api"
  - videoMetadata: object      # { title, channel, duration?, upload_date?, video_id?, topic? }
  - wordCount: number          # Estimated word count
  - transcriptQuality: string  # "HIGH" | "MEDIUM" | "NONE" | "UNAVAILABLE"

Mechanics: Read references/source-selection.md. It covers URL extraction, the 4-tier transcript fallback chain, and VTT cleanup.

Auto-detect: If the user already provided a YouTube URL, skip the URL prompt and go directly to metadata extraction.

Gate 1 checklist (verify ALL):

• transcriptPath exists and is readable
• transcriptSource is set
• videoMetadata.title and videoMetadata.channel are non-empty
• wordCount > 0
• transcriptQuality is set

"Phase 1 complete. {wordCount} words loaded from {transcriptSource}. Proceeding to config..."

PHASE 2: INTERACTIVE CONFIG

BLOCKING GATE 2

PRE-CONDITIONS:
  - transcriptPath exists and is readable
  - videoMetadata is populated (title + channel at minimum)
MANDATORY OUTPUTS:
  - category: string            # business, finance, technology, etc.
  - format: string              # tutorial | course | finance | interview | lecture | general
  - outputSelection: string[]   # Selected output types
  - depth: string               # "quick" | "standard" | "deep"
  - focusArea: string           # Format-specific focus (or "none")
  - repoUrl: string | null      # GitHub repo URL (tutorials only)
  - confidence: number          # Detection confidence percentage
  - mode: string                # "document" | "chat" — see Q5 (or pre-set by flag)

Q1: Content Type Confirmation

Detection: Run the content-type detector with metadata extracted in Phase 1:

bun run ${CLAUDE_PLUGIN_ROOT}/scripts/detect-content-type.ts --url "URL"
# OR pipe metadata JSON
echo '{"title":"...","description":"...","tags":[...]}' | bun run ${CLAUDE_PLUGIN_ROOT}/scripts/detect-content-type.ts --json

If confidence < 60%, present alternatives. See content-types.md for full keyword lists and scoring.

{
  "questions": [{
    "question": "I detected this as {category}/{format} ({X}% confidence). Is that correct?",
    "header": "Content type",
    "options": [
      {"label": "Yes, proceed", "description": "Use {category}/{format} as detected"},
      {"label": "Change category", "description": "Keep {format} format, pick a different category"},
      {"label": "Change format", "description": "Keep {category} category, pick a different format"},
      {"label": "Change both", "description": "Select both category and format manually"}
    ],
    "multiSelect": false
  }]
}

Q2: Output Selection (multiSelect: true)

The available options depend on format:

tutorial / course: Detailed Summary · Production Checklist · Tool/Package Inventory · Key Quotes finance: Strategy Breakdown · Action Items · Risk Analysis · Key Quotes general / interview / lecture: Detailed Summary · Deep Analysis · Key Insights · Key Quotes

Default if user says "all" or doesn't specify: Detailed Summary + Key Quotes.

Q3: Output Depth

A) Quick (~500w) · B) Standard (~1500w, recommended) · C) Deep dive (~3000w+)

Q4: Format-Specific

• Tutorial / Course: "GitHub repo for this tutorial? Paste URL or skip." (stored as repoUrl)
• Finance: "Actionable takeaways or theoretical analysis?"
• General / Interview / Lecture: "Any specific angle to emphasize?"

Q5: Delivery Mode

SKIP this question entirely if mode was pre-set by an invocation flag. Otherwise:

{
  "questions": [{
    "question": "How should the analysis be delivered?",
    "header": "Delivery",
    "options": [
      {"label": "Save to disk", "description": "Default — write a permanent markdown file at the resolved output directory. Best when you want to reference this later."},
      {"label": "Discuss in chat", "description": "Run the full analysis but return the rendered markdown inline so we can talk through it. No file is created."}
    ],
    "multiSelect": false
  }]
}

Map: Save to disk → mode = "document"; Discuss in chat → mode = "chat". Default: mode = "document".

Gate 2 checklist (verify ALL):

• category is a valid category from content-types.md
• format is one of: tutorial, course, finance, interview, lecture, general
• outputSelection has ≥1 item
• depth is set
• focusArea is set (can be "none")
• repoUrl is a string or null
• mode is "document" or "chat"

"Phase 2 complete. {category}/{format} at {confidence}% confidence. Depth: {depth}. Outputs: {outputSelection}. Mode: {mode}. Proceeding to scaling..."

PHASE 3: MULTI-AGENT SCALING + REPO EXPLORATION

BLOCKING GATE 3

PRE-CONDITIONS:
  - category, format, outputSelection, depth all set
  - transcriptPath exists
MANDATORY OUTPUTS:
  - partitionStrategy: string         # "single" | "multi"
  - agentCount: number                # 1 for single, 2+ for multi
  - chunkPaths: string[]              # Chunk file paths
  - repoExploreResults: object | null # Mermaid diagrams from repo exploration

Mechanics: Read references/scaling-and-repo-explore.md. It covers token estimation, the scaling decision table (≤30K / 30–100K / >100K), partition execution, and the 3-explorer parallel repo exploration (StructureExplorer, DependencyExplorer, PatternExplorer — all subagent_type: Explore).

Trigger for repo exploration: repoUrl is non-null AND format is tutorial or course. Run in parallel with transcript partitioning.

Gate 3 checklist (verify ALL):

• partitionStrategy is set
• agentCount ≥ 1
• chunkPaths has ≥1 path; each path exists and is readable
• repoExploreResults is set (object or null)
• If repoUrl was provided, either repoExploreResults has content OR a skip reason is documented

"Phase 3 complete. {agentCount} agent(s) ready. {repoExploreResults ? 'Repo exploration complete with Mermaid diagrams.' : ''} Dispatching {format} workflow..."

PHASE 4: WORKFLOW DISPATCH + SYNTHESIS

BLOCKING GATE 4

PRE-CONDITIONS:
  - All Gate 3 outputs satisfied
  - category, format, outputSelection, depth, focusArea, mode all set
MANDATORY OUTPUTS:
  - workflowLoaded: string                # Workflow file that was loaded
  - outputPath: string | null             # Canonical output path (null when mode == "chat")
  - renderedMarkdown: string | null       # Rendered markdown (populated when mode == "chat")
  - copyPath: string | null               # Optional cwd copy path from Step 4.7 (null if declined or chat mode)

Final-phase reporting (branch on mode):

If mode == "document" AND copyPath is set: "Analysis complete. Saved to {outputPath}. Copy also at {copyPath}." If mode == "document" AND copyPath is null: "Analysis complete. Saved to {outputPath}." If mode == "chat": "Analysis complete — rendered below for discussion. No file written." Then print renderedMarkdown inline so it enters the conversation context.

Step 4.1: Dispatch

Dispatch table:

Why general-purpose on sonnet: Workflow agents follow precise file instructions to extract structured data and produce markdown. general-purpose executes workflow instructions directly without loading specialized agent personalities.

Pre-dispatch verification:

1. Format maps to a valid workflow file in the table above
2. Read the workflow file contents
3. Agent prompt includes the full workflow file
4. Agent receives: chunk path + user config + video metadata
5. subagent_type: "general-purpose" and model: "sonnet" set explicitly

Step 4.2: Launch Workflow Agents

Per chunk, launch a Task agent with subagent_type: "general-purpose", model: "sonnet". Each agent receives:

1. Its chunk file path (or full transcript if single agent)
2. User config: { category, format, outputSelection, depth, focusArea }
3. Video metadata: { title, channel, duration, upload_date, video_id }
4. Workflow instructions (full content of the appropriate workflows/*.md)
5. Instruction: "Analyze ONLY your assigned chunk. Do not read beyond your assigned content."

Parallel: if agentCount > 1, launch ALL chunk agents in parallel (single message, multiple Task calls).

Step 4.3: Synthesis

Launch ONE synthesis agent (general-purpose, sonnet) with a fresh context. Pass it references/output-templates.md (YAML frontmatter, Production Checklist section, Ground Truth Architecture section, Package Version table) so it can apply the templates without polluting the orchestrator context.

Synthesis agent receives:

1. Merged chunk analysis results
2. User config (including mode)
3. Video metadata
4. repoExploreResults if non-null (Mermaid diagrams)
5. Target output path — only if mode == "document"; pass null for chat
6. Contents of references/output-templates.md

Synthesis agent does:

1. Merge + deduplicate chunk analyses
2. Apply output template based on format + outputSelection
3. Generate YAML frontmatter
4. If tutorial + repoExploreResults: add Ground Truth Architecture section with Mermaid diagrams
5. Tutorials: extract package list for the package database (always — runs regardless of mode)
6. Branch on mode:
   • mode == "document" → write file to output path. Return { outputPath, renderedMarkdown: null, wordCount, packagesFound[] }
   • mode == "chat" → skip file write. Return { outputPath: null, renderedMarkdown: <full markdown including frontmatter>, wordCount, packagesFound[] }. Orchestrator prints renderedMarkdown inline.

Step 4.4: Package DB Integration (Tutorials Only)

For each package found:

bun run ${CLAUDE_PLUGIN_ROOT}/scripts/package-db.ts add \
  --name "{packageName}" --display-name "{displayName}" \
  --version-mentioned "{version}" --category "{packageCategory}" \
  --source "{videoUrl}"

The package database lives at ~/.config/youtube-analyzer/package-db.json (created on first use).

Version lookup (post-analysis, batches of 5; skip packages checked within 7 days):

• npm: WebFetch on https://registry.npmjs.org/{pkg}/latest
• PyPI: WebFetch on https://pypi.org/pypi/{pkg}/json
• Other: WebSearch

Update the package database with --latest-version. Status thresholds and the Package Version table format live in references/output-templates.md. Schema details: package-database-schema.md.

Step 4.5: Output Path Resolution

Skip this step entirely when mode == "chat" — set outputPath = null and continue to cleanup.

For mode == "document": read references/output-paths.md. The skill resolves the output directory from ${CLAUDE_PROJECT_DIR}/.claude/youtube-analyzer.local.md if present, otherwise prompts the user once via AskUserQuestion and persists the answer there for next time.

Step 4.6: Cleanup

rm -rf "{scratchpad}/repo-explore/"

Step 4.7: Optional Copy to Invocation Cwd

Skip when mode == "chat" — no file exists to copy. Set copyPath = null.

After the canonical file is written and cleanup is done, ask the user whether to also drop a copy in the cwd captured at skill invocation. Use AskUserQuestion:

{
  "questions": [{
    "question": "Also save a copy to the project you ran this from? Cwd: {invocationCwd}",
    "header": "Copy to repo",
    "options": [
      {"label": "No, just the configured output dir", "description": "File stays at {outputPath} only. No copy created."},
      {"label": "Yes, copy to cwd root", "description": "Drop a copy at {invocationCwd}/{filename}"},
      {"label": "Yes, custom subpath", "description": "I'll specify a subdirectory under {invocationCwd}"}
    ],
    "multiSelect": false
  }]
}

Branch on response:

• No → copyPath = null. Done.
• Yes, copy to cwd root → targetDir = invocationCwd. Proceed to copy.
• Yes, custom subpath → ask one follow-up free-text question: "Subpath under {invocationCwd} (e.g., docs/research, leave blank for cwd root):". Resolve targetDir = invocationCwd + (subpath || ""). Proceed to copy.

Copy execution:

mkdir -p "{targetDir}"
cp "{outputPath}" "{targetDir}/{filename}"

Set copyPath = "{targetDir}/{filename}".

Safety guards:

• If invocationCwd is unset (rare — only if cwd capture failed), skip the prompt and set copyPath = null.
• If invocationCwd equals the configured output directory, skip the prompt — copying onto itself is a no-op.
• If the destination file already exists, append -2, -3, etc. to the filename rather than overwriting.

Example

Input: "Analyze this video: https://youtube.com/watch?v=xyz123"

• Phase 1: Auto-detect URL → yt-dlp metadata → youtube_transcript_api transcript → 12K words.
• Phase 2: Detect finance/finance at 87%. User confirms. Selects: Strategy Breakdown + Action Items. Depth: standard. Focus: actionable takeaways.
• Phase 3: 12K tokens → single agent. No repo exploration.
• Phase 4: 1 FinanceAgent analyzes full transcript. Synthesis writes to {configured-output-dir}/2026-04-27-dividend-portfolio-strategy.md. Step 4.7 then asks whether to copy a duplicate into invocationCwd.

For --chat invocation, Phase 4 returns renderedMarkdown inline, skips Steps 4.5 and 4.7, and never writes a file.

Quick Reference

Scripts (in ${CLAUDE_PLUGIN_ROOT}/scripts/): clean-transcript.ts, detect-content-type.ts, partition-transcript.ts, package-db.ts · External: yt-dlp, youtube_transcript_api, bun

Agent types:

• Workflow agents: general-purpose + sonnet, given full workflow file content
• Repo explorers: Explore (Structure / Dependency / Pattern)
• Synthesizer: general-purpose + sonnet, given merged results + references/output-templates.md

Workflow files: workflows/{tutorial,finance,general,repo-exploration}-workflow.md

Sequence: verify external tools → Phase 1 (Gate 1) → Phase 2 (Gate 2) → Phase 3 (Gate 3) → Phase 4 (Gate 4) → report. No phase may be skipped.