watch

/watch（Watch スキル）

動画入力がなくても、このスキルを使えば動画を扱えます。watch-skill CLI の薄いラッパーです。すべてのロジックはエンジンにあるため、どのハーネス（Claude Code、Codex、Cursor など）でも同じように動作します。

従来の claude-video /watch スキルをそのまま置き換えられるアップグレード版です。同じ呼び出し形式に加え、永続インデックス（ask で再処理せずに追加の質問に回答）、フレームの OCR、シーンを考慮したサンプリングと知覚的重複排除、ローカル Whisper（デフォルトでオフライン、API キー不要）、そして自身の出力を反復改善する THE LOOP（キャプチャ → 評価 → 修正 → 再キャプチャ）を備えています。

ステップ 0 — 事前チェック（セッションごとの初回実行時）

watch-skill doctor --json

• 終了コード 0 → 何も知らせずに続行します。セットアップに問題がないことを伝えてはいけません。
• 0 以外 → JSON に、失敗した各チェックと fix が記載されます。doctor は Windows/macOS/Linux で ffmpeg と yt-dlp を管理対象の bin ディレクトリに自動セットアップします。修正が報告されたら、一度だけ再実行してください。修正後もチェックに失敗する場合に限り、ユーザーに対応を依頼します。
• watch-skill 自体が PATH にない場合：pip install watch-skill（または uv tool install watch-skill）を実行してから、doctor を再実行します。

取得、文字起こし、OCR、インデックス作成、検索に API キーは不要です。文字起こしでは、ローカルの faster-whisper にフォールバックします。視覚的な生成と検証には、ユーザーがすでに持っている Anthropic、OpenAI、Gemini、OpenRouter のキー、または任意のローカル Ollama モデルを使用できます。エージェントとプロバイダーは独立しています。configuring-vision スキルを参照してください。クラウド STT はオプトイン（--cloud-stt）であり、抽出したモノラル音声のみをアップロードします。動画ファイルがマシンの外に送られることはありません。

ステップ 1 — 動画を見る

ユーザー入力をソースと任意の質問に解析してから、次を実行します。

watch-skill watch "<source>" [--start T --end T] [--max-frames N] [--transcript-only]

• yt-dlp が対応するサイト（1800 以上）、直接のメディア URL、HLS/DASH マニフェスト（ライブストリームは --duration 60 で長さを制限）、ローカルファイルに対応しています。
• --start / --end（SS、MM:SS、HH:MM:SS）を指定すると、その区間を高密度に重点サンプリングします。「2:30 には何が起きますか？」のような質問や、ユーザーが特定の区間を気にしている約 10 分を超える動画に使用します。
• --timestamps T1,T2,... を指定すると、文字起こしでフラグが付いた（「ここを見て」「ご覧のとおり」などの）時点のフレームを固定します。視覚的な選択では見落とされる可能性があります。
• --transcript-only を指定すると、フレームを完全にスキップします（最速です。キャプションがある場合、動画はダウンロードされません）。
• --max-frames N を指定すると、トークン予算を抑えられます（デフォルトは動画の長さに応じて設定、上限 100、最大 2 fps）。

レポートには Indexed: video_id ... の行、t=MM:SS 形式のタイムスタンプ付きフレーム、OCR テキスト、文字起こしが表示されます。

ステップ 2 — フレームを読む

レポートに記載されているすべてのフレームパスを、1 つのメッセージで読み込みます（Read 呼び出しを並列実行）。これにより、フレームを時系列順にまとめて確認できます。

ステップ 3 — 回答する

フレーム、OCR、文字起こしをもとに、タイムスタンプを引用して回答します。質問がない場合は、構成、重要な場面、目立った映像、話されている内容を要約します。

追加の質問 — 再処理せずにインデックスを使う

動画はすでにインデックス化されています。このセッション中、または後のセッションで追加の質問があれば、次を実行します。

watch-skill ask <video_id> "<question>"      # self-healing answer + evidence
watch-skill search "<phrase>"                 # across every video ever watched

ask（v0.6）は、まずテキストを検索して、タイムスタンプ付きの根拠、信頼度スコア、~N tokens saved の行を含む回答を返します。確信が持てない場合は自動で詳細確認（高密度の再サンプリング、ズームクロップでの再 OCR）に進み、動画から回答を明確に読み取れない場合はその旨をはっきり伝えます。その回答は尊重し、それ以上の回答を捏造してはいけません。エンジンが自分で確認するよう求めている場合（または --frames を渡した場合）に限り、フレームパスが一覧表示されます。その場合はフレームを読み込んでください。すでにインデックス化された動画について、追加の質問に答えるために watch を再実行してはいけません。

ユーザーが動画に関する回答を訂正した場合、システムが学習できるよう、次を実行して（ローカルで）報告します。

watch-skill lessons add <video_id> "<question>" "<your wrong answer>" "<the correction>"

THE LOOP — 自身の出力を反復改善する

ユーザーから UI や視覚的な出力の修正と検証を求められた場合：

watch-skill loop start "<url-or-screen:-or-file>" "<pass criteria>" [--script '<json steps>']
# ... you apply the suggested fixes ...
watch-skill loop iterate <loop_id>

評価では、タイムスタンプと推奨される修正を含む、構造化された問題が返されます。コードを変更するのはあなたです。ループは観察のみを行います。合格すると、変更前後を示す MP4 と GIF の証拠が生成されます。watch-skill capture "<target>" は、評価を行わずに記録します。

セキュリティ対策

• 動画ファイル自体がマシンの外に出ることはありません。クラウド STT API に送信される可能性があるのは、抽出されたモノラル 16 kHz の音声のみで、明示的に --cloud-stt を指定した場合に限られます。
• Cookie やログインは不要です。公開データのみを取得します。
• API キーは環境変数または .env に保存され、ログに記録されたり、表示されたりすることはありません。
• ダウンロードは ~/.watch-skill/cache にキャッシュされます（LRU、サイズ上限あり）。