search-youtube

YouTube リサーチ

マルチプラットフォーム対応の動画リサーチツールキットです。ツールキット（個別操作）と リサーチ（自律型の検索から要約までのパイプライン）の2つのモードで動作します。すべての操作は、 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py の単一の CLI を使用します。

任意のサブコマンドの全フラグを確認するには、python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py <subcommand> --help を実行してください。

ツールキットモード

目的を絞った操作には、個別のサブコマンドを呼び出します。ユーザーが 特定のアクション（文字起こし、検索、メタデータ、音声、チャンネルのスキャン）を依頼した場合の デフォルトモードです。

検索

クエリに一致する動画を検索します。メタデータ付きの構造化された結果を返します。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py search "<query>" --count 10

結果を絞り込むには、--min-duration 600（秒）、--after 20250101（YYYYMMDD）、 --min-views 50000 などのフィルターを追加します。フィルターは取得後にクライアント側で適用されるため、 補正用にツールが自動的に多めの結果を取得します。デフォルトの出力形式は JSON です。人が読みやすい形式にするには、-f text を追加します。

文字起こし

字幕をダウンロードして整形し、LLM で扱いやすいテキストにします。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py transcript "<url>"

デフォルトでは、整形済みの文章を標準出力に出力します。タイミング情報付きの SRT を出力するには、 --timestamps を追加します。~/youtube-research/<topic>/ に保存するには、--save -t <topic> を追加します。 ダウンロード前に利用可能な字幕言語を一覧表示するには、--lang all を使用します。フォールバック順は、 手動字幕、その後に自動生成字幕です。指定した言語の字幕がない場合は、終了コード 4 で終了します。

メタデータ

ダウンロードせずに、動画の詳細情報を抽出します。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py metadata "<url>"

返される情報：タイトル、説明、チャンネル、再生時間、チャプター、再生回数と高評価数、タグ、利用可能な 字幕言語、サムネイル URL です。再生リスト内の項目一覧を表示するには、--playlist を追加します。

音声

指定した形式で音声をダウンロードします。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py audio "<url>" --audio-format mp3 -t <topic>

~/youtube-research/<topic>/audio/ に保存します。対応形式：mp3、m4a、opus、wav。 常にディスクに保存されます（音声は標準出力に出力できません）。成功すると、ファイルパスを出力します。

チャンネル

チャンネルのコンテンツをスキャンします。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py channel "<url-or-@handle>" --limit 20

タブに対応しています：--tab videos（デフォルト）、shorts、streams、playlists。 --after／--before（YYYYMMDD）で絞り込みます。再生回数の多い順に並べるには、--sort views を使用します。

バッチ処理

search 以外のすべてのサブコマンドは、複数の URL を処理するために --batch <file>（または標準入力には --batch -）を受け付けます。 1行につき URL を1つ指定します。# または ; で始まる行はスキップされます。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py transcript --batch urls.txt --save -t <topic>

リサーチモード

YouTube を情報源としてトピックを「リサーチ」「調査」する、または「詳しく知りたい」とユーザーが依頼した場合に有効にします。 人気動画では十分に扱われないことの多い、ニッチなトピックや新興トピック向けに設計された、 適応型の複数ラウンドによる探索パイプラインです。

ラウンド 1：発散的検索

トピックのさまざまな側面を網羅する、4～6個のクエリ候補を作成します：

• ツール／概念の正確な名称（例："openclaw"）
• ツール名とエコシステムの文脈（例："openclaw claude code"）
• ツールが解決する課題（例："claude code documentation framework"）
• ワークフロー／デモを想定した表現（例："openclaw walkthrough demo"）
• 該当する場合は、別名、略称、よくあるスペルミス

クエリ候補ごとに Task エージェントを1つずつ起動し、同時にそれぞれが次を実行します：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py search "<query-variant>" --count 15

すべての結果を集め、動画 ID を基準に重複を除去します。すべてのスレッドを合わせて、 30～50件の一意な候補を目指します。

第 1 ラウンドの評価：ニッチなトピックを優先するヒューリスティック

ニッチなトピック、新興トピック、最先端技術に関するトピックでは、次のシグナルが品質を予測します。

ポジティブなシグナル（活用してください）：

