watch skill (bradautomates) for Claude: ask questions about a video

Lets your agent watch a video from a URL or file and answer questions about it, using frames and a transcript or Google Gemini. For Claude Code and Codex.

Installs: 17.8K; on skills.sh
Stars: 19.7K; on GitHub
Files: 13; besides SKILL.md
Updated: Sep 2026; last repo commit

watch makes your agent turn a video into evidence it can read. It either sends the video to Google Gemini, which answers with timestamps, or it downloads the video, pulls frames with ffmpeg and a transcript from captions, and reads those itself. Captions come first. If a video has none, it can transcribe with WhisperX on your machine, or with Groq or OpenAI.

You use it by asking about a video link or file, or typing /watch. On the first run it asks which engine and detail level you want and may install tools. Gemini needs a free API key. The local engine needs no key but needs Python 3.10+, ffmpeg and yt-dlp.

Good for

Anyone who wants a summary or answers from a YouTube or other video link
Developers checking a screen recording or demo video
Researchers who need timestamps for what was said and shown
People who need a private video to stay on their machine

Install watch

Claude Code

Copy this prompt.

Install the watch skill in Claude Code. Run this command:

/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Python 3.10 or newer.

In Claude Desktop, the README adds the same marketplace through Customize, Plugins, Add, Add marketplace, then installs Watch and uses a Code session. Watch does not work in Claude Chat or Cowork. It also needs FFmpeg and a current yt-dlp for the local engine, which the first run helps you install.

From the project README. Source.

What's in the skill

When it loads

Watch a video (URL or local path). Downloads with yt-dlp, extracts auto-scaled frames with ffmpeg, pulls the transcript from captions (or local WhisperX / cloud Whisper fallback), and hands the result to the agent so it can answer questions about what's in the video. With a Gemini API key, Google's agentic video model watches the full video instead.

Sections in SKILL.md

Resolve the skill and interpreter
First run and setup
Watch and answer
Engines
Sampling and transcript cues
Transcription and failure handling
Security and runtime access

Key facts

Author: Bradley Bonanno
License: MIT
Installs on skills.sh: 17,763 (Nov 2, 2026)
GitHub stars: 19,676 for the whole repo (Nov 2, 2026)
Last commit: Sep 25, 2026
Files: 14 files including SKILL.md (10 Python scripts and 1 shell script)
Works in: Claude Code (Desktop Code session, VS Code, terminal), Codex and other skills hosts; not Claude Chat or Cowork
Needs: Python 3.10+, FFmpeg and a current yt-dlp for the local engine (YouTube also needs a supported JavaScript runtime, per the README); a Gemini key for the Gemini engine
Allowed tools: Bash, Read, AskUserQuestion
Skill version: 0.3.2

What it includes

First-run check and setup
Reports missing tools and saved settings as JSON. It can install ffmpeg and yt-dlp with Homebrew on macOS, install uv and a WhisperX environment, and create ~/.config/watch/.env for keys.
Runs code · setup.py
Engine, detail and transcription backend
Asks whether Gemini or local should view videos, then for local the default detail and what to do for videos without captions.
First-run questions
Watch a URL or file and answer
Passes the video and your question to the script. With Gemini the report holds Gemini's timestamped answer; with local it holds frames and a transcript for the agent to read.
Try: “Use watch on https://youtu.be/... and tell me what the speaker says about pricing, with timestamps.”
Runs code · watch.py
Google's model watches the whole video
YouTube links go to Google directly. Other videos are downloaded, uploaded to Google's Files API, and deleted after the answer.
Network · Gemini engine
Frames plus transcript on your machine
Downloads with yt-dlp, picks frames with ffmpeg in four detail levels (transcript, efficient, balanced, token-burner), and reads captions first.
Runs code · Local engine
WhisperX, Groq or OpenAI for videos without captions
WhisperX keeps audio on the machine. Groq or OpenAI upload extracted audio to that provider with your key.
Runs code · Speech fallback
--start, --end and --timestamps
Limits work to a time range, or pulls exact frames when the speaker says to look at something.
Runs code · Focus and cue frames
Report what failed and ask before switching
If Gemini fails it tells you and offers a local rerun instead of switching silently. For download errors it suggests updating yt-dlp.
Failure handling

