yt-search-download skill
Claude Code skill that searches YouTube, browses channels and downloads videos, audio and subtitles with yt-dlp.
- 118 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The script runs yt-dlp on your computer and writes files to `~/Downloads`.
- During a download yt-dlp reads browser cookies, and search requests go to YouTube Data API with your key.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/yt-search-downloadDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The script runs yt-dlp on your computer and writes files to `~/Downloads`.
- During a download yt-dlp reads browser cookies, and search requests go to YouTube Data API with your key.
This is third-party code. Review the repository files before installing.
What it does
The agent gets a YouTube search table with title, date, duration and view count. Search runs by keyword or inside one channel, with sorting by date, views or relevance and filters for duration and publication dates. Data comes from YouTube Data API v3. Selected videos are downloaded by yt-dlp: video up to 4K, audio-only MP3 or subtitles. Subtitles are saved as two files, SRT with timestamps and TXT with the same timestamps, so the text can go to a model for summarising. A single video can also be queried for details: duration, views and description.
Who it is for. Editors and analysts who follow YouTube channels on a topic: they find fresh episodes and pull podcast audio or the transcript of a talk.
Good fit when
- You want to see the latest episodes of a channel and pick by views.
- A podcast episode is needed as MP3 for offline listening.
- Lecture subtitles must become text for a model to summarise.
- A topic search should cover only the last few months.
- Several episodes of a channel have to be downloaded in a row.
Not a fit when
- A transcript by link is enough: a transcript MCP server avoids downloading files.
- You have no YouTube Data API key and cannot get one.
- The computer is shared and yt-dlp must not see your browser cookies.
- You have no right to a copy of the video and the rights holder did not allow downloading.
Example request
Show the five latest episodes of the @lexfridman channel by views and download subtitles for the most popular one.Limitations
The skill script does not start without a YouTube Data API v3 key in `YT_BROWSE_API_KEY` or `YOUTUBE_API_KEY`. Downloading requires an installed `yt-dlp`. During a download yt-dlp takes Chrome, Firefox or Safari cookies, so it reaches your browser session. Downloading videos may conflict with YouTube terms and copyright. The instructions ask the agent to add a Chinese translation to English titles. The last commit in the repository dates from March 2026.
How to disable. Delete the skill folder `~/.claude/skills/yt-search-download` and the key variable from `~/.zshrc`. Downloaded files sit in `~/Downloads` or in the `--dir` folder and are removed separately.
FAQ
How do I install yt-search-download in Claude Code?
Run `npx skills add joeseesun/yt-search-download`. Then set a YouTube Data API v3 key in `YT_BROWSE_API_KEY` and install `yt-dlp`, for example `brew install yt-dlp` on macOS.
Do I need an API key if I only download videos?
Yes, the script does not start without a key for any command. Create the key in Google Cloud Console by enabling YouTube Data API v3.
Which files appear when I download subtitles?
Two files: `.srt` with timestamps and `.txt` with the same timestamps for model summaries. English subtitles come first, and automatic ones are used when they are missing.
How do I sort results by views?
Add `-o viewCount` and the API does the sorting. For local sorting use `--sort-by views`, and cut duration with `--min-duration` and `--max-duration`.
Where do downloaded files go?
Into `~/Downloads`. `--dir` sets another folder, `-q 1080p` picks the video quality, and `--audio-only` keeps only MP3.
Discussion
No questions or reviews yet.
Related
SkillsTwelve skills teach an agent to read YouTube through the TranscriptOut service: transcripts, search and channels in one HTTPS call
yt-fts downloads subtitles of YouTube channels and playlists into SQLite and finds phrases with links to the exact second, plus semantic search and chat
A Claude Code skill that downloads a YouTube video, splits it into semantic chapters, cuts chosen clips, translates subtitles and burns bilingual ones in
YouTube Skills
YouTube Skills for AI Agents
A set of skills that gives an agent YouTube transcripts, video and channel search, and playlist extraction over one API
The /watch skill turns a link or file into frames and captions, or with a Gemini key hands the whole video to Google for the agent to answer from
watch-cli is a skill and CLI that hands an agent the frames and transcript of any social video so it can read the clip itself.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| yt-search-download (this card) | no | 118 | |
| YouTube Skills | no | 1,172 | returns transcripts, search and playlists through one third-party API; yt-search-download searches with a YouTube Data API key and downloads files through yt-dlp |
| YouTube Clipper Skill | no | 2,284 | cuts videos into chapters and burns in bilingual subtitles; yt-search-download stays with search, downloads and subtitle files |
README in short
The repository holds the SKILL.md instructions and the `scripts/yt_search.py` script. The README is in Chinese, with sample requests, typical workflows and a table of search parameters.
README badge
Original SKILL.md
--- name: yt-search-download description: | YouTube 视频搜索、下载视频、下载字幕工具。结合 YouTube Data API v3 进行高级搜索，yt-dlp 下载视频/音频/字幕。 核心能力：全站关键词搜索、频道浏览、按时间/播放量/相关度排序、下载视频、提取音频（MP3）、下载字幕（中英文）、查看视频详情。 触发场景（任何涉及 YouTube 的操作都应使用此 skill）： - 搜索类："搜索YouTube"、"YouTube搜索"、"找YouTube视频"、"搜索[频道名]最新视频"、"查找[人名]的YouTube"、"[人名]最近更新的YouTube"、"YouTube上有什么关于XXX的" - 频道浏览类："浏览频道"、"看看[频道名]最新视频"、"[人名]最近发了什么视频"、"[人名]YouTube更新"、"查看[频道名]的视频列表" - 下载视频类："下载YouTube"、"下载这个视频"、"下载YouTube视频"、"把这个视频下载下来"、"保存视频" - 下载音频类："提取音频"、"下载音频"、"YouTube转MP3"、"只要音频" - 下载字幕类："下载字幕"、"提取字幕"、"获取字幕"、"下载YouTube字幕"、"中文字幕"、"英文字幕"、"提取文字"、"视频转文字"、"获取视频文本" - 视频信息类："视频详情"、"视频信息"、"这个视频多长" 关键词匹配：只要用户消息中出现 "YouTube"、"油管"、"YT"、"yt" 加上搜索/下载/字幕/频道/视频等动作词，就应触发此 skill。 --- # YouTube 搜索 & 下载 基于 YouTube Data API v3 进行高级搜索，配合 yt-dlp 下载。 ## 前置条件 1. **YouTube API Key**： ```bash echo $YT_BROWSE_API_KEY ``` 如果为空：[Google Cloud Console](https://console.cloud.google.com/) → 启用 YouTube Data API v3 → 创建 API Key → 写入 `~/.zshrc`： ```bash export YT_BROWSE_API_KEY=your_key ``` 2. **yt-dlp**（下载用）： ```bash brew install yt-dlp # macOS pip install yt-dlp # 或 pip 安装 ``` ## 命令说明 脚本路径：`~/.claude/skills/yt-search-download/scripts/yt_search.py` ### 全站关键词搜索 ```bash python3 scripts/yt_search.py search "关键词" -n 20 ```