youtube-transcript（YouTube 成绩单）

YouTube Transcript Skill

Use this skill to fetch transcripts and transcript languages with a standalone Python CLI tool (no MCP server).

Prerequisites

Install dependency:

python3 -m pip install youtube-transcript-api

Package Knowledge: youtube-transcript-api

Teach and apply these package facts when reasoning about failures or writing code:

• Package role:
• fetch transcript text for a YouTube video
• list available transcript languages
• detect generated vs manual captions
• Common API patterns across versions:
• static-style: YouTubeTranscriptApi.get_transcript(video_id, languages=[...])
• class list: YouTubeTranscriptApi.list_transcripts(video_id)
• instance-style (newer variants): api = YouTubeTranscriptApi(); api.list(video_id); api.fetch(video_id, languages=[...])
• Typical transcript item fields:
• text
• start
• duration
• Typical language fields:
• language_code
• language
• is_generated
• Common exception names you should expect and map:
• InvalidVideoId
• TranscriptsDisabled
• NoTranscriptFound
• VideoUnavailable
• TooManyRequests
• CouldNotRetrieveTranscript
• Reliability guidance:
• try requested language first, then fallback to first available language
• for AI summary workflows, prefer transcript retrieval with --include-timestamps false
• keep tool output structured JSON so downstream AI agents can parse reliably

Core Contract

This skill provides transcript retrieval. Summary and analysis must be done by AI.

• Use the CLI for data retrieval (transcript, languages).
• Do summary/key points/quotes using an AI agent.
• Prefer sub-agent summarization when available to preserve main-context space.

Workflow

1. Extract a YouTube URL or 11-character video ID.
2. Decide output type:

• Full transcript requested: fetch transcript and return it.
• Summary requested: fetch transcript first, then summarize with AI.

1. Context-saving rule for summary:

• If sub-agents are available, run transcript retrieval + summarization in a sub-agent.
• If sub-agents are unavailable, summarize in the current agent after retrieval.

1. For long videos, prefer transcript fetch with --include-timestamps false unless timestamps are explicitly requested.

Sub-Agent Guidance

When available, use this flow:

1. Sub-agent runs transcript fetch command.
2. Sub-agent summarizes transcript based on user intent.
3. Sub-agent returns concise summary (and optional key quotes).
4. Main agent returns the synthesized result without dumping full raw transcript unless the user asks.

Commands

Get transcript with timestamps:

python3 youtube_transcript_tool.py \
  --mode transcript \
  --url "https://www.youtube.com/watch?v=VIDEO_ID" \
  --lang en \
  --include-timestamps true

Get transcript as plain text (recommended for summarization):

python3 youtube_transcript_tool.py \
  --mode transcript \
  --url "VIDEO_ID" \
  --include-timestamps false

List available transcript languages:

python3 youtube_transcript_tool.py \
  --mode languages \
  --url "https://youtu.be/VIDEO_ID"

Output Contract

Default output is JSON (--json true).

Success payload:

• ok: true
• includes mode, video_id, and mode-specific payload

Error payload:

• ok: false
• error.code
• error.message
• error.hint

Use --json false for readable text output.

Error Handling Guidance

When the tool fails, surface the hint directly and suggest one practical next step:

• invalid_video_id: check URL format or use raw 11-char ID
• transcripts_disabled: captions disabled by publisher
• no_transcript: try another language or auto-generated captions
• video_unavailable: video is private/deleted/restricted
• rate_limited: retry later or from a different network
• dependency_missing: install youtube-transcript-api

Defaults

• --lang en
• --include-timestamps true
• --json true