pp-youtube

YouTube — Printing Press CLI

前提条件：CLI をインストールする

このスキルは youtube-pp-cli バイナリを使用します。**このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。**インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使用してインストールします。バイナリのインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin がデフォルトです。

   npx -y @mvanhorn/printing-press-library install youtube --cli-only
   

2. 確認します：youtube-pp-cli --version
3. このスキルを実行するエージェント／ランタイムで、表示されたインストール先ディレクトリが $PATH に含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go を直接インストールする方法に切り替えてください（Go 1.26.6 以降が必要です）。この方法では $GOPATH/bin（デフォルトは $HOME/go/bin）にインストールされるため、代わりにそのディレクトリを $PATH に追加してください。

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/youtube/cmd/youtube-pp-cli@latest

インストール後に --version が「command not found」と表示される場合、ランタイムからバイナリのディレクトリを $PATH 経由で参照できていません。確認が成功するまで、スキルのコマンドを実行しないでください。

市場調査や競合調査で重要となる YouTube Data API v3 の読み取り機能を、すべてのパラメーターを指定して利用し、競合モニタリング用に設計されたローカルの SQLite データバンクにデータを蓄積します。約 15 社の競合を watch で登録し、1 回あたり約 20～40 クォータ単位で monitor による更新を行います。さらに、velocity、growth、breakouts、comments-mine、packaging を使って蓄積されたスナップショットを最新の市場情報に変換します。更新の遅い分析プラットフォームでは、こうした情報の提供が 1～2 週間遅れます。

この CLI を使用する場面

YouTube の市場調査や競合調査を行うタスクでは、いつでもこの CLI を利用してください。競合チャンネルの固定リストを経時的に追跡する、現在再生回数を伸ばしている動画を測定する、ニッチ市場で新たにブレイクしている動画を見つける、コメントから視聴者の反応を掘り起こす、パッケージ分析用にタイトル、サムネイル、フックを収集するといった用途に適しています。更新の遅い外部分析プラットフォームではなく、自分で所有し定期的に更新するデータバンクに基づいて回答する場合に最適なツールです。

使用しない場面

次の用途にはこの CLI を使用しないでください。

• 自分のチャンネルの非公開分析情報（収益、視聴維持率、デモグラフィック、トラフィックソース）には使用しないでください。これらは OAuth 専用の YouTube Analytics API の対象であり、この CLI では意図的に扱いません。
• 動画のアップロード、編集、評価、削除、またはチャンネルの管理には使用しないでください。書き込み操作はすべて対象外です。
• 動画や音声のメディアのダウンロードには使用しないでください。メディアファイルには yt-dlp を使用してください。
• ニッチ間の外れ値スコアや収益化の推定値など、市場全体を対象とする計算済みの判断には使用しないでください。そうした用途には厳選された分析データベースを使用します。この CLI が扱うのは、追跡対象チャンネルの最新データです。

独自の機能

この API に対して、これらの機能を利用できる他のツールはありません。

競合モニタリングマシン

• watch — モニタリング対象として追跡する競合チャンネルを、独自の型付きウォッチリストテーブルに登録します。

  追跡する市場を一度定義すれば、それ以降のすべてのモニタリングコマンドはチャンネルを再指定せずに実行できます。

  youtube-pp-cli watch add @mkbhd --json
  

• monitor — ウォッチリストに登録したすべてのチャンネルを1回の実行で更新します：統計のスナップショット、新しいアップロード、最近の動画統計の再スナップショットを取得します。

  1つのコマンドでデータバンクを最新の状態に保ち、市場に関する回答を数週間前ではなく数時間前の情報に基づいたものにできます。

  youtube-pp-cli monitor --json
  

• velocity — 実際のスナップショット間の差分から算出し、追跡中の動画のうち、現在最も速く視聴回数を伸ばしているものを確認できます。

  現在の市場の動向、つまり2週間前ではなく今日注目を集めているものがわかります。

  youtube-pp-cli velocity --json
  

