AI Guides › Workbench
By Nigel Guy · 8 min read
Most people who want Claude to "watch" a YouTube video paste in the transcript and call it done. It feels fine because the words are all there, but a transcript cannot show cuts, on-screen captions or pauses. If the thing you want to learn from a video is how it was made, a transcript is the one source that cannot show you.
The rule: let a model that can actually see the video do the watching, then have Claude work from its timestamped notes — and treat those notes as evidence to check, not gospel.
| Term | Plain meaning |
|---|---|
| Skill | A folder of instructions and scripts Claude Code (or Codex) loads when a task matches. You install it once. |
| Watch | An open-source skill, bradautomates/claude-video on GitHub (MIT licence, version 0.3.2 at time of writing). You call it with /watch. |
| Gemini engine | Watch's default mode when you give it a Google Gemini API key. Google's video model watches the whole video, picture and sound, and returns a timestamped answer. |
| Local engine | Watch's no-key mode. It downloads the video, pulls still frames and captions on your machine, and Claude reads those. |
Claude itself reads text and still images. With the Gemini engine, Claude is relaying what Gemini saw; it has not watched the video.
| Option | What it does | Cost at time of writing | Best for | Catch |
|---|---|---|---|---|
| Transcript only | Words with rough timings | £0 | Talks, interviews, podcasts | Blind to cuts, captions, visuals |
| Watch, local engine | Frames plus captions, read by Claude | £0 (needs Python 3.10+, FFmpeg, yt-dlp; YouTube also needs Deno) | Private videos, files that must stay on your machine | Frame cap (about 100 at the default "balanced" detail), at most 2 frames per second, weaker on fast edits |
| Watch, Gemini engine | Gemini watches the full video and answers your question with timestamps | Free tier available; paid use is billed in US dollars per million tokens, so check Google's pricing page before heavy use | Public YouTube videos, edit and pacing analysis | Public videos only; free tier capped at 8 hours of YouTube a day; Gemini can still be wrong |
Watch works in Claude Code (the Code tab in Claude Desktop, VS Code, or a terminal) and in Codex. Its own README says it does not work in Claude Chat or Cowork: in Cowork the Gemini key does not persist between tasks, and most sites block downloads from that cloud environment.
Pick one route.
https://github.com/bradautomates/claude-video, click Sync, then find Watch and install it. Adding the marketplace alone does not install it./plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video
Use $skill-installer to install the watch skill from:
https://github.com/bradautomates/claude-video/tree/main/skills/watch
Start a new session afterwards if /watch does not appear in autocomplete.
Get a free key at aistudio.google.com/apikey. On first run, Watch asks which engine to use; choose gemini. It then creates ~/.config/watch/.env with a GEMINI_API_KEY= line. Paste the key into that file yourself, not into the chat or a terminal command. Nothing to fill in:
You are setting up the watch skill on my computer. Goal: Gemini engine ready, with my API key stored only in the watch config file.
Steps:
1. Run the skill's bundled setup with the Gemini engine selected.
2. If it reports the key is missing, open ~/.config/watch/.env in my default text editor so I can paste the key after GEMINI_API_KEY= myself. Do not ask me to paste the key into this chat or into any shell command.
3. When I say "saved", rerun the setup check.
Output: one line saying ready or not ready, and if not ready, the exact error and the single next action.
Before you answer, confirm you have not printed, echoed or logged the key anywhere.
You can also export GEMINI_API_KEY in your shell profile; Watch checks the environment first, then the config file, then a .env in the current folder.
Always pass a question. Watch sends it to Gemini with the video, and an answer to a specific question beats a vague summary. Fill in the link and what you want to know:
Use the watch skill on [PUBLIC_YOUTUBE_URL].
Context: I am studying this video because [WHY_YOU_CARE, e.g. "I want to copy its opening structure for my own product demos"].
Question for the video model: [YOUR_QUESTION].
Output:
- A short summary (no more than five sentences).
- A timeline table: timestamp | what is on screen | what is said | any on-screen text, quoted exactly.
- A line saying which engine ran (gemini or local).
If the link is private, unlisted, or the run fails, stop and tell me what failed. Do not switch engines without asking.
Before answering, check every row has a timestamp and that any quoted on-screen text is marked as Gemini's reading.
This is the test that shows whether you are getting real visual detail. Watch clips with --start and --end (seconds, MM:SS or HH:MM:SS). There is no --clip flag, and with the Gemini engine the --fps option is ignored; on the local engine it is capped at 2 frames per second. So you cannot force "10 frames a second" — ask for precision in the question instead. Fill in the link and the window:
Use the watch skill on [PUBLIC_YOUTUBE_URL] with --start [START, e.g. 0:00] --end [END, e.g. 0:05].
Role: you are an editor logging cuts for a rough-cut review.
Question for the video model: List every cut or shot change in this window. For each one give the timestamp to the nearest tenth of a second if you can, what is on screen, the words spoken, and any on-screen caption quoted exactly.
Output: a table with columns Time | Shot | Spoken words | Caption (exact). Add a final line stating how confident the model was about cut timings.
If the window is longer than [MAX_SECONDS] seconds, ask me before running.
Self-check: count the rows, and flag any caption you could not read clearly rather than guessing it.
Then scrub the same five seconds yourself. If the cut count is off, trust longer runs less.
Once you have a timeline you trust, make it useful. Fill in your business and goal:
Role: practical adviser to a small UK business.
Context: below are timestamped notes on a video. My business: [YOUR_BUSINESS]. What I want from this video: [GOAL, e.g. "a better 30-second product teaser"].
Task: turn the notes into a numbered action plan I can carry out this week.
For each step: what to do, which timestamp in the notes it comes from, and a rough time estimate.
Constraints: no more than 8 steps; do not invent anything that is not in the notes; mark any step that depends on tools or budget I have not mentioned.
If my business or goal is missing or vague, ask before writing the plan.
Self-check: every step cites a timestamp.
[PASTE_NOTES]
--engine local). Gemini only accepts public YouTube links, and local files sent through the Gemini engine are uploaded to Google first.--start/--end. Watch's own notes say local accuracy is usually best under 10 minutes.yt-dlp.