---
id: oxbshw/watch-skill/watch
version: "217c7d6d"
license: MIT
install: manual
updated: 2026-07-12
---

# watch — Watch Skill processes videos locally by extracting scene-aware frames, running OCR on text within them, and transcribing audio via offline Whisper or captions. It builds a searchable index so follow-up questions are answered without re-processing the video. No API keys required for core features; vision and STT are optional and configurable.

Publisher: oxbshw · Stars: 236 · Updated: 2026-07-12

Install (manual): `git clone https://github.com/oxbshw/watch-skill`

## SKILL.md

# /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.
- 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:

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


[View on SkillFed](https://skillfed.io/oxbshw/watch-skill/watch) · [View on GitHub](https://github.com/oxbshw/watch-skill)