• growth — 日付付きのローカルスナップショット間で、チャンネル単位の登録者数、視聴回数、アップロード数の差分を確認できます。

  外部の履歴サービスを使わずに、競合が加速しているかどうかをエージェントに判断させることができます。

  youtube-pp-cli growth @mkbhd --json
  

• backfill — チャンネルの全アップロード履歴を統計情報とともに、1つのコマンドでローカルデータバンクに取り込みます。

  競合ごとに一度実行すれば、それ以降はそのチャンネルに関する質問にオフラインで無料で回答できます。

  youtube-pp-cli backfill @mkbhd --json
  

• workspace — 名前付きデータバンクを使用します：競合モニタリングマシンを1つのデータベースに保持し、別のデータベースで新しいニッチを調査して、瞬時に切り替えられます。

  本番用のウォッチリストデータバンクに影響を与えることなく、ニッチごとにクリーンな調査用サンドボックスをエージェントに立ち上げさせることができます。

  youtube-pp-cli workspace list --json
  

• auth keys — 名前付きのYouTube APIキーを複数保存して瞬時に切り替えられます。必要に応じて、1つのキーが割り当て上限に達した際に --rotate で自動的に別のキーへ切り替えることもできます。

  最初のキーの1日あたりの割り当て上限を使い切っても、人手を介さずにエージェントが大規模な収集作業を完了できます。

  youtube-pp-cli auth keys list --json
  

新たな市場の発見

• breakouts — 検索フィルターを組み合わせてマトリックス（検索語 x アップロード期間 x 動画の長さ x 地域）を作成し、検索結果をチャンネル規模と結び付けて、勢いのある新着動画をランキングします。

  分析が遅いプラットフォームに情報が届く数週間前に、アップロードから数日でニッチ市場の急上昇動画を見つけられます。

  youtube-pp-cli breakouts "berlin history" --days 14 --json
  

• comments-mine — コメントを型付きの全文検索可能なテーブルに同期し、「いいね」が多いコメント、キーワードの出現頻度、視聴者からの質問を報告します。

  所有するデータから、チャンネル全体にわたって視聴者が何を称賛し、質問し、不満に思っているかという、素早く得られる視聴者の反応を確認できます。

  youtube-pp-cli comments-mine @mkbhd --json
  

• packaging — タイトル、サムネイル（ローカルの画像ファイルとしてダウンロード）、および文字起こし冒頭のフックテキストを収集し、パッケージングテーブルに保存します。

  スクレイピングや手作業での収集をせずに、サムネイルとフックを分析するために必要な情報をすべてマルチモーダルエージェントに渡せます。

  youtube-pp-cli packaging @mkbhd --json
  

コマンドリファレンス

youtube — 市場および競合分析向けの YouTube Data API v3（読み取り専用、api-key）

• youtube-pp-cli youtube activities-list — リソースの一覧を取得します。必要に応じて絞り込みできます。
• youtube-pp-cli youtube captions-list — リソースの一覧を取得します。必要に応じて絞り込みできます。
• youtube-pp-cli youtube channel-sections-list — リソースの一覧を取得します。必要に応じて絞り込みできます。
• youtube-pp-cli youtube channels-list — リソースの一覧を取得します。必要に応じて絞り込みできます。
• youtube-pp-cli youtube comment-threads-list — 動画、チャンネル、またはスレッド ID で絞り込み可能な、トップレベルのコメントスレッド一覧を取得します。
• youtube-pp-cli youtube i18n-languages-list — リソースの一覧を取得します。必要に応じて絞り込みできます。
• youtube-pp-cli youtube i18n-regions-list — リソースの一覧を取得します。必要に応じて絞り込みできます。
• youtube-pp-cli youtube playlist-items-list — リソースの一覧を取得します。必要に応じて絞り込みできます。
• youtube-pp-cli youtube playlists-list — リソースの一覧を取得します。必要に応じて絞り込みできます。
• youtube-pp-cli youtube search-list — 検索リソースの一覧を取得します。
• youtube-pp-cli youtube video-categories-list — リソースの一覧を取得します。必要に応じて絞り込みできます。
• youtube-pp-cli youtube videos-list — リソースの一覧を取得します。必要に応じて絞り込みできます。
• youtube-pp-cli youtube channel-uploads — チャンネルの最新アップロード動画を一覧表示します（@handle または channelId を解決し、アップロード動画の再生リストを順にたどります）。
• youtube-pp-cli youtube playlist-enrich — 1 回の並行呼び出しで、再生リストを動画ごとのメタデータ、文字起こし、説明文に展開します。
• youtube-pp-cli youtube search-bulk — 1 回の呼び出しで複数の検索語句を YouTube で検索し、各語句の上位 N 件を返します。
• youtube-pp-cli youtube videos-comments — ページをまたいで高評価順に並べた、動画の人気コメントを取得します。
• youtube-pp-cli youtube videos-embed — 動画の埋め込み HTML、iframe、または Markdown スニペットを出力します。
• youtube-pp-cli youtube videos-enrich — 1 回の呼び出しで、1 本の動画のメタデータ、文字起こし、説明文を取得します。
• youtube-pp-cli youtube videos-links — 動画の説明文からリソースリンクを抽出します（短縮リンクを展開し、ソーシャルメディア関連のノイズを除外します）。
• youtube-pp-cli youtube videos-related — 関連動画を検索します。同じチャンネルの動画よりも、共通トピックによる順位付けを優先します。
• youtube-pp-cli youtube videos-transcript — OAuth なしで文字起こしを取得します（timedtext；--format markdown|text|json）。

