How to Run Specific Features of the bradautomates/claude-video Watch Skill

The bradautomates/claude-video repository provides a command-line interface through skills/watch/scripts/watch.py that allows you to download videos, extract frames at various detail levels, and generate transcripts using specific flags like --detail, --fps, and --timestamps.

The claude-video repository implements the /watch skill, a self-contained package designed for Agent-Skills hosts such as Claude Code, Codex, or Cursor. This guide explains how to run specific features of the watch skill using the command-line entry point and its various configuration options.

Understanding the Watch Skill Architecture

The watch skill is deliberately host-agnostic, resolving all paths relative to SKILL_DIR as defined in skills/watch/SKILL.md. The architecture centers on skills/watch/scripts/watch.py as the primary orchestrator, which coordinates four specialized modules: download.py handles video retrieval via yt-dlp, frames.py manages frame extraction algorithms, whisper.py provides speech-to-text fallback, and config.py stores default parameters like frame caps for each detail level.

This modular design allows you to invoke specific features—whether extracting keyframes, processing custom timestamps, or generating transcripts—without requiring host-specific environment variables.

Running the Watch Script Entry Point

All features are accessed through the main entry point at skills/watch/scripts/watch.py. The script accepts a video URL or local file path as the primary argument, followed by optional flags that control frame extraction, transcription, and output formatting.

The basic invocation syntax follows this pattern:

python -m skills.watch.scripts.watch "<video_url_or_path>" [OPTIONS]

Upon completion, the script prints a Markdown report to stdout and outputs extracted frames to a temporary directory (or a user-specified --out-dir), referencing paths like /tmp/watch-abc123/frames.

Configuring Frame Extraction Detail Levels

The --detail flag controls the frame extraction strategy by selecting specific algorithms implemented in skills/watch/scripts/frames.py. Each mode balances token consumption against visual coverage.

Efficient Mode (Keyframe Extraction)

Efficient mode uses extract_keyframes to select only visually distinct keyframes, minimizing token usage while preserving scene changes. This mode is ideal for long videos where you need representative coverage without excessive frame counts.

python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" --detail efficient

The underlying logic calculates target FPS using auto_fps based on video length and the frame budget defined in config.py.

Balanced Mode (Scene-Aware Extraction)

Balanced mode invokes extract_scene_or_uniform to perform scene detection, extracting frames at scene boundaries while maintaining uniform coverage within scenes. This provides richer context than efficient mode without reaching token-burner levels.

python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" --detail balanced

Transcript-Only Mode

To disable frame extraction entirely and retrieve only captions or transcripts, use transcript mode. This skips all frame processing and focuses solely on subtitle download or Whisper transcription.

python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" --detail transcript

Customizing Frame Selection Parameters

Beyond preset detail levels, the watch skill provides granular control over frame selection through timestamp specification, frame rate overrides, and resolution limits.

Extracting Frames at Specific Timestamps

Use the --timestamps flag to extract frames only at explicit cue points. The extract_at_timestamps function in frames.py handles the precise seeking and extraction logic.

python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" \
    --timestamps "00:10,01:23,02:45"

When combined with --detail transcript, this retrieves only the specified frames without additional scene-based extraction.

Adjusting FPS, Resolution, and Frame Caps

Override automatic calculations by specifying explicit parameters:

• --fps: Set target frames per second (bypasses auto_fps calculations)
• --resolution: Set frame width in pixels (e.g., 720 for 720px width)
• --max-frames: Hard limit the total frame count regardless of detail level defaults

python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" \
    --resolution 720 --fps 2.5 --max-frames 30

Processing Local Files and Video Segments

The watch skill handles both remote URLs and local video files, with options to focus processing on specific time ranges.

Processing Local Video Files

Pass a local file path instead of a URL. Ensure the file path is absolute or relative to the execution context:

python -m skills.watch.scripts.watch "/path/to/local_video.mp4"

Focusing on Time Ranges (--start and --end)

Use --start and --end flags to process only a sub-range of the video. This is particularly effective when combined with efficient mode for targeted analysis:

python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" \
    --start 01:00 --end 03:30 --detail efficient

Configuring Transcription and Whisper Integration

When caption files are unavailable, watch.py falls back to Whisper transcription via skills/watch/scripts/whisper.py. This module supports both Groq and OpenAI backends.

Disabling Whisper Fallback

To prevent automatic transcription attempts (useful when API keys are unavailable), use the --no-whisper flag:

python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" --no-whisper

Configuring API Keys

The load_api_key function in whisper.py reads API credentials from ~/.config/watch/.env. Create this file with your preferred provider's key:

# ~/.config/watch/.env

OPENAI_API_KEY=sk-your-key-here

# or

GROQ_API_KEY=gsk-your-key-here

Selecting Whisper Backends

Force a specific transcription backend using the --whisper flag. Valid options are openai or groq:

python -m skills.watch.scripts.watch "local_video.mp4" --whisper openai

The transcribe_video function routes the request to the specified endpoint and formats the output for inclusion in the final Markdown report.

Environment Setup and Configuration

Default behaviors are governed by skills/watch/scripts/config.py, which defines frame caps for each detail level and other constants. You do not need to modify this file to run specific features; instead, use the command-line flags to override defaults at runtime.

The skill requires yt-dlp for video downloading (handled automatically by download.py) and optional Whisper dependencies only if transcription fallback is enabled. All paths resolve relative to the skill directory, ensuring portability across different Agent-Skills hosts.

Summary

• Entry point: Run skills/watch/scripts/watch.py with a URL or file path to access all features.
• Detail levels: Use --detail efficient for keyframes, --detail balanced for scene-aware extraction, or --detail transcript for text-only output.
• Frame customization: Control extraction with --timestamps, --fps, --resolution, and --max-frames flags.
• Segment processing: Focus on specific time ranges using --start and --end parameters.
• Transcription control: Manage Whisper via --no-whisper, --whisper openai, and API keys in ~/.config/watch/.env.

Frequently Asked Questions

How do I extract frames only at specific moments in the video?

Use the --timestamps flag followed by comma-separated timestamps in HH:MM:SS or MM:SS format. The extract_at_timestamps function in frames.py processes these cues and extracts frames only at those specific points, bypassing the automatic FPS calculation.

What is the difference between efficient and balanced detail modes?

Efficient mode uses extract_keyframes to grab only visually distinct keyframes using auto_fps_focus calculations, minimizing token count. Balanced mode uses extract_scene_or_uniform to detect scene boundaries and extract frames at transitions while maintaining uniform coverage within scenes, providing more context at higher token cost.

Where does the watch skill store API keys for transcription?

The load_api_key function in whisper.py looks for a file at ~/.config/watch/.env. Store your OPENAI_API_KEY or GROQ_API_KEY in this file; the skill reads these values when you use the --whisper flag or when automatic transcription is required.

Can I process only a portion of a long video without downloading the whole file?

Yes. Use the --start and --end flags to specify time ranges. While download.py retrieves the video, the frame extraction logic in watch.py respects these boundaries when processing, allowing you to focus analysis on specific segments without manual pre-trimming.

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