youtube-search

YouTubeSearch

クエリで YouTube を検索し、メタデータとエンゲージメント指標を含む、構造化された人が読みやすい結果を返します。

できること

YouTube に対して yt-dlp の検索を実行し、最近の期間（デフォルトは 6 か月）で絞り込んだ上位 N 件（デフォルトは 20 件）の結果を返します。各結果には次の情報が含まれます。

• タイトルとURL
• チャンネル名と登録者数
• 視聴回数と再生時間
• アップロード日
• エンゲージメント比率（視聴回数／登録者数）— チャンネルの視聴者数に対して、動画の成績が良かったか、振るわなかったかをすばやく把握するための指標です

数値は人が読みやすい形式（例：1.2M、45.3K）で表示されます。結果は区切り線で分けられ、簡単に確認できます。

要件

• yt-dlp がインストールされ、PATH に含まれていること
• jq がインストールされ、PATH に含まれていること
• bc がインストールされていること（macOS/Linux では標準で利用できます）

使い方

同梱のスクリプトを実行します。

bash ~/.claude/skills/YouTubeSearch/scripts/yt-search.sh "<search query>" [--count N] [--months N]

パラメーター

フラグ	デフォルト	説明
（位置引数）	—	検索クエリ（必須）
--count	20	返す結果の数
--months	6	過去 N か月以内の動画のみを含めます

使用例

# Basic search — top 20 results from last 6 months
bash ~/.claude/skills/YouTubeSearch/scripts/yt-search.sh "kubernetes security best practices"

# Narrow to 5 results from the last month
bash ~/.claude/skills/YouTubeSearch/scripts/yt-search.sh "rust async tutorial" --count 5 --months 1

# Broader window — last 2 years
bash ~/.claude/skills/YouTubeSearch/scripts/yt-search.sh "home lab setup" --months 24

エンゲージメント比率の見方

視聴回数と登録者数の比率は、注目すべきコンテンツを見つけるのに役立ちます。

• > 1.0x — 動画の視聴回数がチャンネルの登録者数を上回っています。そのトピックが視聴者の関心を集めた、またはアルゴリズムによって動画が推薦されたことを示す強い指標です。
• 0.3x - 1.0x — すでに確立されているチャンネルでは一般的な範囲です。
• < 0.3x — リーチが平均を下回っています。トピックがニッチである、サムネイルやタイトルの効果が低かった、またはチャンネルの視聴者が関心を失った可能性があります。

この指標は、同じトピックの動画を比較する場合に最も役立ちます。小規模なチャンネルで比率が 5.0x なら、コンテンツが視聴者の心をつかんだ可能性があります。

Claude の使い方

ユーザーが YouTube の検索や動画の検索を依頼した場合：

1. ユーザーのクエリと指定されたフラグを使ってスクリプトを実行します
2. 結果を提示します。スクリプトの出力はターミナルで読みやすい形式になっています
3. ユーザーが分析（例：「この中で見る価値があるのはどれですか？」）を求めた場合は、エンゲージメント比率と視聴回数を使って注目すべき動画を示します
4. 多くの結果で登録者数が「N/A」と表示されても、これは正常です。yt-dlp は検索結果からチャンネルのメタデータを常に取得できるわけではありません

トラブルシューティング

• 結果がない：クエリの範囲を広げるか、--months の値を増やしてください
• 動作が遅い：各結果でメタデータの取得が必要です。結果を速く得るには --count の値を減らしてください。
• 登録者数が「N/A」と表示される：yt-dlp は検索からチャンネルのフォロワー数を解決できない場合があります。他のフィールドは引き続き入力されます。

---

注意点

• API の order=date を指定しても関連性によるランキングが適用されます — 最近アップロードされた動画の順位が下がる場合があります。日付順と関連性順の 2 つの検索結果を結合する方法が回避策です。
• クォータはプロジェクトごとに 1 日単位で設定されています — 検索はコストが高く（1 クエリあたり 100 単位）、短時間に大量に実行すると、その日はプロジェクトが利用停止になります。
• regionCode パラメーターによって結果が変わります — 同じクエリでも地域が異なると別の動画が返されます。デフォルトでは閲覧者の IP アドレスから地域が判定されます。
• 文字起こし API は検索 API とは別です — 文字起こしが利用可能かどうかは動画ごとに異なります。文字起こしがない動画もあり、その場合 API はエラーを返しません。
• チャンネル ID とチャンネルのユーザー名：ハンドル（@name）、従来のユーザー名、ID はそれぞれ異なる識別子です。解決には明示的なチャンネル一覧の呼び出しが必要です。
• アップロード者によって埋め込みが禁止されている動画：検索結果に表示される場合がありますが、埋め込みを行う下流のツールは警告なしで失敗します。status.embeddable を確認してください。