適切なコマンドを見つける

実行したいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接問い合わせてください。

youtube-pp-cli which "<capability in your own words>"

which は、自然言語での機能に関する問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は 1 件以上の候補が見つかったことを意味し、終了コード 2 は確度の高い候補がないことを意味します。その場合は --help を参照するか、より具体的な問い合わせを使用してください。

レシピ

監視用マシンを立ち上げる

youtube-pp-cli watch add @mkbhd --json

競合はそれぞれ 1 回だけ追加します。バックフィルで履歴を作成し、監視を実行するたびに最新の状態に保ちます。

今日の変化

youtube-pp-cli velocity --agent --select items.title,items.views_per_day

追跡対象の動画について、スナップショット間の再生数の伸びを、エージェントに必要なフィールドに絞って表示します。

ニッチ分野で急成長中の動画を見つける

youtube-pp-cli breakouts "berlin history" --days 14 --json

フィルターを連鎖させたマトリックスをチャンネル規模と結合し、過去 2 週間にアップロードされた、登録者あたりの再生数が多い動画を抽出します。

エージェント向けパッケージング資料

youtube-pp-cli packaging @mkbhd --json

タイトル、サムネイルのローカルファイル、フックのテキストを並べて表示します。マルチモーダルなパッケージング分析にすぐ利用できます。

視聴者が繰り返し尋ねていること

youtube-pp-cli comments-mine @mkbhd --json

同期されたコメントテーブルから、人気コメント、キーワードの頻度、抽出した質問を表示します。

認証の設定

YOUTUBE_API_KEY に YouTube Data API v3 のキーを設定してください（console.cloud.google.com の APIs & Services > Credentials で作成するか、auth set-token で一度だけ保存します）。環境変数のキーは保存済みのキーより優先されます。doctor に auth_source env と表示され、HTTP 400 'API key not valid' エラーで呼び出しに失敗する場合は、環境変数に設定されたキーが古くなっています。環境変数の設定を解除するか、更新してください。読み取り専用の公開データ操作のみをサポートしており、OAuth は一切使用しません。

youtube-pp-cli doctor を実行して、設定を確認してください。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションに展開されます：--json --compact --no-input --no-color。

• パイプ可能 — stdout に JSON、stderr にエラーを出力します

• フィルタリング可能 — --select でフィールドの一部を保持します。ドット区切りのパスはネストされた構造をたどり、配列では各要素を走査します。応答量の多い API でコンテキストを小さく保つうえで重要です：

  youtube-pp-cli youtube activities-list --part snippet --agent --select contentDetails,etag,id
  

• プレビュー可能 — --dry-run でリクエストを送信せずに表示します

• オフライン対応 — 同期／検索コマンドでは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトを表示せず、すべての入力をフラグで指定します

