/watch

name: watch
version: "1.4.3"
description: Watch any video (URL, stream, or local path) via Watch Skill. Downloads, extracts scene-aware deduped frames, OCRs them, transcribes (captions first, then local Whisper — offline by default), indexes everything, and hands the result to the agent. Follow-up questions are answered from the persistent index without re-processing.
argument-hint: "<video-url-or-path> [question]"
allowed-tools: Bash, Read, AskUserQuestion
license: MIT
user-invocable: true

/watch (Watch Skill)

You don't have a video input; this skill gives you one. It is a thin wrapper around the `watch-skill` CLI — all logic lives in the engine, so this skill works identically on every harness (Claude Code, Codex, Cursor, ...).

This is a drop-in upgrade of the classic claude-video `/watch` skill: same invocation shape, plus a persistent index (`ask` answers follow-ups without re-processing), OCR on frames, scene-aware sampling with perceptual dedup, local Whisper (offline by default, no API key needed), and THE LOOP (capture -> critique -> fix -> re-capture) for iterating on your own output.

Step 0 — Preflight (first invocation per session)

watch-skill doctor --json

• Exit 0 → proceed silently. Do NOT announce that setup is fine.
• Non-zero → the JSON lists each failing check with a `fix`. `doctor`

auto-bootstraps ffmpeg and yt-dlp into a managed bin dir on Windows/macOS/ Linux; re-run once after it reports fixes. Only involve the user when a check still fails after remediation.

• If `watch-skill` itself is not on PATH: `pip install watch-skill` (or

`uv tool install watch-skill`), then re-run the doctor.

No API key is required for acquisition, transcription, OCR, indexing, or search: transcription falls back to local faster-whisper. Visual synthesis and verification can use the user's existing Anthropic, OpenAI, Gemini, or OpenRouter key, or an optional local Ollama model. The agent and provider are independent; see the `configuring-vision` skill. Cloud STT is opt-in (`--cloud-stt`) and only ever uploads extracted mono audio — the video file never leaves the machine.

Step 1 — Watch

Parse the user input into source + optional question, then:

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

• Any yt-dlp-supported site (1800+), direct media URLs, HLS/DASH manifests

(`--duration 60` bounds live streams), and local files all work.

• `--start` / `--end` (`SS`, `MM:SS`, `HH:MM:SS`) switch to dense focused

sampling of that window — use for "what happens at 2:30?" questions and for any video over ~10 minutes when the user cares about one section.

• `--timestamps T1,T2,...` pins frames at transcript-flagged moments

("look here", "as you can see") that visual selection may miss.

• `--transcript-only` skips frames entirely (fastest; no video download when

captions exist).

• `--max-frames N` tightens the token budget (default: duration-tiered,

hard cap 100, max 2 fps).

The report prints an `Indexed: video_id ...` line, frames with `t=MM:SS` timestamps, OCR text, and the transcript.

Step 2 — Read the frames

Read every frame path the report lists, in a single message (parallel Read calls), so you see them together in chronological order.

Step 3 — Answer

Answer from frames + OCR + transcript, citing timestamps. No question → summarize structure, key moments, notable visuals, spoken content.

Follow-ups — use the index, not re-processing

The video is already indexed. For any follow-up question in this or a LATER session:

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

`ask` (v0.6) answers text-first with timestamped evidence, a confidence score, and a `~N tokens saved` line. It escalates on its own when unsure (dense re-sampling, zoom-crop re-OCR) and states plainly when the video does not clearly show the answer — trust that refusal; do NOT invent an answer past it. Frame paths are listed only when the engine wants you to look yourself (or pass `--frames`); Read them then. Never re-run `watch` for a follow-up on an already-indexed video.

If the user corrects one of your video answers, report it so the system learns (locally):

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

THE LOOP — iterate on your own output

When the user asks you to fix UI/visual output and verify the fix:

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>

The critique returns structured issues with timestamps and suggested fixes. YOU change the code; the loop only observes. On pass it renders a before/after MP4+GIF proof. `watch-skill capture "<target>"` records without critiquing.

Security posture

• The video file itself NEVER leaves the machine. Only extracted mono-16kHz

audio may go to a cloud STT API, and only with explicit `--cloud-stt`.

• No cookies, no logins — only public data is requested.
• API keys live in env vars / `.env`; they are never logged or echoed.
• Downloads are cached under `~/.watch-skill/cache` (LRU, size-capped).