YouTube Summary Skill

Summarize YouTube videos by extracting transcripts via TranscriptAPI.com and generating structured summaries.

Setup

Prerequisites

• Python 3.10+
• A TranscriptAPI.com account ($5/mo for 1,000 transcripts)
• Optional: pass (Unix password manager) for secure key storage

Installation

• Sign up at transcriptapi.com and get your API key
• Provide the API key via one of these methods:
• Environment variable (simplest): export TRANSCRIPT_API_KEY="your-key-here"
• pass password store (most secure): pass insert transcriptapi/api-key
• Install Python dependencies:

pip install -r skills/youtube-summary/requirements.txt

Detection

Trigger on messages containing YouTube URLs matching any of:

• youtube.com/watch?v=ID
• youtu.be/ID
• youtube.com/shorts/ID
• m.youtube.com/watch?v=ID
• youtube.com/live/ID

⚠️ Critical Rules

• NEVER use web_search as a fallback. If transcript extraction fails, report the error and stop.
• NEVER fabricate transcript content. Only summarize what the extraction script returns.
• Always run the extraction script. Do not skip it, even for well-known videos.

Workflow

Step 1: Extract transcript

If using pass:

_yt_key_file=$(mktemp) && pass transcriptapi/api-key > "$_yt_key_file" && python3 skills/youtube-summary/scripts/extract.py "YOUTUBE_URL_OR_ID" --api-key-file "$_yt_key_file"; rm -f "$_yt_key_file"

If using env var:

python3 skills/youtube-summary/scripts/extract.py "YOUTUBE_URL_OR_ID"

Security note: The pass + temp file approach avoids exposing the key in ps output or shell history. The env var approach is simpler but the key is visible in the process environment.

Parse stdout:

• PROGRESS: lines → relay to user as status updates (optional)
• ERROR: lines → relay error to user, stop
• RESULT: line → parse the JSON after RESULT: — contains: header, transcript, language, tokens, title, channel, duration_str

Step 2: Summarize the transcript

Use the extracted transcript to generate a summary. The summary language must match the transcript language (from the language field).

If tokens < 50000 — single-pass: summarize the full transcript in one request.

If tokens ≥ 50000 — tell the user it's a long video and summarize the first ~40K tokens with a note that it was truncated.

Default summary format (use when no custom prompt given):

{header}

**TL;DR:** 2-3 sentence summary.

**Key Points:**
• Point one
• Point two
• (3-7 total)

**Notable Quotes:** (only if genuinely quotable lines exist)
> "Quote here"

Custom prompt — if the user included text alongside the URL, append it as additional instructions for the summary.

Step 3: Reply

• Keep output under 4000 characters for Telegram
• If the summary would exceed 4000 chars, send the TL;DR first, then the rest as a follow-up
• Always include the header line from the extraction result

Error Handling

• ERROR: API_ERROR: Invalid API key → "TranscriptAPI key is invalid. Check pass transcriptapi/api-key."
• ERROR: No transcript available → "This video doesn't have captions available."
• ERROR: Video not found → "Couldn't find that video — double-check the URL."
• Any other ERROR: → relay the message as-is. Do NOT fall back to web_search.

Why TranscriptAPI?

YouTube aggressively blocks datacenter/IPv6 ranges from accessing transcripts. Most cloud VPS (Hetzner, DigitalOcean, AWS, etc.) are blocked — direct transcript fetching fails for most videos when running from a server.

TranscriptAPI.com proxies requests through residential IPs, bypassing these blocks reliably. The $5/mo plan covers 1,000 transcript fetches.

💡 Tip: Add instructions after the URL to customize the summary (e.g. "focus on the technical details").