用途
youtube-downloader 是一个用于下载 YouTube 视频的技能，底层使用 yt-dlp 工具。它适合需要快速保存视频或音频、提取音频、按画质选择下载、下载播放列表或字幕的用户场景。
主要能力
- 自动安装：检查系统是否已安装 yt-dlp，若未安装则提示安装。安装方式包括 macOS Homebrew、pip 与 pipx。
- 灵活输入：支持完整 YouTube URL、短链接 youtu.be 以及仅视频 ID。
- 画质选择：支持 best、1080p、720p、480p、audio，默认 best。
- 格式选项：支持 mp4 视频与 mp3 音频，默认 mp4；audio 与 mp3 均转为 MP3。
- 进度跟踪：显示下载进度。
- 元数据嵌入：自动嵌入缩略图和元数据。
- 输出命名：文件按
<video-title>-<video-id>.mp4或.mp3命名。 - 播放列表下载：可下载整个播放列表，并可限制前 N 个视频。
- 字幕下载：支持写入字幕与自动生成字幕。
- 受限内容：支持通过浏览器 cookies 处理年龄限制内容。
使用方式
基本语法：
youtube-download <url-or-id> [quality] [format] [output-dir]
参数说明：
- URL 或 Video ID（必填）：完整 URL、短 URL 或视频 ID。
- Quality（可选，默认 best）：best、1080p、720p、480p、audio。
- Format（可选，默认 mp4）：mp4、mp3。
- Output Directory（可选，默认 ~/Downloads/YouTube）：自定义目录。
示例：
youtube-download "https://www.youtube.com/watch?v=dQw4w9WgXcQ" youtube-download dQw4w9WgXcQ youtube-download dQw4w9WgXcQ 720p youtube-download dQw4w9WgXcQ audio youtube-download dQw4w9WgXcQ best mp4 ~/Videos youtube-download dQw4w9WgXcQ "" mp3
播放列表下载：
youtube-download "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" youtube-download "playlist-url" best mp4 ~/Downloads "--playlist-end 10"
字幕下载：
youtube-download <video-id> best mp4 ~/Downloads "--write-subs --sub-lang en" youtube-download <video-id> best mp4 ~/Downloads "--write-auto-subs"
年龄限制视频：
youtube-download <video-id> best mp4 ~/Downloads "--cookies-from-browser chrome"
安装检查命令：
which yt-dlp brew install yt-dlp pip install yt-dlp pipx install yt-dlp
配置位置：~/.config/yt-dlp/config，可设置优先画质、嵌入缩略图、添加元数据与输出模板。
脚本位置：scripts/download.sh，可直接调用：
~/.claude/skills/youtube-downloader/scripts/download.sh <args>
适用场景
- 快速下载单个 YouTube 视频。
- 提取视频音频为 MP3。
- 按指定画质下载视频。
- 批量下载播放列表。
- 下载字幕或自动生成字幕。
- 处理年龄限制视频。
- 与其他技能集成，如 youtube-transcript、notebooklm、gen_wechat_article。
限制
- 需遵守版权与 YouTube 服务条款。
- 部分视频可能受地理限制或不可用。
- 直播流需要特殊处理。
- 超长视频可能耗时较长。
- 该工具仅用于个人、教育和合理使用目的。
错误处理
yt-dlp 未找到 → 提示安装；无效 URL/ID → 显示示例格式；视频不可用 → 建议检查视频是否存在；网络错误 → 建议重试；磁盘空间 → 下载前检查可用空间。
更新方式
brew upgrade yt-dlp pip install -U yt-dlp pipx upgrade yt-dlp