• タイトルにツールや概念が具体的に記載されている（「2025年のおすすめAIツール」ではない）
• チャンネル登録者数が少ない（5万人未満）。新しい技術の場合、教育者がそのトピックを見つける前に実践者が公開するためです
• 技術的で具体的な説明（コード、設定、アーキテクチャ、コマンドに言及している）
• 構成の整ったコンテンツ：チャプター、タイムスタンプ、または詳細な説明がある
• 最近アップロードされている

ネガティブなシグナル（ニッチなトピックでは危険信号として扱ってください）：

• 再生回数が10万回を超える。狭いトピックでは、初心者向けの内容やクリックベイトであることが多いです
• 新しいツールについて、タイトルに「初心者向けチュートリアル」や「完全ガイド」とある
• 関連性のない多くのトピックを扱う大規模な総合チャンネル

候補の統合プールから6～10件を選択します。最も優れた結果を出したチャンネルを記録してください。これらは第2ラウンドで対象にします。

第 2 ラウンド：チャンネルの発見と絞り込み

第1ラウンドで有力な結果が見つかった各チャンネルについて、最近の動画を確認します。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py channel "<channel-url>" --limit 20

また、第1ラウンドで有力だったタイトルや説明に登場する具体的な用語を使って、絞り込んだ検索クエリを1～2件実行します。新たな候補があれば、プールに追加します。

品質ゲート： 第1ラウンドの候補が弱い場合（一般的なタイトル、再生回数の多い総合的なコンテンツばかり、トピックを具体的に扱ったものがない場合）は、その旨をユーザーに伝え、トランスクリプトに進む前に検索クエリを再構成して、もう1ラウンド検索します。

第 3 ラウンド：確認とトランスクリプトの取得

候補を拡充したプールから、第1ラウンドの基準に従って動画を4～7本選択します。ダウンロードに進む前に、メタデータを抽出して関連性を確認します。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py metadata "<url>"

トランスクリプトは並列でダウンロードします。動画が2本の場合でも、動画ごとに必ず1つのTaskエージェントを起動してください。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py transcript "<url>" --save -t <topic>

各トランスクリプトを読み、調査結果をレポートにまとめます。YouTubeの情報源間で主張が食い違う場合や、疑問に答えていない場合は、WebSearchまたはbrave-cliを使って主張を相互参照したり、不足情報を補ったりしてください。

調査レポートの形式

調査結果を、次の構成に沿ったMarkdownレポートとして提示します。

• タイトルと、調査の問いを要約した1段落
• 主な調査結果（全情報源を通じて最も重要なポイントを3～7個、箇条書きで記載）
• 情報源間で一致している点（複数の動画で確認できる内容）
• 意見が分かれている点（情報源間で矛盾する点と、その情報源を明記）
• 独自の洞察（他の動画では繰り返されていない、個々の動画に含まれる注目すべき点）
• 調査範囲の不足（情報源全体で取り上げられていない点）
• 情報源の表：使用した各動画のタイトル、チャンネル、長さ、URL

個々の主張の出典となる動画を明記します。トランスクリプトにタイムスタンプが保持されている場合は、それも記載します。今後の参照に備えて、すべてのトランスクリプトをトピックのディレクトリに保存します。レポートの構成例はexamples/research-report.mdを参照してください。

調査の組み合わせ

サブコマンドと標準的なUnixツールを組み合わせるパイプラインのパターンについては、references/cli-reference.mdを参照してください（search → jq → batch transcript）。

エラーからの復旧

終了コード	意味	復旧方法
0	成功	—
1	使用方法のエラー	正しい構文を--helpで確認する
2	yt-dlpが見つからない	次のコマンドでインストールするようユーザーに伝えます：pip install yt-dlp
3	ネットワーク／ダウンロードエラー	URLが有効か確認します。非公開または制限付きのコンテンツでは、--cookies <browser>を試します
4	結果なし	トランスクリプトの場合：利用可能な言語を一覧表示するため、--lang allを試します。検索の場合：クエリの範囲を広げるか、フィルターを削除します

プラットフォームに関する注意事項

YouTube以外のURLを処理する場合、または見慣れないプラットフォームでyt-dlpコマンドが終了コード3で失敗した場合は、references/platforms.mdを読み込みます。主なプラットフォームはYouTubeですが、yt-dlpがサポートするURL（Vimeo、Twitter、Twitchなど）であれば使用できます。

トランスクリプトを取得したら、その内容を読み、主要なポイントをユーザー向けに要約します。ただし、ユーザーが生の出力のみを求めている場合は除きます。