• 読み取り専用 — 作成、更新、削除、公開、コメント、賛成票、招待、注文、送信など、状態を変更するリクエストにはこの CLI を使用しないでください

応答エンベロープ

ローカルストアまたは API から読み取るコマンドは、出力を出所情報のエンベロープでラップします：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データには .results を解析し、ライブデータかローカルデータかを判断するには .meta.source を確認してください。人間が読みやすい N results (live) という概要は、stdout がターミナルであり、かつ機械可読形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合に限り、stderr のみに出力されます。パイプ経由／エージェントからの利用と、形式を明示した実行では、stdout に純粋な JSON が出力されます。

パスと状態

エージェントは、CLI のパス解決機能を実行時の契約の一部として扱ってください：

• 1 回の実行では --home <dir> を使用するか、YOUTUBE_HOME=<dir> を設定して、4 種類すべてのパスを 1 つのルート配下に移動します。

• 特定の種類のパスだけを別の場所にする必要がある場合に限り、種類ごとの環境変数 YOUTUBE_CONFIG_DIR、YOUTUBE_DATA_DIR、YOUTUBE_STATE_DIR、YOUTUBE_CACHE_DIR を使用します。

• 解決の優先順位は、種類ごとの環境変数、--home、YOUTUBE_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME）、プラットフォームのデフォルトの順です。

• config には config.toml やプロファイルなどの設定が含まれます。data には credentials.toml、data.db、Cookie、認証サイドカーが含まれます。state には永続化されたクエリ、ジョブ、teach.log が含まれます。cache には再生成可能な HTTP／キャッシュファイルが含まれます。

• 保存されたシークレットは、data ディレクトリ内の credentials.toml にあります。互換性のため、従来の config.toml にあるシークレットも読み込まれ、最初の認証書き込み時に config.toml から削除されます。

• youtube-pp-cli doctor --fail-on warn を実行すると、パスと認証情報の保存場所に関する警告を表示できます。agent-context は、解決済みのディレクトリが必要なエージェント向けに、スキーマ v4 の paths ブロックを公開します。

• MCP では、MCP ホストの設定を通じて移動先を指定してください。MCP バイナリは CLI フラグを継承しません：

  {
    "mcpServers": {
      "youtube": {
        "command": "youtube-pp-mcp",
        "env": {
          "YOUTUBE_HOME": "/srv/youtube"
        }
      }
    }
  }
  

⚠️ 2 つのファイルは、意図的に移動可能なツリーの外側にあるプラットフォームの設定ディレクトリ（macOS では ~/Library/Application Support/youtube-pp-cli/）に保存されます。workspaces.json（ワークスペースのレジストリはワークスペースのホームの外に置く必要があります。そうでないと切り替えが自己参照になるためです）と keyring.json（クォータはワークスペース単位ではなくキー単位のためです）です。その結果、--home／YOUTUBE_HOME ではキーリングやワークスペースのレジストリは分離されません。分離されたホームの下でも、keys add/use と workspace create/use は共有状態を変更します。

フリートでの優先順位：継承された種類ごとの環境変数は、その種類について明示的な --home より優先されます。フリート全体で継続的に適用する設定には YOUTUBE_HOME または種類ごとの環境変数を使用し、--home は 1 回の実行に限って使用してください。環境変数を解除しても移動は元に戻りません。YOUTUBE_HOME を消去する前に手動でファイルを移動してください。そうしないと、doctor は以前のルートに残された認証情報を見つけられません。

アナリスト用データベース（SQL スキーマ）

アナリストコマンドはすべて、ローカルの SQLite データベースに書き込みます。これは doctor --json がストアのパスとして報告するファイルです。ファイル名は有効な API キーに応じて変わり（data-<hash>.db）、workspace を切り替えると、完全に別のデータベースに切り替わります。エージェントは 2 つの方法でこのデータベースをクエリします。MCP の sql ツール（読み取り専用、検証済み）と、MCP の search ／ CLI の search 全文検索機能です。

