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

bash

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.

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:

bash

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:

bash

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):

bash

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:

bash

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

watch

NPX Install

Tags

SKILL.md Content

/watch (Watch Skill)

Step 0 — Preflight (first invocation per session)

Step 1 — Watch

Step 2 — Read the frames

Step 3 — Answer

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

THE LOOP — iterate on your own output

Security posture