메뉴
Watch a video (URL or local path). Downloads with yt-dlp, extracts auto-scaled frames with ffmpeg, pulls the transcript from captions (or Whisper API fallback), and hands the result to Claude so it can answer questions about what's in the video.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/bradautomates/claude-video --skill watch명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | watch |
| version | 0.2.0 |
| description | Watch a video (URL or local path). Downloads with yt-dlp, extracts auto-scaled frames with ffmpeg, pulls the transcript from captions (or Whisper API fallback), and hands the result to Claude so it can answer questions about what's in the video. |
| argument-hint | <video-url-or-path> [question] |
| allowed-tools | Bash, Read, AskUserQuestion |
| homepage | https://github.com/bradautomates/claude-video |
| repository | https://github.com/bradautomates/claude-video |
| author | bradautomates |
| license | MIT |
| user-invocable | true |
You don't have a video input; this skill gives you one. A Python script gets captions first, optionally downloads the video, extracts frames as JPEGs (scene-aware, or fast keyframes at efficient detail), gets a timestamped transcript (native captions first, then Whisper API as fallback), and prints frame paths. You then Read each frame path to see the images and combine them with the transcript to answer the user.
SKILL_DIR (do this before any command)Every python3 ... command below runs a bundled script under SKILL_DIR/scripts/. Set SKILL_DIR to the absolute path of the directory containing THIS SKILL.md you just Read — your harness told you that path in the Read result. The scripts are always a direct sibling of this file (SKILL_DIR/scripts/watch.py), in every install layout:
Read ~/.claude/plugins/cache/claude-video/watch/<ver>/skills/watch/SKILL.md → SKILL_DIR=…/skills/watch
Read ~/.codex/skills/watch/SKILL.md → SKILL_DIR=~/.codex/skills/watch
Read ~/.agents/skills/watch/SKILL.md → SKILL_DIR=~/.agents/skills/watch
Substitute that literal path for ${SKILL_DIR} in every command. This works on every harness (Claude Code, Codex, Cursor, Gemini CLI, …) without relying on any harness-specific environment variable. Guard once at the start of a run:
SKILL_DIR="<absolute path of the directory containing the SKILL.md you Read>"
if [ ! -f "$SKILL_DIR/scripts/watch.py" ]; then
echo "ERROR: scripts/watch.py not found under SKILL_DIR=$SKILL_DIR" >&2
echo "Re-check the directory of the SKILL.md you Read and substitute it as SKILL_DIR." >&2
exit 1
fi
/watch invocation, silent on success)Python interpreter: every python3 ... command in this skill is for macOS/Linux. On Windows, substitute python — the python3 command on Windows is the Microsoft Store stub and will not run the script.
On the first /watch invocation in a session, use structured preflight so you can detect first-run setup:
python3 "${SKILL_DIR}/scripts/setup.py" --json
Branch on two fields:
can_proceed: true and first_run: false → setup is already done (the user may have deliberately skipped a Whisper key — that's allowed). Proceed to Step 1 without comment.first_run: true → genuine first-time setup. Do these in order:
missing_binaries is non-empty, run the installer first (it auto-installs on macOS / prints commands elsewhere — see below) and confirm the binaries land. Do not skip this and jump to preferences.~/.config/watch/.env (it only writes the template when the file is absent, so let it create the file before you write any values into it).~/.config/watch/.env and set SETUP_COMPLETE=true.can_proceed: false and first_run: false → setup was finished before but the environment regressed (e.g. missing_binaries after an OS change). Run the installer to remediate, then proceed. Don't re-ask preferences.A missing Whisper key is encouraged to fix, not required: on a genuine first run status will read needs_key even when binaries are present — that's your cue to encourage a key, not a blocker.
On follow-up /watch calls in the same session, use the silent check:
python3 "${SKILL_DIR}/scripts/setup.py" --check
This is a <100ms lookup. Exit 0 means /watch can run — this includes a user who finished setup without a Whisper key (keyless is allowed). On exit 0 the script emits nothing — proceed to Step 1 without comment. Do NOT announce "setup is complete" to the user — they don't need a status message on every turn. The only acceptable user-visible output from Step 0 is when remediation is required.
On non-zero exit, follow the table:
| Exit | Meaning | Action |
|---|---|---|
2 | Missing binaries (ffmpeg / ffprobe / yt-dlp) | Run installer |
3 | Genuine first run with no Whisper API key | Run installer to scaffold .env, then encourage a key (the user may decline — proceed with --no-whisper) |
4 | Both missing | Run installer, then encourage a key |
Exit 3 only fires before the user has completed setup. Once SETUP_COMPLETE=true is written, a keyless install returns exit 0 and is never nagged again.
The installer is idempotent — safe to re-run:
python3 "${SKILL_DIR}/scripts/setup.py"
On macOS with Homebrew, it auto-installs ffmpeg and yt-dlp. On Linux/Windows, it prints the exact install commands for the user to run. It scaffolds ~/.config/watch/.env with commented placeholders and default watch settings at 0600 perms.
If an API key is still missing after install: use AskUserQuestion to ask the user whether they have a Groq API key (preferred — cheaper, faster) or an OpenAI key. Then write it into ~/.config/watch/.env — set the matching GROQ_API_KEY=... or OPENAI_API_KEY=... line. If they don't want to set up Whisper, proceed with --no-whisper and tell them videos without native captions will come back frames-only.
First-run watch preference: after the installer has scaffolded ~/.config/watch/.env, use AskUserQuestion to ask one question:
AskUserQuestion options in this exact order — lightest to heaviest — and keep (recommended) on balanced even though it is not first (do not reorder to put the recommended option first):
transcript — no frames at all, transcript only (skips video download when captions exist).efficient — fast keyframe pass (cap 50).balanced (recommended) — scene-aware frames (cap 100, default).token-burner — scene-aware, uncapped (maximum fidelity; high token cost).Write the answer directly into ~/.config/watch/.env by setting the bare key on its own line — no trailing inline comment (a # note after the value can break parsing):
WATCH_DETAIL=balanced
Use the user's selected value. If they skip the question, keep the recommended default. Once dependencies, the API-key choice, and this preference are handled, write or update SETUP_COMPLETE=true in the same file. Do not ask this preference question again when SETUP_COMPLETE=true.
Structured mode (optional): python3 "${SKILL_DIR}/scripts/setup.py" --json emits {status, can_proceed, first_run, setup_complete, missing_binaries, whisper_backend, has_api_key, config_file, watch_detail, platform} where status is one of ready | needs_install | needs_key | needs_install_and_key. status describes the ideal state (a key is encouraged, so a keyless first run reads needs_key); can_proceed is the operational gate (binaries present AND a key is set OR setup was already completed). Branch on can_proceed/first_run to decide whether to run; use status to decide what to encourage.
Within a single session, you can skip Step 0 on follow-up /watch calls — once --check returned 0, nothing about the environment changes between turns.
.mp4, .mov, .mkv, .webm, etc.) and asks about it./watch <url-or-path> [question].--fps would imply more.WATCH_DETAIL in ~/.config/watch/.env, or --detail), not a single global cap:
transcript → no framesefficient → up to 50 (keyframes)balanced (default) → up to 100 (scene-aware)token-burner → uncapped (scene-aware; a soft warning prints past 250 frames)--max-frames N overrides whichever cap the mode would otherwise use.Step 1 — parse the user input. Separate the video source (URL or path) from any question the user asked. Example: /watch https://youtu.be/abc what language is this in? → source = https://youtu.be/abc, question = what language is this in?.
Step 2 — run the watch script. Pass the source verbatim. Do not shell-escape it yourself beyond normal quoting:
python3 "${SKILL_DIR}/scripts/watch.py" "<source>"
Optional flags:
--detail transcript|efficient|balanced|token-burner — fidelity/speed dial. transcript = no frames (transcript only, skips video download when captions exist); efficient = fast keyframes (cap 50); balanced = scene-aware frames (cap 100); token-burner = scene-aware, uncapped.--start T / --end T — focus on a section. Accepts SS, MM:SS, or HH:MM:SS. When either is set, fps auto-scales denser (see "Focusing on a section" below).--timestamps T1,T2,… — grab a frame at each of these absolute timestamps (SS, MM:SS, or HH:MM:SS). Use this after reading the transcript to capture deictic moments the presenter flags ("look here", "as you can see", "notice this") that visual selection alone may miss. See "Transcript-cue frames" below.--max-frames N — override the preset cap for tighter token budget (e.g. --max-frames 40)--resolution W — change frame width in px (default 512; bump to 1024 only if the user needs to read on-screen text)--fps F — override auto-fps (clamped to 2 fps max)--out-dir DIR — keep working files somewhere specific (default: an auto-generated tmp dir)--whisper groq|openai — force a specific Whisper backend (default: prefer Groq if both keys exist)--no-whisper — disable the Whisper fallback entirely (frames-only if no captions)--no-dedup — keep near-duplicate frames. By default a frame-delta pass drops frames that are visually near-identical to the previous kept one (held slides, static screen recordings, paused video) so the frame budget goes to distinct content; the report's Frames line notes how many were dropped. Pass this only if the user needs every sampled frame (e.g. judging subtle frame-to-frame motion).When the user asks about a specific moment — "what happens at the 2 minute mark?", "zoom into 0:45 to 1:00", "the first 10 seconds" — pass --start and/or --end. The script switches to focused-mode budgets, which are denser than full-video budgets (still capped at 2 fps, and still bounded by the detail-mode cap — the counts below assume the default balanced cap of 100; efficient tops out at 50):
Focused mode is the right call for:
Transcript is auto-filtered to the same range. Frame timestamps are absolute (real video timeline, not offset-from-start).
Examples:
# Last 10 seconds of a 1 minute video
python3 "${SKILL_DIR}/scripts/watch.py" video.mp4 --start 50 --end 60
# Zoom into 2:15 → 2:45 at 2 fps (60 frames)
python3 "${SKILL_DIR}/scripts/watch.py" "$URL" --start 2:15 --end 2:45 --fps 2
# From 1h12m to the end of the video
python3 "${SKILL_DIR}/scripts/watch.py" "$URL" --start 1:12:00
Step 3 — Read every frame path the script lists. The Read tool renders JPEGs directly as images for you. Read all frames in a single message (parallel tool calls) so you see them together. The frames are in chronological order with a t=MM:SS timestamp so you can align them to the transcript.
Step 4 — answer the user. You now have two streams of evidence:
captions = yt-dlp pulled native subs; whisper (groq) or whisper (openai) = transcribed by API).If the user asked a specific question, answer it directly citing timestamps. If they didn't ask anything, summarize what happens in the video — structure, key moments, notable visuals, spoken content.
This holds for transcript detail too: even with no frames, produce a summary like the other modes — do not paste the full transcript into chat. Synthesize structure, key moments, and spoken content with timestamps; quote only the lines that matter. Offer the raw transcript only if the user explicitly asks for it.
Step 5 — clean up. The script prints a working directory at the end. If the user isn't going to ask follow-ups about this video, delete it with rm -rf <dir>. If they might, leave it in place.
Default behavior comes from ~/.config/watch/.env:
WATCH_DETAIL=transcript|efficient|balanced|token-burner (default: balanced)At transcript detail, captions are enough to return a report without downloading video. If captions are missing, the script downloads audio only and tries Whisper. If no transcript can be produced, it reports the limitation clearly; re-run with --detail balanced for frames.
At efficient detail, the script downloads the video and extracts keyframes only (ffmpeg -skip_frame nokey) — a near-instant pass that lands frames on scene cuts. If a clip has fewer than 4 keyframes it falls back to uniform sampling.
At balanced / token-burner detail, the script extracts scene-aware frames: ffmpeg scene-change selection first, falling back to uniform sampling only when the video is effectively static. balanced caps at 100 frames; token-burner is uncapped. Frame report lines include both timestamp and selection reason. Extracted images are clamped to a maximum 1998px height for Claude Read compatibility.
Visual frame selection (scene/keyframe) can miss the moments a presenter explicitly flags — "look here", "as you can see", "notice this", "watch what happens" — because pointing at a slide is often a low visual change. --timestamps lets you force a frame at those exact moments. You decide which moments matter, by reading the transcript:
--detail transcript (or any detail) to get the timestamped transcript.--timestamps 4:32,7:10,9:55 (absolute source times). For a URL, point the second run at the downloaded local file in the work dir so it doesn't re-download.Behavior:
reason=transcript-cue) are merged into whatever --detail already selected, in chronological order.--start/--end, any cue timestamp outside the window is dropped (reported in the summary). Coordinates are always absolute source time.--detail transcript --timestamps … skips scene/keyframe sampling and returns only the cue frames (it will download the video to do so, since frames need pixels).The script gets a timestamped transcript in one of two ways:
ffmpeg -vn -ac 1 -ar 16000 -b:a 64k, ~0.5 MB/min) and uploads it to whichever Whisper API has a key configured:
whisper-large-v3. Preferred default: cheaper, faster. Get a key at console.groq.com/keys.whisper-1. Fallback. Get a key at platform.openai.com/api-keys.Both keys live in ~/.config/watch/.env. The script prefers Groq when both are set; override with --whisper openai to force OpenAI. Use --no-whisper to skip the fallback entirely.
python3 "${SKILL_DIR}/scripts/setup.py" (auto-installs ffmpeg/yt-dlp via brew on macOS, scaffolds the .env). For API key, ask the user via AskUserQuestion and write it to ~/.config/watch/.env.--start/--end rather than a sparse full-video scan.--whisper openai if Groq failed (or vice versa).This skill burns tokens primarily on frames. Order of magnitude:
--resolution to 1024 roughly quadruples the image tokens per frame. Only do it when necessary.If you already watched a video this session and the user asks a follow-up, do not re-run the script — you already have the frames and transcript in context. Just answer from what you have.
What this skill does:
yt-dlp locally to download the video and pull native captions when the source supports them (public data; the request goes directly to whatever host the URL points at)ffmpeg / ffprobe locally to extract frames as JPEGs and, when Whisper is needed, a mono 16 kHz audio clipapi.groq.com/openai/v1/audio/transcriptions) when GROQ_API_KEY is set (preferred — cheaper, faster)api.openai.com/v1/audio/transcriptions) when OPENAI_API_KEY is set and Groq is not, or when --whisper openai is forced--out-dir if specified) so Claude can Read them~/.config/watch/.env (mode 0600) to store the Whisper API key(s) and a SETUP_COMPLETE marker. As a fallback, also reads .env in the current working directoryWhat this skill does NOT do:
--no-whisperapi.groq.com, OpenAI key only goes to api.openai.com)~/.config/watch/.env — clean up the working directory when you're done (Step 5)Bundled scripts: scripts/watch.py (entry point), scripts/download.py (yt-dlp wrapper), scripts/frames.py (ffmpeg frame extraction), scripts/transcribe.py (caption selection + Whisper orchestration), scripts/whisper.py (Groq / OpenAI clients), scripts/setup.py (preflight + installer)
Review scripts before first use to verify behavior.