Watch Agent Skill

/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).