yt-dlp について
yt-dlp は、動画・音声 URL の情報確認、字幕抽出、承認後のメディアダウンロードを行うコマンドラインスキルです。字幕を優先する手順により、読み取り専用の確認、出力先の指定、ユーザー所有の Cookie の使用を徹底します。
主な機能
- 01読み取り専用の URL 情報確認
- 02字幕・文字起こしの抽出
- 03承認後のメディアダウンロード
- 04プレイリストの列挙と選択
- 05Cookie ファイルの検証
- 06JSON 形式の事前チェック
活用シーン
- 01動画のタイトルと字幕の確認
- 02メディアを取得せず字幕を保存
- 03承認済みメディアを指定先に保存
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/yt-dlpを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
evals/evals.jsonreferences/ethics-and-tos.mdformats-and-quality.mdtroubleshooting.mdscripts/check.pydoctor.pyprobe_url.pyscripts/asset_toolkit/validate_hooks.py詳細
yt-dlp
yt-dlp 用の CLI スキルです。読み取り専用の URL プローブ、字幕／トランスクリプトの抽出、任意でのメディアダウンロードに対応します。ダウンロードの前に、トランスクリプト優先プロトコルに従ってください。
対象範囲： yt-dlp がサポートする動画／音声ホスト、ユーザー所有の Cookie ファイル、プレイリストのメタデータ、明示的に指定されたディレクトリへのローカル出力。対象外： 静的ページの取得（Fetch MCP または curl を使用）、複数ソースにわたる幅広いリサーチ（research）、ffmpeg の変換レシピ（ffmpeg）、プラットフォームの利用規約の回避。
標準用語
| 用語 | 意味 | 該当しないもの |
|---|---|---|
| probe | --dump-json による読み取り専用のメタデータ取得。メディアは書き込みません | ダウンロード |
| transcript | 字幕をテキストファイルに保存すること。完全なダウンロードより優先します | デフォルトでの音声リッピング |
| download | プローブとユーザーの承認後にメディアデータを保存すること | 無断での一括取得 |
| playlist | 複数のエントリを含む URL。選択的にダウンロードする前に列挙します | 無条件でのプレイリスト全件ダウンロード |
| cookies | --cookies で指定する、ユーザー所有の Netscape Cookie ファイル | コミット済み、またはスキルに同梱されたシークレット |
| doctor | バイナリ、バージョン、ffmpeg の事前確認用 JSON レポート | URL に対するライブスモークテスト |
| format id | プローブから取得した yt-dlp の format_id（例：251、137+140） | 推測した拡張子 |
| manual sub | 投稿者がアップロードした字幕 | 自動生成字幕のみ |
| auto sub | プラットフォームが生成した字幕 | 正確性が保証された字幕 |
振り分け
$ARGUMENTS | モード | アクション |
|---|---|---|
probe <url> / metadata <url> / info <url> | プローブ | 同梱の probe_url.py を実行します。タイトル、ID、再生時間、字幕を要約します |
transcript <url> / subs <url> / captions <url> | トランスクリプト | まずプローブを実行し、動画をダウンロードせずに利用可能な最適な字幕を抽出します |
download <url> / fetch <url> / save <url> | ダウンロード | まずプローブを実行し、権利と形式を確認してから、明示的に指定された出力ディレクトリにダウンロードします |
playlist <url> | プレイリスト | プレイリストを許可してプローブを実行し、エントリを一覧表示します。選択的なダウンロードは承認後に限ります |
cookies <path> / cookies check <path> | Cookie | ユーザー所有の Cookie ファイルのパスを検証します。リポジトリにコピーしてはいけません |
doctor / preflight | Doctor | scripts/doctor.py --format json を実行します |
| 自然言語：「この動画は何ですか」「字幕を取得して」「これをダウンロードして」 | 自動 | 以下のプロトコルに従って、プローブ → トランスクリプト → ダウンロードに振り分けます |
| (空) | ヘルプ | モード、プロトコル、倫理に関する案内、使用例を表示します |
自動検出のヒューリスティック
- URL と subtitle、caption、transcript、CC などの語句がある場合 → トランスクリプト（それでも最初にプローブを実行します）。
- URL と download、save、mp4、audio、rip がある場合 → ダウンロード（それでも最初にプローブと承認が必要です）。
- URL と playlist、channel list、all videos がある場合 → プレイリスト。
- URL のみ、または「このリンクは何ですか」の場合 → プローブ。
cookies.txtで終わるパス、またはログイン／認証への言及がある場合 → Cookie の案内を行い、その後--cookiesを指定して再プローブします。- 判別できない場合 → メタデータのみ、トランスクリプト、ダウンロードのどれを希望するか確認します。
トランスクリプト優先プロトコル
以下のステージを順番に実行してください。プローブを省略してはいけません。 トランスクリプトでは要件を満たせないと確認できるか、ユーザーがメディアファイルを明示的に希望するまでは、ダウンロードしてはいけません。
ステージ 1 — Doctor（セッションごとに 1 回、またはエラー発生後）
uv run python scripts/doctor.py --format json
ok: false の場合、またはチェック結果の status: fail がある場合は停止します（yt-dlp バイナリが見つかりません）。
ステージ 2 — プローブ（トランスクリプトまたはダウンロードの前に必須）
uv run python scripts/probe_url.py --url 'https://…' --format json
ユーザー所有の Cookie を使う場合：
uv run python scripts/probe_url.py --url 'https://…' --cookies "$HOME/.config/yt-dlp/cookies.txt" --format json
プレイリスト URL（エントリを列挙し、プローブに --allow-playlist を指定します）：
uv run python scripts/probe_url.py --url 'https://www.youtube.com/playlist?list=PL…' --allow-playlist --format json
プローブの JSON から、id、title、duration、uploader、availability、subtitles／automatic_captions の言語、推奨する format_id の候補を報告します。形式を選択する際は、references/formats-and-quality.md を読み込んでください。
Stage 3 — Transcript（ダウンロードより優先）
字幕がある場合は、動画をダウンロードせずにテキストを抽出します。
yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs 'en.*,en' \
--convert-subs srt --sub-format srt \
-o '%(title).200B.%(ext)s' \
--paths home:"$HOME/Downloads/yt-dlp/transcripts" \
'URL'
両方ある場合は、自動生成字幕より手動字幕を優先します。.srt / .vtt の保存先を要約し、タイミング行を削除してプレーンテキストにするか確認します。字幕がない場合はその旨を伝え、文字起こしのためのダウンロード（コストが高く、権利に関わるため）を行う前にユーザーに確認します。
Stage 4 — Download（明示的な承認が必要）
実行前に、以下を確認します。
- references/ethics-and-tos.md に記載のとおり、ユーザーにコンテンツを保存する権利があること（個人利用／アーカイブ／フェアユースの状況）を確認します。
- 出力先ディレクトリを確認します（デフォルト：
$HOME/Downloads/yt-dlp/media/）。 - プローブ結果から形式を確認します（
-f FORMATまたは妥当なデフォルト：bv*+ba/b）。
mkdir -p "$HOME/Downloads/yt-dlp/media"
yt-dlp -f 'bv*+ba/b' \
--paths home:"$HOME/Downloads/yt-dlp/media" \
-o '%(playlist_index)s-%(title).200B.%(ext)s' \
'URL'
出力先、形式 ID、ファイルサイズ、ffmpeg による結合が実行されたかどうかを報告します。
モードの詳細
Probe モード
- 同梱の
probe_url.py（yt-dlp --dump-json --no-downloadのラッパー）を使用します。 - 読み取り専用です。cwd またはリポジトリ内に書き込みは行いません。
- 年齢制限付き、またはログイン限定のコンテンツの場合は停止し、Cookies に案内します。認証情報を推測してはいけません。
Transcript
- テキストが必要な場合、動画／音声のダウンロードをデフォルトにしてはいけません。
- 常に
--skip-downloadを使用します。 - 複数の言語がある場合は、ユーザーが指定した言語を選ぶか、プローブ結果にあるフォールバックリストから
enを選びます。
Download
- 単一 URL の場合、ユーザーがプレイリストを指定していない限り、デフォルトで
--no-playlistを使用します。 - 明示的に範囲を確認せずに、チャンネル全体／アーカイブを一括で処理してはいけません。
- チャットログ内のコマンドに Cookie を埋め込んではいけません。
$COOKIES環境変数またはユーザーが指定したパスのみを参照します。
Playlist
- プレイリストを有効にしてプローブします。
uv run python scripts/probe_url.py --url 'PLAYLIST_URL' --allow-playlist --format json
- 番号付きの項目（インデックス、タイトル、再生時間）を提示します。
- 承認を得てから、選択されたインデックスのみをダウンロードします（
--playlist-items 1,3,5）。プレイリスト全体を確認せずにダウンロードしてはいけません。
Cookies
- ユーザーが所有する Cookie ファイルのみを使用します。パスはユーザーのホームディレクトリ配下、またはユーザーが明示的に指定したものに限ります。
- Cookie ファイルをコミットしたり、リポジトリに保存したり、スキルパッケージに同梱したりしてはいけません。
- エクスポート手順（ブラウザー拡張機能 → Netscape
cookies.txt）は references/ethics-and-tos.md に記載されています。 - 読み取り可能か検証します。
test -r "$HOME/.config/yt-dlp/cookies.txt" && echo readable
ユーザーがパスを指定した場合に限り、プローブ／ダウンロード時に --cookies PATH を渡します。
Doctor
uv run python scripts/doctor.py --format json
JSON の ok、summary、各チェックの status を解析します。fail の場合はワークフローを停止します。warn（例：ffmpeg が見つからない）は参考情報として扱います。
Help
ディスパッチテーブル、文字起こし優先の手順、デフォルトのパス、倫理に関する参考リンクを表示します。
Gallery（引数なし）
$ARGUMENTS が空の場合は、よく使われる呼び出し例を提示します。
| # | タスク | 例 |
|---|---|---|
| 1 | 事前チェック | /yt-dlp doctor |
| 2 | メタデータをプローブ | /yt-dlp probe https://www.youtube.com/watch?v=… |
| 3 | 字幕を取得 | /yt-dlp transcript https://www.youtube.com/watch?v=… |
| 4 | ダウンロード（承認後） | /yt-dlp download https://www.youtube.com/watch?v=… |
| 5 | プレイリストを列挙 | /yt-dlp playlist https://www.youtube.com/playlist?list=… |
| 6 | ユーザー所有の Cookie | /yt-dlp cookies ~/.config/yt-dlp/cookies.txt |
番号、ディスパッチテーブルのモードを選ぶか、URL を貼り付けて、メタデータ、字幕、ダウンロードのどれが必要かを伝えてください。
重要なルール
- トランスクリプトの取得やダウンロードの前にプローブする — 常に
probe_url.pyまたは同等の--dump-json --no-downloadを使用してください。 - ダウンロードの前にトランスクリプトを取得する — 字幕がある場合は、字幕を抽出する
--skip-downloadを優先してください。 - ダウンロードには明示的な承認を得る — 権利、対象範囲、出力ディレクトリ、形式を確認してください。
- ユーザー所有のCookieのみを使用する — Cookieをコミットしたり、リポジトリにコピーしたり、Cookieのパスをでっち上げたりしないでください。
- 利用規約の回避方法を指南しない — references/ethics-and-tos.md を参照してください。DRMの回避やペイウォールの迂回を求める依頼には対応しないでください。
- Fetch MCPの対象ではありません — 静的HTML、ドキュメントページ、yt-dlp以外のホストには、このスキルではなくFetch MCPまたは
curlを使用してください。 - ffmpegスキルの対象ではありません — リマックス、トランスコード、クリップ、波形の作成が必要な場合は、ダウンロード後に
/ffmpegを使用してください。 - 出力権限は最小限にする — ユーザーが承認したディレクトリ内にのみ書き込み、エージェントのリポジトリツリーには書き込まないでください。
- 出所を報告する — 最終的な概要に、タイトル、URL、エクストラクター、形式ID、出力パスを記載してください。
トラブルシューティング
エクストラクターのエラー、地域制限、署名エラー、ffmpegの結合に関する問題については、references/troubleshooting.md を参照してください。
参考資料
| ファイル | 使用する場面 |
|---|---|
| ethics-and-tos.md | 権利、Cookie、対応を拒否する境界 |
| formats-and-quality.md | -f 形式文字列の選択 |
| troubleshooting.md | doctorのチェックに合格した後に発生するエラー |
スクリプト
| スクリプト | 用途 |
|---|---|
scripts/doctor.py | JSON形式の事前チェック：yt-dlp、バージョン、ffmpeg |
scripts/probe_url.py | 読み取り専用の --dump-json ラッパー |
scripts/check.py | スキルのマニフェストと評価を検証 |
例
# Preflight
uv run python scripts/doctor.py --format json
# Probe
uv run python scripts/probe_url.py --url 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' --format json
# Transcript (after probe shows subs)
yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs en -o '%(id)s' \
--paths home:"$HOME/Downloads/yt-dlp/transcripts" 'URL'
# Download (after user approval)
yt-dlp -f 'bv*+ba/b' --paths home:"$HOME/Downloads/yt-dlp/media" -o '%(title).200B.%(ext)s' 'URL'