Watch

/watch

You don't have a video input; this skill gives you one. A Python script gets captions first, optionally downloads the video, extracts frames as JPEGs (scene-aware, or fast keyframes at efficient detail), gets a timestamped transcript (native captions first, then Whisper API as fallback), and prints frame paths. You then Read each frame path to see the images and combine them with the transcript to answer the user.

Resolve SKILL_DIR (do this before any command)

Every python3 ... command below runs a bundled script under SKILL_DIR/scripts/. Set SKILL_DIR to the absolute path of the directory containing THIS SKILL.md you just Read — your harness told you that path in the Read result. The scripts are always a direct sibling of this file (SKILL_DIR/scripts/watch.py), in every install layout:

Read ~/.claude/plugins/cache/claude-video/watch/<ver>/skills/watch/SKILL.md → SKILL_DIR=…/skills/watch
Read ~/.codex/skills/watch/SKILL.md                                          → SKILL_DIR=~/.codex/skills/watch
Read ~/.agents/skills/watch/SKILL.md                                         → SKILL_DIR=~/.agents/skills/watch

Substitute that literal path for ${SKILL_DIR} in every command. This works on every harness (Claude Code, Codex, Cursor, Gemini CLI, …) without relying on any harness-specific environment variable. Guard once at the start of a run:

SKILL_DIR="<absolute path of the directory containing the SKILL.md you Read>"
if [ ! -f "$SKILL_DIR/scripts/watch.py" ]; then
  echo "ERROR: scripts/watch.py not found under SKILL_DIR=$SKILL_DIR" >&2
  echo "Re-check the directory of the SKILL.md you Read and substitute it as SKILL_DIR." >&2
  exit 1
fi

Step 0 — Setup preflight (runs every /watch invocation, silent on success)

Python interpreter: every python3 ... command in this skill is for macOS/Linux. On Windows, substitute python — the python3 command on Windows is the Microsoft Store stub and will not run the script.

On the first /watch invocation in a session, use structured preflight so you can detect first-run setup:

python3 "${SKILL_DIR}/scripts/setup.py" --json

Branch on two fields:

• `can_proceed: true` and `first_run: false` → setup is already done (the user may have deliberately skipped a Whisper key — that's allowed). Proceed to Step 1 without comment.
• `first_run: true` → genuine first-time setup. Do these in order:

1. If missing_binaries is non-empty, run the installer first (it auto-installs on macOS / prints commands elsewhere — see below) and confirm the binaries land. Do not skip this and jump to preferences.
2. Run the installer once more if needed so it scaffolds ~/.config/watch/.env (it only writes the template when the file is absent, so let it create the file before you write any values into it).
3. Encourage a Whisper API key and ask the watch-preference questions below, then write the selected values into ~/.config/watch/.env and set SETUP_COMPLETE=true.

• `can_proceed: false` and `first_run: false` → setup was finished before but the environment regressed (e.g. missing_binaries after an OS change). Run the installer to remediate, then proceed. Don't re-ask preferences.

A missing Whisper key is encouraged to fix, not required: on a genuine first run status will read needs_key even when binaries are present — that's your cue to encourage a key, not a blocker.

On follow-up /watch calls in the same session, use the silent check:

python3 "${SKILL_DIR}/scripts/setup.py" --check

This is a <100ms lookup. Exit 0 means /watch can run — this includes a user who finished setup without a Whisper key (keyless is allowed). On exit 0 the script emits nothing — proceed to Step 1 without comment. Do NOT announce "setup is complete" to the user — they don't need a status message on every turn. The only acceptable user-visible output from Step 0 is when remediation is required.

On non-zero exit, follow the table:

Exit 3 only fires before the user has completed setup. Once SETUP_COMPLETE=true is written, a keyless install returns exit 0 and is never nagged again.

The installer is idempotent — safe to re-run:

python3 "${SKILL_DIR}/scripts/setup.py"

On macOS with Homebrew, it auto-installs ffmpeg and yt-dlp. On Linux/Windows, it prints the exact install commands for the user to run. It scaffolds ~/.config/watch/.env with commented placeholders and default watch settings at 0600 perms.

If an API key is still missing after install: use AskUserQuestion to ask the user whether they have a Groq API key (preferred — cheaper, faster) or an OpenAI key. Then write it into ~/.config/watch/.env — set the matching GROQ_API_KEY=... or OPENAI_API_KEY=... line. If they don't want to set up Whisper, proceed with --no-whisper and tell them videos without native captions will come back frames-only.

First-run watch preference: after the installer has scaffolded ~/.config/watch/.env, use AskUserQuestion to ask one question:

• Default detail (one dial). Present these as AskUserQuestion options in this exact order — lightest to heaviest — and keep (recommended) on balanced even though it is not first (do not reorder to put the recommended option first):
• transcript — no frames at all, transcript only (skips video download when captions exist).
• efficient — fast keyframe pass (cap 50).
• balanced (recommended) — scene-aware frames (cap 100, default).
• token-burner — scene-aware, uncapped (maximum fidelity; high token cost).

Write the answer directly into ~/.config/watch/.env by setting the bare key on its own line — no trailing inline comment (a # note after the value can break parsing):

WATCH_DETAIL=balanced

Use the user's selected value. If they skip the question, keep the recommended default. Once dependencies, the API-key choice, and this preference are handled, write or update SETUP_COMPLETE=true in the same file. Do not ask this preference question again when SETUP_COMPLETE=true.

Structured mode (optional): python3 "${SKILL_DIR}/scripts/setup.py" --json emits {status, can_proceed, first_run, setup_complete, missing_binaries, whisper_backend, has_api_key, config_file, watch_detail, platform} where status is one of ready | needs_install | needs_key | needs_install_and_key. status describes the ideal state (a key is encouraged, so a keyless first run reads needs_key); can_proceed is the operational gate (binaries present AND a key is set OR setup was already completed). Branch on can_proceed/first_run to decide whether to run; use status to decide what to encourage.

Within a single session, you can skip Step 0 on follow-up /watch calls — once --check returned 0, nothing about the environment changes between turns.

When to use

• User pastes a video URL (YouTube, Vimeo, X, TikTok, Twitch clip, most yt-dlp-supported sites) and asks about it.
• User points at a local video file (.mp4, .mov, .mkv, .webm, etc.) and asks about it.
• User types /watch <url-or-path> [question].

Recommended limits

• Best accuracy: videos under 10 minutes. Frame coverage scales inversely with duration.
• Universal rate cap: 2 fps. The script never samples faster than 2 fps, even when a budget or --fps would imply more.
• The frame ceiling is set by the detail mode (WATCH_DETAIL in ~/.config/watch/.env, or --detail), not a single global cap:
• transcript → no frames
• efficient → up to 50 (keyframes)