This skill should be used when the user asks to "download YouTube transcript", "get YouTube captions", "extract YouTube subtitles", or needs to retrieve transcript from a YouTube video.
Use this skill when:
This skill guides downloading YouTube transcripts using yt-dlp and formatting them as structured HTML.
Core principle: Create HTML transcript with title, chapter headings (using video chapters if available), and paragraph content. Abort cleanly if transcript unavailable.
Create one file: transcript.html - Structured HTML with:
<h1> title from video<h2> chapter headings with start timestamp only (format: MM:SS - Title)<p> paragraph content under each chapterChapter sources (in priority order):
| Task | Command | Notes |
|---|---|---|
| Check transcript availability | yt-dlp --list-subs URL |
Run first to verify |
| Get video metadata + chapters | yt-dlp --print "%(title)s|%(chapters)s" URL |
Chapters may be null |
| Download transcript | yt-dlp --write-auto-sub --sub-lang en --sub-format vtt --skip-download URL |
VTT has timestamps |
| Download manual subs (fallback) | yt-dlp --write-sub --sub-lang en --sub-format vtt --skip-download URL |
If auto unavailable |
yt-dlp --list-subs VIDEO_URL
If no subtitles available:
yt-dlp --print "%(title)s|%(description)s" VIDEO_URL
Check description for chapter markers:
MM:SS Title or HH:MM:SS Title on separate lines0:00 Introduction
2:30 Main Topic
5:15 Conclusion
If chapters exist in description:
MM:SS - Title (start timestamp and title only)If no chapters in description:
# Try auto-generated first
yt-dlp --write-auto-sub --sub-lang en --sub-format vtt --skip-download VIDEO_URL
# If auto unavailable, try manual
yt-dlp --write-sub --sub-lang en --sub-format vtt --skip-download VIDEO_URL
Parse VTT file:
<00:00:00.000>, <c>, etc.00:00:00.000 --> 00:00:00.000If using video chapters (from description):
MM:SS - Chapter TitleIf creating auto-generated chapters:
MM:SS - Generated Title<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Video Title Here</title>
</head>
<body>
<h1>Video Title Here</h1>
<h2>0:00 - Introduction</h2>
<p>First paragraph of this chapter...</p>
<p>Second paragraph of this chapter...</p>
<h2>2:30 - Main Topic</h2>
<p>Content for this section...</p>
</body>
</html>
Requirements:
<h1> with video title<h2> with format MM:SS - TitleRemove temporary VTT file after processing.
Wrong: Always creating auto-generated 1-3 minute chapters even when video has chapter markers in description.
Right:
Wrong (no chapters):
<body>
<h1>Video Title</h1>
<p>All transcript text...</p>
</body>
Right:
<body>
<h1>Video Title</h1>
<h2>0:00 - Introduction</h2>
<p>Transcript text for this chapter...</p>
<h2>2:30 - Next Topic</h2>
<p>More content...</p>
</body>
Wrong:
<h2>Introduction</h2>
<h2>0:00 Introduction</h2>
<h2>00:00:00.000 - Introduction</h2>
<h2>0:00 - 2:30 - Introduction</h2>
Right:
<h2>0:00 - Introduction</h2>
Wrong:
webfetch https://www.youtube.com/watch?v=...
Right:
yt-dlp --write-auto-sub --sub-format vtt --skip-download URL
Wrong (using first sentence verbatim):
<h2>0:00 - Can you break down the difference between capitalist, socialist, commu</h2>
Right (concise summary):
<h2>0:00 - Economic Systems Overview</h2>
Guidelines for auto-generated titles:
If you catch yourself thinking:
<h1> with video title.<h2> chapters.MM:SS - Title.1. User requests YouTube transcript
↓
2. Check transcript availability (yt-dlp --list-subs)
↓
3a. If unavailable → Abort with message
3b. If available → Continue
↓
4. Get video title and description
↓
5. Check description for chapter markers
↓
6a. Chapters found → Use those timestamps/titles
6b. No chapters → Generate 1-3 min sections
↓
7. Download transcript (VTT format)
↓
8. Process VTT: remove tags, extract timestamps, clean text
↓
9. Group content by chapters
↓
10. Create transcript.html:
- <h1> with title
- <h2> chapters with MM:SS - Title
- <p> paragraphs under each chapter
↓
11. Clean up temporary files
Video with chapters in description:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Understanding Economic Systems</title>
</head>
<body>
<h1>Understanding Economic Systems</h1>
<h2>0:00 - Introduction</h2>
<p>Welcome to this video on economic systems. Today we'll explore the key differences...</p>
<h2>2:30 - Capitalism Explained</h2>
<p>Capitalism is a system where capital goes to those who can generate the best returns...</p>
<h2>5:45 - Socialist Approaches</h2>
<p>In socialist systems, the government plays a larger role in economic decisions...</p>
<h2>8:20 - Conclusion</h2>
<p>Each system has tradeoffs. Understanding these helps us make informed decisions...</p>
</body>
</html>
Key features:
MM:SS - Title format (from video's chapter markers)