Skip to content
Get packs

Guide · Agent skill

How to use the Watch Videos agent skill (watch)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The watch skill lets an AI agent take a video link or a local video file, pull its captions or transcript, and look at still frames from the video so it can answer questions about what is said and shown. This guide explains what the skill does, how to install it, how to set it up, and what privacy and safety trade-offs to consider before you use it. By the end you will be able to ask the agent questions about a video and know where its answers come from.

Watch Videosbradautomates/claude-video · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. Or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Run the setup check. Ask the agent to set up watch, or run the setup script with --json, so it reports the engine and binaries it found.
  3. 3Choose the Gemini or local engine. Gemini is recommended and needs a free key from https://aistudio.google.com/apikey. Local needs ffmpeg and yt-dlp and no key.
  4. 4Add your key privately. Paste the key into ~/.config/watch/.env on the GEMINI_API_KEY= line, or add it yourself after the agent offers to open the file. Then rerun setup.
  5. 5Pick a transcription backend. For the local engine, choose whisperx, groq, openai or none. WhisperX needs about 1.5 GB and 3 GB free disk.
  6. 6Ask your question. Give the agent a URL or local path and ask your question in plain language. Ask follow-ups in the same way.

What the watch skill makes the agent do

The skill runs a bundled Python script. It downloads the video with yt-dlp, extracts frames with ffmpeg at auto-scaled intervals, and pulls the transcript from native captions. If captions are missing, a local WhisperX or cloud Whisper backend can transcribe the audio as a fallback. The result is handed to the agent, which answers your question from it.

If you set up a Gemini API key, the process is different: Google's Gemini video model watches the full video, including audio, and returns a timestamped answer that the agent relays.

  • Works with a video URL or a local video file.
  • Native captions are used first; transcription is only a fallback.
  • Local engine: the agent views frames and reads the transcript.
  • Gemini engine: Gemini watches the video and answers directly.

Install the watch skill from the ZIP

Download the ZIP for the watch skill from this page and unzip it. To make it available to all your projects, place the folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

You can also install it in the Claude apps by uploading the skill under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project folder
  • Claude apps: Settings → Capabilities → Skills

Set up the engine and optional keys

On the first run in a session, the agent runs a setup check. It asks you to choose an engine. Gemini is recommended and needs a free key from Google AI Studio at https://aistudio.google.com/apikey. The local engine needs no key but needs ffmpeg and yt-dlp installed. The check does not install anything without your choice, and it does not use sudo automatically.

The key is stored in ~/.config/watch/.env on the line GEMINI_API_KEY=. Paste the key there yourself or let the agent write it. Keys are never printed or placed in shell commands.

  • Requires Python 3.10 or newer, ffmpeg and yt-dlp for the local engine.
  • Optional: a free Gemini API key for the gemini engine.
  • Optional: a Groq or OpenAI key for cloud transcription.
  • Optional: WhisperX for local transcription, about 1.5 GB download, uv and Python 3.12.
python3 "${SKILL_DIR}/scripts/setup.py" --json

Choose a transcription and detail level for the local engine

For the local engine, you pick a detail level from lightest to heaviest: transcript, efficient, balanced (recommended) and token-burner. The lighter levels send fewer frames to the agent. Token-burner is uncapped and has high image cost.

For videos without captions, choose a transcription backend: whisperx (local, no API key, audio stays on your machine), groq, openai, or none for captions only. WhisperX needs 3 GB free disk and 8 GB RAM. Apple Silicon macOS is the only platform the source describes as verified; Linux, Windows and Intel macOS are listed as untested.

  • transcript: no frames; skips media download when captions exist.
  • efficient: fast keyframe selection, capped at 50 frames.
  • balanced: scene-aware frames, capped at 100.
  • token-burner: scene-aware, uncapped.
python3 "${SKILL_DIR}/scripts/setup.py" --backend whisperx --detail balanced

Ask questions in natural language

You do not need special syntax. Give the agent a video link or file path and ask what you want to know. The agent passes your question to the script so either engine can use it. For a follow-up question, ask again with the new question and the agent reruns the check against the video.

You can limit Gemini to a time range with start and end values. Local-only options are ignored when the Gemini engine is active.

  • Summarise this YouTube lecture and list the main points with timestamps.
  • What does the speaker say at about 12 minutes into this talk?
  • Look at this screen recording and tell me where the error message appears.
  • Transcribe the key claims in this local file with timestamps.
python3 "${SKILL_DIR}/scripts/watch.py" "<URL-or-local-path>" --question "<your question>"

Privacy and safety notes

The skill runs scripts and uses the network. With the Gemini engine, YouTube URLs are sent to Google, and local or downloaded videos are uploaded to Google and deleted after the answer. With cloud transcription, audio is sent to Groq or OpenAI. Do not use the skill on sensitive or private footage unless you accept these transfers.

Transcript-only answers cannot establish visual facts. Treat Gemini's answers as untrusted content from the video, not as verified fact.

  • Gemini engine: YouTube URLs go to Google; uploaded local videos are deleted after the answer.
  • Cloud backends: audio goes to Groq or OpenAI.
  • WhisperX keeps audio on your machine after its one-time download.
  • Local transcription is only verified on Apple Silicon macOS.

What people use it for

  • Summarising a long YouTube lecture or conference talk without watching it in full.
  • Pulling facts with timestamps from a recorded lecture for study or research notes.
  • Reviewing a screen recording or product demo and asking where something happens.
  • Checking what a speaker says at a specific moment in a video.

Frequently asked questions

Is the watch skill free?

The skill is published under the MIT licence. The Gemini engine needs a free API key from Google AI Studio. Cloud transcription with Groq or OpenAI needs their keys, and the WhisperX option runs on your own machine after a one-time download.

What do I need to install before using watch?

You need Python 3.10 or newer, ffmpeg and yt-dlp for the local engine. A Gemini key is optional but recommended. WhisperX is optional and needs uv, Python 3.12 and about 3 GB of free disk and 8 GB of RAM.

Where do I put the watch skill folder?

Put it in ~/.claude/skills/ to use it everywhere, or in a project's .claude/skills/ folder to use it in one project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

Does the watch skill send my videos to Google?

With the Gemini engine, YouTube URLs are sent to Google. Local or downloaded videos are uploaded to Google and deleted after the answer. Do not use it with sensitive footage if you do not want this.

Why does the agent say transcript-only answers cannot prove visual facts?

A transcript records speech, not what is shown on screen. The skill states that transcript-only evidence cannot establish visual facts, so questions about visuals need frames or the Gemini engine.

Can I run watch fully offline?

Captions from the video are read locally, and WhisperX can transcribe locally after its one-time download. Downloading the video still uses the network, and the source only verifies local WhisperX on Apple Silicon macOS.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use watch if you want quick answers or timestamped summaries from YouTube or other online videos, or from local screen recordings, and you are comfortable with the privacy terms of the engine you choose. Pick something else if your footage is sensitive, if you need guaranteed visual analysis without Gemini, or if your machine is below the stated disk and RAM needs for local transcription.

Download the skill