Let Claude Code Watch Videos - the /watch Skill

What the skill does

When you give Claude a video link or a local file, the skill runs a chain of steps locally on your machine and hands Claude two things back: frames (images from different moments in the video) and a timestamped transcript. After that, Claude has genuinely "seen" the video and "heard" the audio, and it can answer questions about it.

What happens behind the scenes:

• •Download: yt-dlp fetches the video (or resolves a local file). Works with YouTube, TikTok, Instagram, X, Loom, and a few hundred more sites.
• •Frames: ffmpeg extracts scene-aware images, auto-scaled by the video's length.
• •Transcript: native captions first (free), and if there are none, Whisper through Groq or OpenAI.
• •Read: Claude reads each frame as an image, aligns it to the transcript by timestamp, and answers you.

Install in two lines

The skill is an open-source (MIT) plugin by bradautomates. In Claude Code, the recommended way is via the marketplace - that way it also auto-updates. Run these two commands inside Claude Code:

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

Using Codex or another skill-based agent? Clone the repository into its skills directory:

git clone https://github.com/bradautomates/claude-video.git ~/.codex/skills/watch

That path is for Codex. Other agents may use a different skills directory.

First run - it sets itself up

There's no manual config. The first time you run /watch, the skill checks whether yt-dlp and ffmpeg are installed. If not, on macOS it runs for you:

brew install ffmpeg yt-dlp

(On Linux and Windows it prints the exact commands to run yourself.) After that the check is silent and later runs just work - it's a sub-100ms lookup, so it doesn't slow you down.

Captions cover most public videos for free. A Whisper key is only needed when a video has no caption track at all. That's exactly what the next sections are about.

Basic usage - paste and ask

The shape is simple: /watch <url-or-path> <question>. It takes a URL or a local file, and you can add a question at the end:

/watch https://youtu.be/abc123 what happens at the 30 second mark?

/watch ./screen-recording.mov what's going wrong here?

/watch https://tiktok.com/@user/video/123 summarize this

If you don't add a question, Claude just summarizes what happens in the video - the structure, the key moments, what was said and shown on screen.

Tip: videos under 10 minutes get the best coverage. For a long video, focus on a specific section with --start and --end (e.g. --start 2:15 --end 2:45) instead of a sparse scan of the whole thing.

Where the transcript comes from

The transcript comes from one of two places, in this order:

Only the extracted audio clip is sent to the transcription service, not the video file. If you do not want to send audio, use --no-whisper: videos without captions will be analyzed from frames only.

What happens when captions are missing

The current upstream skill supports two Whisper services: Groq with whisper-large-v3 is the recommended default, and OpenAI whisper-1 is the alternative. Add the matching key to ~/.config/watch/.env:

# ~/.config/watch/.env
GROQ_API_KEY=...
# or
OPENAI_API_KEY=...

Force a provider with --whisper groq or --whisper openai. Without a key, you can still analyze videos that expose source captions, or use --no-whisperand continue with frames only.

Why it is useful - use cases

• Analyze a competitor's content

  /watch <viral-video> what hook did they open with? - Claude looks at the first frames, reads the opening transcript, and breaks down the structure. Same for ad creative, competitor launches, or podcast intros.

• Repro a bug from a screen recording

  Someone sends you a recording of something broken. /watch bug.mov what's going wrong? - Claude watches the recording, finds the frame where the issue appears, and often catches the cause without you opening the file at all.

• Cut the hype out of an update video

  /watch <launch-video> what's actually new - skip the hype - you get the substance without ten minutes of intro and overselling.

• Turn a video into notes

  /watch <video> summarize this to a note - run it across a series and file a per-video summary. A whole course becomes a searchable set of notes instead of hours you have to sit through.

Control frames, range, and context cost

Most context cost comes from frames. Instead of one detail mode, the skill exposes explicit controls:

• •--max-frames N - lowers the frame ceiling.
• •--resolution 1024 - enlarges frames when small on-screen text matters.
• •--start and --end - analyze only a focused time range.
• •--fps F - overrides automatic sampling, up to the 2 fps ceiling.

For example, analyze 30 seconds at high resolution with a smaller frame budget:

/watch https://youtu.be/abc --start 2:15 --end 2:45 --max-frames 30 --resolution 1024

Rule of thumb: focus the time range first on long videos. Raise resolution only when Claude needs to read code, slides, or small UI.