Skip to content
Back to search

watch-video-skill

A Claude skill that teaches your AI to watch videos. Use it to learn, absorb, copy, or give visual feedback like you would to a real person.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/newuxtreme--watch-video-skill/badge.svg)](/listings/newuxtreme--watch-video-skill)

HTML

<a href="/listings/newuxtreme--watch-video-skill"><img src="/api/listings/newuxtreme--watch-video-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone into your Claude skills folder:

# macOS / Linux
git clone https://github.com/Newuxtreme/watch-video-skill.git ~/.claude/skills/watch-video

# Windows (Git Bash / WSL)
git clone https://github.com/Newuxtreme/watch-video-skill.git ~/.claude/skills/watch-video

# Windows (PowerShell / cmd)
git clone https://github.com/Newuxtreme/watch-video-skill.git "$env:USERPROFILE\.claude\skills\watch-video"

For Claude Desktop or Claude Agent SDK apps, clone into whatever folder that environment loads skills from.

Dependencies

- **ffmpeg + ffprobe.** [Download](https://ffmpeg.org/download.html), or use `brew install ffmpeg` on macOS, `winget install Gyan.FFmpeg` on Windows, or `apt install ffmpeg` on Linux. - **yt-dlp.** Use `winget install yt-dlp.yt-dlp` on Windows, `brew install yt-dlp` on macOS, or `pipx install yt-dlp` on Linux. It must be on `PATH` as a standalone binary. - **Python 3.9 or later.** Available on `PATH` as `python` (or `python3` on macOS and Linux). The scripts use `from __future__ import annotations`, so 3.9 works. - **Optional: Whisper API key.** Only needed for videos with no captions. Get a key at one of these: - [Groq](https://console.groq.com/keys). Recommended. It is cheaper and faster than OpenAI. It runs `whisper-large-v3`. - [OpenAI](https://platform.openai.com/api-keys). The fallback.

Run the setup wizard to create the `.env` file and check dependencies:

python scripts/setup.py

It creates `~/.config/watch/.env` with placeholder lines for both keys. Edit the file and paste in your key. Without a key, the skill still works on any video that has captions, which covers most of YouTube.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 142 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: watch-video
  3. description: SLASH-COMMAND-ONLY. Invoke ONLY when the user explicitly types the literal `/watch-video` slash command. Never auto-trigger on phrases like "watch this video," "summarize this video," "take notes on this video," or on a bare YouTube URL. For ad-hoc YouTube questions, fetch the transcript directly (YouTube page or yt-dlp) and skim — do not run this heavyweight pipeline.
  4. ---
  5. # Watch Video
  6. Claude can't stream video directly. This skill fakes it: a Python pipeline (vendored from [bradautomates/claude-video](https://github.com/bradautomates/claude-video) under `scripts/`) downloads the video, extracts auto-scaled JPEG frames with ffmpeg, pulls a timestamped transcript (native captions first, Whisper API fallback), and prints a markdown report listing every frame path. Claude then `Read`s each frame, aligns it to the spoken text, and writes a structured notes file.
  7. ## When to invoke
  8. **Slash-command only.** Run this skill ONLY when the user literally types `/watch-video`. That is the sole trigger.
  9. Do NOT invoke on:
  10. - Casual phrases like "watch this video," "summarize this," "take notes on this YouTube video," "analyze this reel"
  11. - A bare YouTube URL pasted with a question ("what useful tips are in this video?" + URL)
  12. - Any natural-language ask about a video that lacks the explicit `/watch-video` command
  13. **Default for YouTube questions without the slash command:** pull the transcript the fastest way available — fetch the YouTube page / use yt-dlp captions / a transcript site — skim it, and answer from that. The frame-extraction pipeline is overkill unless the user explicitly asks for it via `/watch-video`.
  14. > If you'd rather have auto-trigger behavior, edit the `description:` line above to match the keywords you want Claude to fire on (e.g. "Use when the user wants Claude to watch, analyze, or take notes on a video"). Slash-only is the default in this repo because explicit invocation prevents accidental token burn on long videos.
  15. ## Dependencies
  16. - **ffmpeg + ffprobe** on PATH — for frame and audio extraction
  17. - **yt-dlp** on PATH — for downloading and caption fetching
  18. - **Python 3.9+** — the bundled scripts use `from __future__ import annotations` so 3.9 works
  19. - **Optional:** Whisper API key for videos without native captions. Set `GROQ_API_KEY` (preferred — cheaper/faster, runs `whisper-large-v3`) or `OPENAI_API_KEY` in `~/.config/watch/.env`. Without one, captioned videos work fine; uncaptioned videos return frames-only.
  20. Run `python scripts/setup.py --check` to verify dependencies, or `python scripts/setup.py` to scaffold the `.env` and check binaries. On macOS, the installer auto-installs missing binaries via Homebrew. On Linux/Windows, it prints exact install commands.
  21. ## Pipeline
  22. The work happens in `scripts/watch.py`. It downloads, extracts, transcribes, and prints a markdown report to stdout that lists every frame path. The pipeline auto-scales the frame budget by duration (hard cap 100 frames / 2 fps), so no manual interval tuning.
  23. ```
  24. python scripts/watch.py "<youtube-url-or-local-path>" [flags]
  25. ```
  26. Flags worth knowing:
  27. - `--start T` / `--end T` — focus on a section (`SS`, `MM:SS`, or `HH:MM:SS`). Auto-scales fps denser inside the range. Use this for any question about a specific moment, or for any video > 10 min where the user's question is about one part.
  28. - `--max-frames N` — lower the cap for tighter token budget (default 80, hard max 100).
  29. - `--resolution W` — frame width in px (default 512; bump to 1024 only if on-screen text is unreadable).
  30. - `--whisper groq|openai` — force a specific Whisper backend (default: prefer Groq if both keys exist).
  31. - `--no-whisper` — skip transcription entirely if no captions. Frames-only output.
  32. - `--out-dir DIR` — keep working files somewhere specific (default: an auto-generated tmp dir).
  33. Auto-fps budgets (full-video mode):
  34. - ≤30s → up to 30 frames
  35. - 30s–1min → ~40 frames
  36. - 1–3min → ~60 frames
  37. - 3–10min → ~80 frames
  38. - \>10min → 100 frames sparse (warning printed; consider `--start`/`--end`)
  39. ## Step-by-step workflow
  40. ### 1. Run the pipeline
  41. Default invocation, no flags:
  42. ```
  43. python scripts/watch.py "<source>"
  44. ```
  45. For long videos where the user asked about a specific moment, pass `--start`/`--end`:
  46. ```
  47. python scripts/watch.py "<source>" --start 2:15 --end 2:45
  48. ```
  49. The script writes everything to a tmp working directory and prints a markdown report to stdout. Capture the stdout — it contains:
  50. - Header (Title, Uploader, Duration, Transcript source: `captions` / `whisper (groq)` / `whisper (openai)` / `none available`)
  51. - `## Frames` section with `- \`<absolute-path>\` (t=MM:SS)` lines
  52. - `## Transcript` section with `[MM:SS] text...` lines
  53. - Footer with `Work dir: <path>`
  54. ### 2. Read every frame
  55. Read all the listed frame paths in a single message (parallel `Read` tool calls). The Read tool renders JPEGs as images. Each frame's filename + `t=MM:SS` from the report tells you when it occurred — pair each frame with the matching transcript line at that timestamp.
  56. For very long videos (>10 min, sparse mode): the budget already capped at 100 frames, so reading all of them is fine.
  57. ### 3. Write the summary
  58. Output file: `<work-dir>/<slug>-notes.md` by default. If the user said "save notes somewhere permanent," ask where.
  59. Structure the markdown like this:
  60. ```markdown
  61. # <Title>
  62. **Source:** <URL or local path>
  63. **Duration:** <mm:ss>
  64. **Uploader:** <if from YouTube>
  65. **Transcript source:** <captions / whisper (groq) / whisper (openai) / none>
  66. ## One-line summary
  67. <≤20 words — the core claim or hook of the video>
  68. ## TL;DR
  69. <3–5 bullet points capturing the main arguments, moments, or beats>
  70. ## Timeline
  71. - **[00:00]** <what's happening visually + the key line being said>
  72. - **[00:15]** ...
  73. <one row per meaningful beat, not per frame>
  74. ## Key quotes
  75. > "<verbatim quote>" — [mm:ss]
  76. ## Visual notes
  77. <what the video shows that the transcript alone would miss — setting, B-roll, on-screen text, graphics, transitions, subject's emotion>
  78. ## Takeaways (optional)
  79. <Only include if the content is directly relevant to the user's domain or goals. Omit otherwise.>
  80. ```
  81. ### 4. Clean up
  82. After the `.md` is written, delete the work dir (it contains the full downloaded video + frames, which is large). The script prints `Work dir: <path>` in the footer of its report; pass that path to `rm -rf`.
  83. If the user specified a non-tmp `--out-dir`, ask before deleting.
  84. ## Common gotchas
  85. - **YouTube Shorts / age-gated / members-only** — yt-dlp may fail. Surface its stderr verbatim; don't retry silently.
  86. - **No captions + no Whisper key** — the report says `Transcript: none available` and points at `setup.py`. Tell the user they can add a Groq key to `~/.config/watch/.env` for Whisper, or use `--no-whisper` for frames-only.
  87. - **Local file with no audio track** — Whisper extraction errors out cleanly. Use `--no-whisper` for frames-only.
  88. - **Very long videos (>30 min)** — confirm with the user before running. The pipeline caps at 100 frames so the budget is bounded, but a sparse 100-frame scan of a 60-min video isn't very useful. Almost always better to run focused on the specific section.
  89. - **Cloudflare 403 on Groq** — `whisper.py` already sets a custom User-Agent to clear Cloudflare's default-Python-UA block. If you ever see a 403, that's the failure mode.
  90. - **No automatic Groq → OpenAI fallback** — the script picks one Whisper backend at the start of each run (Groq if its key is set, else OpenAI) and stays on it. If Groq rate-limits, the script retries Groq twice then errors out. To use OpenAI instead, pass `--whisper openai`.
  91. ## What NOT to do
  92. - Don't attempt to "watch" a video by inventing content based on title or thumbnail. If the pipeline fails, say so.
  93. - Don't write the summary before actually reading frames. The transcript alone misses visual context (B-roll, on-screen text, emotion, graphics, transitions).
  94. - Don't skip cleanup. Frame dumps + downloaded videos are large.
  95. - Don't auto-fire on a video URL. Slash-command-only — see "When to invoke" above.
  96. ## Engine attribution
  97. The pipeline scripts under `scripts/` are vendored from [bradautomates/claude-video](https://github.com/bradautomates/claude-video) (MIT). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the full upstream license.
README.md · README · 158 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # watch-video skill
  2. A Claude skill that lets Claude "watch" videos by extracting a time-synced transcript plus auto-scaled still frames, then reading them together to produce structured markdown notes.
  3. Works with any Claude surface that supports the skill format — **Claude Code**, **Claude Desktop**, and apps built on the **Claude Agent SDK**.
  4. ## Watch the tutorial
  5. <p align="center">
  6. <a href="https://www.youtube.com/watch?v=U10NUi4FqnU">
  7. <img src="https://img.youtube.com/vi/U10NUi4FqnU/maxresdefault.jpg" alt="Watch the tutorial on YouTube" width="720" />
  8. </a>
  9. </p>
  10. > **Note:** the tutorial above covers v1. v2 uses a new engine from [bradautomates/claude-video](https://github.com/bradautomates/claude-video). See "What's new in v2" below for the changes.
  11. ## What it does
  12. Claude can see pictures. It cannot watch a video on its own. This skill fixes that.
  13. Here is how it works:
  14. 1. It pulls the transcript. If the video has captions, it uses those. If it does not, it sends the audio to Whisper. Groq is the default and OpenAI is the backup.
  15. 2. It pulls still frames from the video. Short videos get more frames, long videos get fewer. The cap is 100 frames so the token cost stays low.
  16. 3. It matches each frame to the words said at that moment.
  17. 4. Claude reads the frames and the transcript together. Then it writes a clean notes file with a one line summary, a TL;DR, a timeline, key quotes, and visual notes.
  18. It works on YouTube and on every other site yt-dlp supports (Vimeo, TikTok, X, Twitch, Loom, Instagram). It also works on local video files (mp4, mov, mkv, webm, avi).
  19. ## Use cases
  20. **1.** If you don't understand a tool or concept, you can make Claude watch a video and then plan from there on out; Claude Code will have a much clearer understanding. I saw a custom extension being built for downloading courses and started vibe-coding Claude on that, and it's doing a really, REALLY good job ;)
  21. ![Use case 1 — screenshot heavily blurred for privacy.](docs/images/use-case-1-onboarding.jpg)
  22. **2.** Someone was giving me screenshots and walking me through a video on how to do a funnel better. In trying to make Claude learn it, it was much easier for it to just watch the whole video, including the screenshots of the conversations that were being had. This gave it a real, live example of how DM conversations go.
  23. ![Use case 2 — screenshot heavily blurred for privacy.](docs/images/use-case-2-tutorial.jpg)
  24. **3.** I'm creating my own Opus Clip Claude Code skill. The difference between the first example that Claude Code made versus the final example it produced is significant, because I was able to show it a demo of what my perfect reel actually looks like.
  25. <p align="center">
  26. <img src="docs/images/use-case-3-reel-a.jpg" alt="Use case 3a — example reel frame" width="45%" />
  27. &nbsp;&nbsp;
  28. <img src="docs/images/use-case-3-reel-b.jpg" alt="Use case 3b — example reel frame" width="45%" />
  29. </p>
  30. **4.** If you like a certain YouTuber's style of editing videos, you can make Claude Code watch two or three of their videos to understand their editing style!
  31. Now, with the new video editing tools like Remotion and Hyperframes, you can actually edit your entire videos through Claude Code in exactly that manner. Since it can see what is on screen and understand how it works along with the timestamps, it can replicate that specific style for you.
  32. ## What's new in v2
  33. I swapped the engine in v2. The old version used a local script I wrote. The new version uses the engine from [bradautomates/claude-video](https://github.com/bradautomates/claude-video) (MIT). It is a big step up.
  34. Here is what changed:
  35. - **Frames are auto scaled.** The script picks how many frames to grab based on the video length. A 30 second video gets about 30 frames. A 10 minute video gets about 80. You do not set the interval by hand anymore.
  36. - **Whisper now runs in the cloud.** The old version used the local `openai-whisper` package, which was slow and a pain to install. The new version sends the audio to the Groq API or the OpenAI API. It is faster and cheaper. It works on any machine that has Python.
  37. - **Focused mode.** You can zoom into one part of a long video. Use `--start` and `--end` to pick a window. The script packs more frames into that window. This is useful when the user asks about one specific moment.
  38. - **Hard caps on cost.** The script will never grab more than 100 frames or run faster than 2 fps. A long video will not blow up your token bill.
  39. ## What this skill adds beyond bradautomates/claude-video
  40. This skill takes Brad's engine and adds four things on top.
  41. - **Slash command only.** Brad's skill fires on any video URL or any phrase like "watch this video." That can burn tokens on long videos you did not mean to watch. This skill only fires when you type `/watch-video`. If you want the old auto trigger back, edit the `description:` line in [SKILL.md](SKILL.md). There is a note in that file that walks you through it.
  42. - **Notes file you can keep.** Brad's skill answers the user in chat and that is it. This skill writes a real markdown file with a Title, a TL;DR, a Timeline, Key quotes, and Visual notes. You can read it later, link to it from other notes, or feed it into another agent.
  43. - **Cleanup is built in.** When the script writes the notes file, it wipes the temp folder. No leftover videos or frames cluttering up your disk.
  44. - **Frame sampling guide.** This skill tells Claude which frames to look at, based on how long the video is. Short videos get every frame read. Medium videos get sampled every five seconds. Long videos get sampled every ten seconds. Claude does not brute force every single frame into the context window.
  45. If you want the pure Brad pipeline with no wrapper on top, install [bradautomates/claude-video](https://github.com/bradautomates/claude-video). It is excellent.
  46. ## Install
  47. Clone into your Claude skills folder:
  48. ```bash
  49. # macOS / Linux
  50. git clone https://github.com/Newuxtreme/watch-video-skill.git ~/.claude/skills/watch-video
  51. # Windows (Git Bash / WSL)
  52. git clone https://github.com/Newuxtreme/watch-video-skill.git ~/.claude/skills/watch-video
  53. # Windows (PowerShell / cmd)
  54. git clone https://github.com/Newuxtreme/watch-video-skill.git "$env:USERPROFILE\.claude\skills\watch-video"
  55. ```
  56. For Claude Desktop or Claude Agent SDK apps, clone into whatever folder that environment loads skills from.
  57. ### Dependencies
  58. - **ffmpeg + ffprobe.** [Download](https://ffmpeg.org/download.html), or use `brew install ffmpeg` on macOS, `winget install Gyan.FFmpeg` on Windows, or `apt install ffmpeg` on Linux.
  59. - **yt-dlp.** Use `winget install yt-dlp.yt-dlp` on Windows, `brew install yt-dlp` on macOS, or `pipx install yt-dlp` on Linux. It must be on `PATH` as a standalone binary.
  60. - **Python 3.9 or later.** Available on `PATH` as `python` (or `python3` on macOS and Linux). The scripts use `from __future__ import annotations`, so 3.9 works.
  61. - **Optional: Whisper API key.** Only needed for videos with no captions. Get a key at one of these:
  62. - [Groq](https://console.groq.com/keys). Recommended. It is cheaper and faster than OpenAI. It runs `whisper-large-v3`.
  63. - [OpenAI](https://platform.openai.com/api-keys). The fallback.
  64. Run the setup wizard to create the `.env` file and check dependencies:
  65. ```bash
  66. python scripts/setup.py
  67. ```
  68. It creates `~/.config/watch/.env` with placeholder lines for both keys. Edit the file and paste in your key. Without a key, the skill still works on any video that has captions, which covers most of YouTube.
  69. ## Usage
  70. After install, invoke the skill with the slash command:
  71. ```
  72. /watch-video https://www.youtube.com/watch?v=...
  73. /watch-video /path/to/local/video.mp4
  74. /watch-video https://youtu.be/abc123 focus on 2:00 to 3:00
  75. ```
  76. The skill is set to slash-only by default. This stops it from firing by accident. If you want auto trigger instead (Claude fires the skill on any "watch this video" or video URL request), edit the `description:` line at the top of [SKILL.md](SKILL.md). There is an inline note in that file that explains how.
  77. ## Direct CLI usage
  78. The pipeline can run on its own:
  79. ```bash
  80. python scripts/watch.py "<url-or-path>" [flags]
  81. ```
  82. Flags:
  83. - `--start T` and `--end T`. Focus on a section. Use `SS`, `MM:SS`, or `HH:MM:SS`.
  84. - `--max-frames N`. Cap on frame count. Default 80, hard max 100.
  85. - `--resolution W`. Frame width in pixels. Default 512.
  86. - `--fps F`. Override auto-fps. Capped at 2 fps.
  87. - `--whisper groq|openai`. Force a specific Whisper backend.
  88. - `--no-whisper`. Disable the Whisper fallback. Returns frames only if there are no captions.
  89. - `--out-dir DIR`. Keep working files in a specific folder. Default is a temp folder.
  90. The script prints a markdown report to stdout. The report lists every frame path, the transcript with timestamps, and the working folder.
  91. ## Troubleshooting
  92. **Whisper request returns 403.** `whisper.py` already sets a custom User-Agent to get past Cloudflare's block on the default Python UA. If you still see 403s, your key is probably invalid. Check it at the provider's console.
  93. **`python` command not found on Windows.** The Microsoft Store stub `python3` does not run scripts. Install Python 3.9 or later from [python.org](https://www.python.org/downloads/) and use `python` (or `py -3.9`).
  94. **yt-dlp fails on YouTube Shorts or age-gated content.** The bundled `download.py` lets yt-dlp pick its own player client. Members-only and region-locked content may still fail. yt-dlp will print a clear error when it does.
  95. **No transcript and no Whisper key.** The report will say `Transcript: none available`. Either add a Whisper key (see install above) or use `--no-whisper` for frames only.
  96. **Long videos (over 10 minutes) come back sparse.** That is on purpose. The frame budget caps at 100. For dense coverage of one section, pass `--start` and `--end` to use focused mode.
  97. ## Credits
  98. - Pipeline engine: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) (MIT). Brad wrote the auto-scaled frame extractor, the Whisper API client, and the setup wizard. The scripts are vendored under `scripts/`. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the upstream license.
  99. - Wrapper skill: [Newuxtreme](https://github.com/Newuxtreme). Includes the slash-only guard, the structured notes template, install and usage docs, and the original v1 local-Whisper pipeline.
  100. ## License
  101. MIT. See [LICENSE](LICENSE). Bundled scripts under `scripts/` keep their original MIT license. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.