oxbshw/watch-skill

# Asking with evidence

Every watched video sits in a persistent index. Questions about it are
answered from that index — text first, frames only when needed — with
timestamps, a confidence score, and an honest refusal when the video
does not show the answer. Never re-run a watch for a follow-up.

## Answer a question

```bash
watch-skill ask <video_id-or-original-url> "<question>"
```

Any language works; the answer comes back in the language of the

# Configuring vision

Watch Skill's agent surface and model backend are separate choices. Claude Code,
Codex, Cursor, OpenClaw, framework agents, and REST clients all call the same engine;
the engine can send selected frames to any supported vision provider.

## Supported providers

```bash
watch-skill setup-vision --provider anthropic --api-key <KEY>
watch-skill setup-vision --provider openai --api-key <KEY>
watch-skill setup-vision --provider gemini --api-key <KEY>
watch-skill setup-vision --provider openrouter --api-key <KEY>
watch-skill setup-vision --provider ollama

# Extracting structure

Three extractors turn an already-watched video into something structured.
All of them answer straight from the persistent index — deterministic, no
extra model calls. The video must be watched first (see `watching-videos`).

## Chapters

```bash
watch-skill extract chapters <video_id-or-source>
```

Titled chapters with start/end timestamps, built from scene changes plus
transcript topic shifts. Good for long tutorials, lectures, meetings —

# Learning from mistakes

When a video answer turns out wrong, the correction is worth more than
an apology. Report it and Watch Skill learns locally — the mistake is
classified, stored as a lesson, injected into future similar questions,
and where possible the original question is immediately re-asked to
confirm the lesson actually fixes it.

## Report a correction

The moment the user corrects a video answer, run:

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

# Recovering from errors

Failures use stable error codes and include an actionable `fix`. Preserve that evidence;
do not replace it with a generic explanation.

## Diagnose first

```bash
watch-skill doctor --json
```

Read the failing checks and apply only their stated fixes. `doctor` can repair managed
ffmpeg and yt-dlp binaries, stale locks, corrupt caches, missing frame directories, and
known local-model health failures. Re-run it once after remediation.

# Sharing results

An analysis that lives only in this chat dies with it. The viewer turns
an analyzed video into a single HTML file anyone can open — no server,
no internet, no Watch Skill install on the other end.

## Generate the page

```bash
watch-skill viewer <video_id-or-source> [-o <path>]
```

The file contains, self-contained (frames inlined as data URIs, zero
external requests):

# THE LOOP

A screenshot shows a moment; it cannot show a flow. THE LOOP records the
actual running target, watches the recording, and judges it against pass
criteria you state in plain language. The loop only observes — YOU apply
the fixes, then iterate. On pass it renders a before/after MP4 + GIF as
proof.

## UI / web page / desktop window

```bash
watch-skill loop start "<url | screen: | window:<title> | file>" "<pass criteria>" [--script '<json steps>']
# ...apply the suggested fixes to the code...
watch-skill loop iterate <loop_id>

# Video memory

Every video ever watched on this machine is still here — frames, OCR,
transcripts, and past answers, in one persistent index under
`~/.watch-skill/`. You never have to say "I don't remember that video."
Sessions don't expire it; watching more videos makes it more useful.

## What's in the library?

```bash
watch-skill list
```

Every indexed video: id, title, duration, when it was analyzed. Check

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

# Watching videos

You don't have a video input; this skill gives you one. Anything a user
hands you — a YouTube link, a TikTok, a lecture, a meeting recording, a
screen capture, an .mp4 on disk — goes through the same pipeline: frames
(scene-aware, deduplicated), OCR, transcript (captions first, local
Whisper offline fallback), all persisted into one index.

## Before watching: check the index

```bash
watch-skill list
```