# Example Usage Scenarios for bradautomates/claude-video: Complete Guide to the /watch Skill > Discover example usage scenarios for bradautomates/claude-video's /watch skill. Analyze videos with Claude by extracting frames and generating timestamped transcripts effortlessly. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: how-to-guide - Published: 2026-07-15 --- **The bradautomates/claude-video repository provides the `/watch` Agent Skill that enables Claude to ingest videos, extract frames, and generate timestamped transcripts for grounded multimodal analysis without manual preprocessing.** The bradautomates/claude-video repository implements a self-contained Agent Skill that eliminates the friction of video analysis. By installing this skill, you can invoke the `/watch` command to instantly process YouTube URLs or local video files, allowing Claude to see frames and hear audio to provide evidence-based answers. This guide explores practical example usage scenarios for bradautomates/claude-video, from debugging screen recordings to analyzing competitor content. ## What is the Claude Video /watch Skill? The `/watch` skill is a portable Agent Skill living in `skills/watch/` that integrates with any compatible host (Claude Code, Codex, Cursor, Copilot, Gemini CLI). According to the skill contract defined in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md), it processes video input through a pipeline of specialized Python modules to generate visual and textual context for AI reasoning. ## Core Workflow and Technical Architecture Understanding the execution flow helps you optimize usage scenarios. The skill orchestrates five main components located in `skills/watch/scripts/`: ### Entry Point and Orchestration [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) serves as the main entry point, parsing CLI arguments and coordinating the workflow. It determines whether to fetch existing captions, download video content, or trigger Whisper transcription based on the input parameters. ### Caption Extraction When processing YouTube URLs, [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) invokes **yt-dlp** to retrieve native captions if available. This avoids unnecessary transcription API calls for videos with existing subtitle tracks. ### Frame Extraction [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) runs **ffmpeg** to extract JPEG frames, implementing an auto-FPS algorithm with three distinct modes: `efficient`, `balanced`, and `token-burner`. It also supports optional scene-change detection to focus on visual transitions and reduce token costs. ### Transcript Generation [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py) parses VTT caption files. When captions are unavailable, it falls back to [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py), which provides a minimal stdlib-based client for the **Groq** or **OpenAI** Whisper APIs. ### Configuration Management User-specific defaults reside in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), reading from `~/.config/watch/.env`. This allows you to set persistent preferences like default detail modes or API provider selection without passing flags for every invocation. ## Real-World Usage Scenarios The repository documentation outlines several concrete workflows that demonstrate the core value proposition: **Claude sees the video and hears the audio**, enabling grounded answers without you watching the clip yourself. ### Competitor Content Analysis Analyze viral videos to identify successful hooks and patterns. By invoking `/watch` on a competitor's YouTube URL, Claude examines the opening frames and captions in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) to answer specific questions like "what hook did they open with?" based on actual visual and audio evidence. ### Bug Diagnosis from Screen Recordings Debug UI issues by processing local screen recordings. When you run `/watch` on a local `.mov` file, the frame extraction in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) pinpoints the moment of failure while the transcript captures any spoken error messages or narration. ### Long-Form Video Summarization Process lengthy content without watching it yourself. The skill extracts key frames and generates a complete transcript via [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py), allowing Claude to produce concise summaries of hour-long videos in seconds rather than minutes. ### Hype-Free Product Launch Analysis Cut through marketing fluff to identify substantive updates. The `/watch` command isolates sections containing actual feature demonstrations versus promotional content, grounding answers strictly in the video evidence extracted by the pipeline. ### Playlist-to-Notes Conversion Transform video playlists into searchable knowledge bases. Repeated invocations across a playlist generate per-video summaries that can be stored and indexed for later retrieval, creating a personal video research database without manual note-taking. ## Practical Command Examples These runnable examples assume the skill is installed (see the repository README). All commands route to [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), which outputs a markdown report containing frame paths with timestamps (`t=MM:SS`), the full transcript with source annotations, and metadata including video duration and frame budget details. Extract transcript-only for specific timestamps: ```bash # Simple transcript-only request (fast, no frames) /watch https://youtu.be/dQw4w9WgXcQ "what happens at the 30 second mark?" ``` Generate scene-aware visual analysis: ```bash # Extract scene-aware frames (default balanced mode) and get a summary /watch https://youtu.be/abc123xyz "summarize this video" ``` Focus on specific time windows to optimize token usage: ```bash # Focus on a specific time window – denser frame budget, lower token cost /watch https://youtu.be/abc123xyz --start 2:15 --end 2:45 "explain the key point here" ``` Debug local recordings: ```bash # Use a local screen-recording to debug a UI bug /watch ~/Videos/bug-repro.mov "what's breaking in this recording?" ``` Override default Whisper providers: ```bash # Force Whisper to use the OpenAI backend (useful if Groq key is unavailable) /watch https://youtu.be/xyz987 "provide a transcript" --whisper openai ``` Preserve duplicate frames for static presentations: ```bash # Disable duplication removal to keep every slide in a static presentation /watch https://youtu.be/lecture123 --no-dedup "list all slide titles" ``` ## Configuration and Customization The skill supports persistent configuration through `~/.config/watch/.env`, managed by [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). You can define: - **Default detail mode**: Set `efficient`, `balanced`, or `token-burner` as your standard extraction profile - **API provider preferences**: Default to Groq or OpenAI for Whisper transcription - **Frame processing options**: Configure scene-change sensitivity and deduplication thresholds This eliminates the need to pass CLI flags for every invocation when working within consistent workflows. ## Summary - The **bradautomates/claude-video** repository implements the `/watch` Agent Skill for multimodal video analysis - **Five core modules** handle the workflow: [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (orchestration), [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) (yt-dlp captions), [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) (ffmpeg extraction), [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) (VTT parsing), and [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) (API fallback) - **Three extraction modes** (`efficient`, `balanced`, `token-burner`) let you balance detail against token costs - **Configuration** persists in `~/.config/watch/.env` via [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) - **Common scenarios** include competitor analysis, bug debugging, summarization, and playlist archiving - **Claude** ingests the generated frame files and transcripts to provide evidence-based answers grounded in actual video content ## Frequently Asked Questions ### What video formats does bradautomates/claude-video support? The `/watch` skill supports any format compatible with **ffmpeg** and **yt-dlp**, including standard web formats (MP4, MOV, WebM) and YouTube URLs. Local file paths and direct video URLs both work as input sources. ### Do I need API keys to use the transcription features? You need either a **Groq** or **OpenAI** API key configured in `~/.config/watch/.env` only when processing videos without native captions. If the video has existing captions (CC/subtitles), [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) retrieves them via yt-dlp without requiring transcription API access. ### How do I reduce token costs when analyzing long videos? Use the `--start` and `--end` flags to focus on specific time windows, select the `efficient` mode in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) or via CLI flags, and rely on transcript-only queries when visual analysis isn't necessary. The [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) module automatically calculates optimal frame budgets based on video duration and your selected mode. ### Can I install this skill on platforms other than Claude Code? Yes. Because the skill is self-contained in `skills/watch/` and implements the standard Agent Skill contract defined in [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), it works with any compatible host including Cursor, Copilot, Gemini CLI, and Codex, provided they support the slash-command invocation pattern.