テーブル	1 行あたりの内容	主な列
yt_watchlist	追跡対象の競合チャンネル	channel_id、handle、title、note、added_at、last_monitored_at
yt_channel_snapshots	取得時点ごとのチャンネル	channel_id、captured_at、subscriber_count、view_count、video_count
yt_videos	既知の動画（ディメンションテーブル）	video_id、channel_id、title、published_at、duration_seconds、is_short、description
yt_video_snapshots	取得時点ごとの動画	video_id、captured_at、view_count、like_count、comment_count
yt_comments	同期済みコメント	comment_id、video_id、channel_id、author、text、like_count、published_at、is_reply
yt_comments_fts	yt_comments.text の FTS5 インデックス	MATCH クエリ。挿入／更新／削除トリガーによって同期されます
yt_packaging	収集したパッケージングアセット	video_id、channel_id、title、thumb_url、thumb_path、hook_text、view_count、captured_at、hook_error、thumb_error
yt_monitor_runs	1 回の monitor 実行	run_id、started_at、finished_at、channels、new_videos、video_snapshots、comments_synced、quota_units_est

monitor、backfill、breakouts、comments-mine、packaging はこれらのテーブルに自動的に書き込みます（ライトスルー）。velocity と growth は連続する yt_video_snapshots ／ yt_channel_snapshots の行から計算されます。空でない結果を得るには、異なる日に 2 回以上実行する必要があります。

ライブデータが格納されたストアで検証済みのクエリ例：

-- What moved: views per video from the latest snapshots
SELECT s.video_id, v.title, s.view_count, s.captured_at
FROM yt_video_snapshots s JOIN yt_videos v USING(video_id)
ORDER BY s.captured_at DESC, s.view_count DESC LIMIT 20;

-- Audience signal: most-liked comments mentioning a topic (FTS5)
SELECT c.like_count, c.author, c.text
FROM yt_comments_fts f JOIN yt_comments c ON c.rowid = f.rowid
WHERE yt_comments_fts MATCH 'gemini' ORDER BY c.like_count DESC LIMIT 10;

-- Growth rate per tracked channel between first and last snapshot
SELECT channel_id,
       MAX(subscriber_count) - MIN(subscriber_count) AS subs_delta,
       MIN(captured_at) AS first_seen, MAX(captured_at) AS last_seen
FROM yt_channel_snapshots GROUP BY channel_id;

自動学習

この CLI には、自己記録型の学習ループが組み込まれています。CLI が記録を自動で管理します。呼び出しはすべてローカルに記録され、失敗フラグの後に修正済みの再試行が行われると flag_alias 候補が自動生成され、プレイブックのないクエリファミリーに対して teach を実行すると、セッションのジャーナルから playbook_candidate が自動生成されます。あなたが行うのは判断だけです。まず recall を実行し、提示された候補に基づいて行動し、最終的な回答を teach し、修正に気づいたら playbook amend を実行してください。失敗を手作業で記録する必要はありません。

ステップ 1：探索の前に recall

新しいユーザーの質問について、list／search／drill コマンドを実行する前に、次を実行します。

youtube-pp-cli recall "<user's question>" --agent

レスポンスの形式：

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "youtube-pp-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

空のストアに対する早期終了：ストアに学習内容、プレイブック、候補がまだなく（recall で何も見つからず、learnings list と learnings candidates も両方とも空の場合）、すべてのクエリで無駄な負荷をかけないよう、このセッションの残りでは recall を省略します。何かを教えたら、再び最初に recall を実行してください。

ステップ 2：判断ツリー

