Example Usage Scenarios for bradautomates/claude-video: Complete Guide to the /watch Skill

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, 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 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 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 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 parses VTT caption files. When captions are unavailable, it falls back to 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, 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 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 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, 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, 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:

# Simple transcript-only request (fast, no frames)

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

Generate scene-aware visual analysis:

# 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:

# 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:

# 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:

# 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:

# 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. 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 (orchestration), download.py (yt-dlp captions), frames.py (ffmpeg extraction), transcribe.py (VTT parsing), and 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
• 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 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 or via CLI flags, and rely on transcript-only queries when visual analysis isn't necessary. The 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, it works with any compatible host including Cursor, Copilot, Gemini CLI, and Codex, provided they support the slash-command invocation pattern.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}