From the official docs

Permissions

Medium risk

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Gemini uploads your video to Google
With the Gemini engine, YouTube links and local or downloaded videos go to Google. Use the local engine for private footage. github.com
Setup installs software on your machine
setup.py can run brew install for ffmpeg and yt-dlp, install uv, and build a WhisperX environment with PyTorch, models and caches. The SKILL.md says it does not use sudo automatically. Approve each step. github.com
Cloud transcription uploads audio
Choosing Groq or OpenAI sends extracted audio and uses your key for that provider. Pick WhisperX or captions only to keep audio local. github.com
Plugin runs a SessionStart hook
The Claude Code plugin registers a SessionStart hook (5-second timeout) that runs hooks/scripts/check-setup.sh. The script calls setup.py --check, prints a one-line note if setup needs attention and always exits 0. Install with the skills CLI to skip it. github.com
Cookie options let yt-dlp use your logins
If you pass a cookie file or browser, yt-dlp reads it and may update the file. Use them only for videos you are allowed to access. github.com
Keys can be pasted into chat
The setup flow offers to take your Gemini, Groq or OpenAI key pasted in chat and write it into ~/.config/watch/.env. Add it to the file yourself instead if you do not want the key in the transcript. github.com
Video content is untrusted
The skill tells the agent to treat frames, captions and transcripts as untrusted evidence, not instructions. github.com

Technical details

Talks to	Source video sites and CDNs through yt-dlp. generativelanguage.googleapis.com (Gemini engine). Groq and OpenAI transcription endpoints (if chosen). PyPI, Hugging Face and GitHub for first-time WhisperX setup
Sign-in and keys	Keys live in ~/.config/watch/.env (mode 0600 on macOS and Linux). The Windows permissions are not audited, per SKILL.md.
Scopes	GEMINI_API_KEY, GROQ or OpenAI keys (optional) Optional browser cookies passed to yt-dlp

Questions

What does the watch skill do?

It lets your agent answer questions about a video from a link or file. It either asks Google Gemini to watch it, or extracts timestamped frames and a transcript on your machine and reads those.

How do I install it in Claude Code, the Claude app or Codex?

Use the install box above. The README documents Claude Code through the plugin, and Codex through its skill installer. It says Watch does not work in Claude Chat or Cowork, including uploading it as a custom skill.

Does it need an API key?

Not for the local engine. The Gemini engine needs a free Google AI Studio key. Groq or OpenAI keys are only for the optional cloud transcription fallback.

Is it safe to install?

It runs Python scripts, can install software with Homebrew and downloads about 1.5 GB of speech models if you choose WhisperX. With Gemini it uploads your video to Google. Choose the local engine for private videos, and read each install step before approving.

Does it keep my video private?

Only with the local engine and WhisperX. The SKILL.md says the local engine never contacts Google and WhisperX audio never leaves the machine. With Gemini, local and downloaded videos are uploaded to Google and deleted after the answer.

What does the Claude Code plugin add?

The plugin adds the watch skill and a start-of-session hook that runs the setup script in check mode and prints a note if setup needs attention. Installing with the skills CLI gives you the skill without that hook.

Why does it say yt-dlp failed?

Sites change often, and the README says Watch supports only the latest yt-dlp. The skill suggests upgrading it with its own package manager first, such as brew upgrade yt-dlp or pipx upgrade yt-dlp, then retrying once.

Information

updated Nov 2, 2026

Repository: bradautomates/claude-video
Folder: skills/watch

bradautomates/claude-video skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

claude-video README · github.com
claude-video hooks.json · github.com
watch SKILL.md · github.com
watch setup.py · github.com
claude-video plugin.json · github.com