candidates、playbook、notes、results[0]、警告の順に確認します。

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `youtube-pp-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

プレイブックとノートは、リソースごとの処理手順とは独立しています。recall のレスポンスにはプレイブックと Results[] のヒットの両方が含まれる場合があります。その場合は両方を使ってください。プレイブックは実行すべき手順を示し、リソースのヒットは特定の手順を省略できるようにします。通常は mismatches を省略し、起動直後の予想外の挙動を調査する場合に限り --debug-mismatches を渡してください。

候補を判断する際の詳細：learnings confirm <id> は、候補を適用する前に候補の完全なペイロードを表示します。表示されたペイロードが、確認した挙動と一致していることを確認してください。learnings reject <id> は導出シグネチャを墓標化し、同じ候補が再び表示されないようにします。エンベロープに含まれるのは、現時点で対応する価値のある少数の候補だけです。未処理の候補一覧は youtube-pp-cli learnings candidates で確認できます。

グレースフルデグラデーション：learnings confirm が不明なコマンドの場合、古いバイナリを使用しています。候補に関する案内は無視し、残りのプロトコルに従ってください。

ステップ 3：warnings は必ず読み取る

• low_confidence：confidence<2 の行が存在します。ヒントとして扱い、スキップしてよい発見結果とは見なさないでください。
• resource_not_in_store：学習結果が指すリソースがローカルストアにありません。マッチ検証でエンティティを分類できなかったため、直接取得して再評価してください。
• cross_alias_match（結果ごと）：その行は別の別名で学習され、entity_lookups を介して、ライブクエリの正規名と一致しました（例：「USA」の学習結果が「United States」の想起に適合する）。resource_id を信頼してください。
• similar_shape_different_entity:<canonical>（トップレベル）：構造的に一致する行は存在しますが、その正規エンティティはライブクエリのものと異なります。コールドスタートとして扱われます。この警告には競合する正規名がヒントとして含まれますが、その行は Results に昇格されません。
• ambiguous_alias（トップレベル）：1 つのクエリエンティティが複数の正規名に解決されました（例：「Cards」→ Arizona Cardinals と St. Louis Cardinals）。リソースを確定する前に、コンテキストに基づいて曖昧さを提示してください。
• candidates_present（トップレベル）：エンベロープに candidates セクションが含まれています。他の処理より先に、ステップ 2 の候補分岐で処理してください。
• lookup_refresh_available（トップレベル）：クエリ内のエンティティに対応するルックアップ行がまだありませんが、同期データから作成できる可能性があります。エンティティのルックアップを更新するには、youtube-pp-cli sync を実行してください。
• トップレベルの no_learnings_for_query_family：Jaccard の下限を上回る行がテーブルにありません。完全なコールドスタートです。

ステップ 4：回答の確定後に teach & を実行する — 常に

学習は無条件で行います。ストアで回答できなかったクエリを解決したら、最終的なリソースの対応関係をバックグラウンドで学習させます。呼び出し回数のしきい値はなく、学習する「価値」があったかどうかを判断する必要もありません。teach はこのループの要です。プレイブックがないファミリーではプレイブックの合成を促し、同じ対象を指す表現は 1 つのファミリーにまとめられるため、ほとんど重複する teach によってストアが断片化することはありません。ユーザーに見せる回答を組み立てた後、出力する前に、シェルの & を付けて実行してください。これにより、呼び出しはすぐに戻ります。

youtube-pp-cli teach --query "<user's question>" --resource-type <type> --resource <id1> --resource <id2>
# (append shell `&` to background it)

成功時は何も表示されません。エラーは解決済みの状態ディレクトリにある teach.log にのみ記録されます。teach するリソースは最も具体的なものにしてください。ユーザーの質問が広範で、具体的な回答を見つけるために親レコードをたどった場合は、親ではなく末端の ID を teach してください。CLI は想起時にシード済みの entity_lookups を使って別名をまたいで解決するため、ある別名（例：「Niners」）での teach は、別の別名（例：「49ers」、「San Francisco」）を使った今後のクエリにも自動的に対応します。

PII に関するルール：識別子を取り除いた構造的な質問を teach してください。名前、メールアドレス、電話番号、アカウント ID、その他の個人識別子を、teach するクエリやメモに絶対に含めないでください。CLI は明らかなメールアドレスや電話番号の形式が teach クエリに含まれているかをスキャンして警告しますが、ブロックはしません。警告に頼るのではなく、teach する前に削除してください。

ステップ 5：playbook - 任意のフラグ、自動合成

セッションに playbook を作る価値があるかどうかを判断する必要はありません。playbook がないファミリーに対する teach は、セッションのジャーナルから playbook_candidate を自動合成し、次のセッションで confirm/reject によって評価します。明示的な playbook フラグを付けるのは、そのまま記録する価値のある一連の操作手順をすでに把握している場合に限ります。たとえば、CLI では見つからなかった回避策（フラグが黙って破棄される、文書化されていないパラメーター、ページネーションの工夫、ペイロードに関する注意点）です。統合された 1 回の呼び出し形式を優先してください。リソースの学習と playbook を同じ teach 呼び出しで記録します。

# Common case: record both the resource learning AND the playbook in one call.
youtube-pp-cli teach \
  --query "<user's question>" \
  --resource <id> \
  --playbook-file ~/playbooks/<shape>.json \
  --playbook-notes-file ~/playbooks/<shape>-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource to record alongside).
youtube-pp-cli teach-playbook \
  --query "<user's question>" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

Playbook ファイルは、steps、entity_slots、expected_tool_calls を含む JSON です。Notes ファイルは、注意点をそのまま記載する Markdown です。ファイルを使わない呼び出し元（MCP 専用エージェント）は、同じ内容をインラインで渡します。統合 teach 形式では --playbook-json と --playbook-notes を、teach-playbook では --playbook-json と --notes を使用します。統合 teach 形式では playbook フラグは任意です。リソースのみを teach する場合は、フラグをすべて省略してください。単独の teach-playbook 形式では、playbook と notes のフラグの少なくとも一方を指定する必要があります。両方とも空の場合は拒否されます。Playbook は構造クエリファミリー（エンティティを除去したもの）に基づいてキー付けされます。そのため、あるエンティティ形状のクエリから学習したレシピは、同じ形状のほかのすべてのクエリにも適用され、呼び出し時には slots_resolved がライブクエリの正規形をバインドします。

今後の呼び出しで playbook が見つかった場合は、それを信頼できる情報源として扱ってください。slots_resolved の置換値を使って手順を再実行し、手順がすでに記録されている探索は省略し、どの手順よりも先に notes を読んでください。

ステップ 6：デバッグ応答で修正点を特定した場合は playbook amend &

デバッグプロトコルへの応答で、notes または playbook に記録すべき具体的な修正点（回避策、文書化されていないエンドポイントの形式、古いフィールド名、確認されたスキーマの変化、空のペイロードに対するフォールバックなど）を特定した場合は、ユーザー向けの応答を出す前に playbook amend を実行してください。teach と同じく、実行結果を待たずに進めます。

youtube-pp-cli playbook amend \
  --query "<exact recall query string>" \
  --add-note "<your concrete correction>"
# (append shell `&` to background it)

修正する価値があるもの：

• フラグを黙って破棄したり、順序を入れ替えたりする CLI のインターフェースに対する回避策。
• 文書化されていないエンドポイントの形式（応答が {meta, results} にラップされている、ペイロードがドキュメントの説明より 2 階層深くネストされているなど）。
• 確認されたスキーマの変化（フィールド名が変更された、シーズン間でインデックスがずれた、API がカテゴリラベルを小文字で返すようになったなど）。

Notes に含めてはいけないもの：

• ユーザーの質問に対する、年やエンティティ固有の回答。それは応答であり、学習内容ではありません。
• playbook が実行時にすでに取得する、チーム、選手、行ごとのデータ。
• 既存の notes の内容を言い換えただけの記述。

Amend コマンドは、タイムスタンプ付きのマーカー（[amend YYYY-MM-DDTHH:MMZ]: <text>）を付けて、既存のファミリーの notes に追記します。複数の amend は蓄積され、監査履歴を確認できます。そのファミリーに playbook がまだ存在しない場合は、notes のみの playbook が作成されます（そのため、初回利用時の修正も記録されます）。

Amend notes における PII の取り扱い

playbook amend の notes は、Printing Press の今後のバージョンで共有知識として上流に提供される可能性があります。事後の削除作業をせずに上流への提供経路を維持できるよう、ユーザーを特定できる情報は含めないでください。

• 含めないでください：ユーザーのファイルシステムへのパス、個人用の API キーやトークン、ユーザーのメールアドレス、ユーザーの GitHub ハンドル、または特定のユーザーに結び付いた具体的なクエリ履歴。
• 含めてもよいもの：エンドポイントの形式、文書化されていないフィールド名、API に関する注意点、確認されたスキーマの変化、CLI のインターフェースに対する回避策、汎用的なページネーションや再試行の手法。

修正点がユーザー固有のコンテキストでしか意味を持たない場合は、playbook amend ではなく個人用のメモに記録してください。

ループの測定

youtube-pp-cli learnings stats は、ローカルの learn_events テーブルから、再現率、学習から再利用への移行率、プレイブックの解決率、候補の承認／却下件数を報告します。分母がない間、率は null です。すべてこのマシン内に保持されます。この CLI で学習ループが役立っているかどうかを確認するために使用してください。

学習の無効化

• 1つのコマンドで --no-learn を指定すると、recall と teach の書き込み処理の両方がスキップされます。蓄積された学習内容の影響を受けてはならない、決定性が求められるエージェントのフローやテストで使用してください。
• 環境変数に YOUTUBE_NO_LEARN=true を設定すると、パイプライン全体が無効になります。

エージェントからのフィードバック

あなた（またはエージェント）がこの CLI の問題に気づいたら、記録してください。

youtube-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
youtube-pp-cli feedback --stdin < notes.txt
youtube-pp-cli feedback list --json --limit 10

エントリーは、解決済みのデータディレクトリ内にある feedback.jsonl にローカル保存されます。YOUTUBE_FEEDBACK_ENDPOINT が設定され、かつ --send が指定されているか、YOUTUBE_FEEDBACK_AUTO_SEND=true が設定されている場合を除き、POST されることはありません。デフォルトの動作はローカル保存のみです。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1行で記録します。そこから知見が積み重なっていきます。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力に加えて（または標準出力の代わりに）指定したシンクに送られるため、エージェントはコマンド結果を手作業でパイプ処理せずに振り分けられます。次の3つのシンクがサポートされています。

シンク	動作
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイルを作成してからリネーム）
webhook:<url>	出力本文を URL に POST します（--compact 指定時は application/json または application/x-ndjson）

不明なスキームは拒否され、サポート対象の一覧を示す構造化エラーが返されます。Webhook の失敗時はゼロ以外の終了コードを返し、stderr に URL と HTTP ステータスを記録します。

名前付きプロファイル

プロファイルは保存済みのフラグ値のセットで、複数回の実行で再利用できます。スケジュール実行または定期実行されるエージェントが、実行ごとに異なる入力を使いつつ同じフラグを再利用する場合に使用してください。

youtube-pp-cli profile save briefing --json
youtube-pp-cli --profile briefing youtube activities-list --part snippet
youtube-pp-cli profile list --json
youtube-pp-cli profile show briefing
youtube-pp-cli profile delete briefing --yes

明示的に指定したフラグは常にプロファイルの値より優先され、プロファイルの値はデフォルトより優先されます。agent-context は available_profiles にすべてのプロファイルを一覧表示するため、情報を取得するエージェントは実行時にプロファイルを検出できます。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が誤っています）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → youtube-pp-cli --help の出力を表示
2. install で始まる → mcp で終わる場合は MCP のインストール。それ以外の場合は上記の「前提条件」を参照
3. その他すべて → 直接使用（--agent を付けて CLI コマンドとして実行）

MCP サーバーのインストール

1. MCP サーバーをインストールします。

   go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/youtube/cmd/youtube-pp-mcp@latest
   

2. Claude Code に登録します。

   claude mcp add youtube-pp-mcp -- youtube-pp-mcp
   

3. 確認します：claude mcp list

直接使用

1. インストール済みか確認します：which youtube-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある「前提条件」を参照）。
2. ユーザーの問い合わせに最適なコマンドを、上記の「独自の機能」と「コマンドリファレンス」から選びます。
3. --agent フラグを付けて実行します。

   youtube-pp-cli <command> [subcommand] [args] --agent
   

4. 曖昧な場合は、サブコマンドのヘルプを確認します：youtube-pp-cli <command> --help