How to use the YouTube Transcript Downloader agent skill

What the skill lets the agent do

The skill downloads transcripts (subtitles and captions) from YouTube videos, including both manually created and auto-generated transcripts. It also fetches the video's metadata and cover image. The source says it needs no API key or browser: it calls YouTube's InnerTube API directly and falls back to yt-dlp when YouTube blocks that direct path.

The output can be a Markdown file with timestamps or an SRT subtitle file. The skill can also list the caption languages available for a video, translate the transcript, split it into chapters taken from the video description, and prepare a file for speaker identification. Results are cached locally, so reformatting the same video does not hit YouTube again.

• Accepted inputs: full watch URLs, youtu.be short URLs, embed URLs, Shorts URLs and bare video IDs.
• Output formats: text (.md) and srt (.srt).
• The skill does not transcribe audio. It only extracts captions that already exist.

Install the skill from the ZIP download

Download the skill as a ZIP file from the agent-skills directory page. Then choose one of two ways to install it.

For Claude Code, unzip the package into your personal skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill available only in that project. For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check what the skill needs before you run it

The skill runs scripts written in TypeScript and needs the Bun runtime. The SKILL.md says the agent uses bun if it is installed, or npx to run bun if npx is available. If neither is present, the agent should suggest installing bun. No API key is required.

yt-dlp is optional. It is used as a fallback when YouTube blocks the direct API path. The source says that if yt-dlp is needed but missing, the agent should decide how to make it available and continue rather than pushing that decision to you.

If yt-dlp needs logged-in cookies, you can set YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER to a browser such as chrome, safari or firefox, or to a profile such as chrome:Profile 1. The value is passed to yt-dlp --cookies-from-browser.

• Bun runtime, or npx to run bun
• Optional: yt-dlp as a fallback
• Optional: YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER for logged-in cookies
• Network access to YouTube

Trigger the skill with natural requests

You do not need to type commands. The skill activates when you ask for a YouTube transcript, subtitles, captions or a video cover, or when you paste a YouTube URL and ask for its text or cover image. The skill's description lists phrases such as get YouTube transcript, download subtitles, get captions, video thumbnail and video cover image, and it also accepts Chinese phrases such as YouTube字幕 and 视频封面.

The agent runs the script behind the scenes. You can also ask for specific formats, languages or chapters in the same request.

• Get the transcript for this video: https://www.youtube.com/watch?v=VIDEO_ID
• Download the subtitles for this talk in Japanese and Chinese, then give me an SRT file.
• What languages are available for this video's captions?
• Get the cover image for this video.
• Translate the transcript of this lecture into Simplified Chinese.

Run the script directly (optional)

The SKILL.md shows the commands the agent runs. {baseDir} is the folder containing SKILL.md, and ${BUN_X} is bun or npx -y bun. The default output is Markdown with timestamps in English. Replace the placeholders with real values when you run them yourself.

Quote YouTube URLs in single quotes. In zsh, the ? in a URL is treated as a wildcard and causes a no matches found error.

• --languages zh,en,ja sets language priority order (default en)
• --format srt writes an SRT subtitle file
• --no-timestamps removes timestamps
• --chapters adds chapter segmentation from the video description
• --speakers prepares raw output for speaker identification, which needs AI post-processing
• --list shows available transcripts to stdout only
• --refresh ignores cached data and re-fetches
• -o or --output-dir sets where files are saved (default folder youtube-transcript)

Find your output and cache files

Each video is saved under youtube-transcript/ in a folder named by channel and title. The folder holds meta.json, the raw snippets, a sentence-segmented transcript, the cover image in imgs/cover.jpg, and transcript.md or transcript.srt depending on the format. A .index.json file maps video IDs to folders so the cache can be found.

On later runs for the same video, cached data is used with no network calls. Requesting a different language refreshes the cache automatically.

• meta.json: title, channel, description, duration, chapters
• transcript-raw.json: raw snippets from the YouTube API
• transcript-sentences.json: sentence-split transcript
• imgs/cover.jpg: video thumbnail
• transcript.md or transcript.srt: the file you asked for