Understanding the File Structure of the Claude Video Skill: A Complete Technical Guide

The Claude Video skill resides in the skills/watch/ directory as a self-contained package containing SKILL.md as the canonical contract and eight specialized scripts in the scripts/ subdirectory that orchestrate video download, frame extraction, and transcription.

The bradautomates/claude-video repository structures the Claude Video skill as a portable, host-agnostic unit compatible with Claude Code, Codex, Cursor, and standalone installations. Examining the file structure of the Claude Video skill reveals how it maintains strict separation between the skill contract, pipeline logic, and host-specific plugin manifests while ensuring every path resolves relative to SKILL.md for cross-platform portability.

Root Skill Directory (skills/watch/)

The skill lives entirely within the skills/watch/ directory, designed as a single transferable unit that AI hosts can copy verbatim without modification.

The SKILL.md Contract

The SKILL.md file at skills/watch/SKILL.md serves as the single source of truth for the skill's behavior. This markdown file defines the /watch slash command interface, parameter specifications, and behavior contracts that Claude Code and other hosts parse to understand capabilities and invocation patterns.

The Scripts Subdirectory

All executable logic resides in skills/watch/scripts/, containing eight Python modules and one shell script that form a complete video processing pipeline. Each script handles a distinct phase of the workflow, from initial video acquisition to final text transcription.

Core Pipeline Scripts

The video processing workflow follows a linear pipeline orchestrated by dedicated modules with specific responsibilities.

watch.py - The Orchestration Layer

The watch.py script at skills/watch/scripts/watch.py functions as the primary entry point. It coordinates the entire pipeline by invoking downloaders, triggering frame extraction, and managing transcription workflows. When you invoke /watch in Claude Code, this module receives the command and delegates to specialized handlers based on arguments.

# Direct invocation example

python -m skills.watch.scripts.watch \
    --detail balanced \
    --out-dir /tmp/watch-run \
    https://youtu.be/dQw4w9WgXcQ

download.py - Video Acquisition

Located at skills/watch/scripts/download.py, this thin wrapper around yt-dlp handles source-agnostic video fetching. It abstracts the complexity of extracting video streams from URLs and localizes content to temporary storage for downstream processing.

frames.py - Frame Processing

The frames.py module (skills/watch/scripts/frames.py) manages ffmpeg-powered frame extraction with automatic FPS calculation and intelligent deduplication logic. It determines optimal sampling rates to balance visual detail against token consumption limits.

transcribe.py and whisper.py - Audio Processing

Audio processing splits between two specialized modules for separation of concerns. The transcribe.py script (skills/watch/scripts/transcribe.py) parses VTT caption files, handles text deduplication, and orchestrates Whisper API calls when native captions are unavailable or insufficient.

It delegates actual API communication to whisper.py (skills/watch/scripts/whisper.py), which implements pure-stdlib HTTP clients supporting both Groq and OpenAI Whisper endpoints without external dependencies.

Configuration and Build Infrastructure

Environment Setup and Validation

Configuration management resides in skills/watch/scripts/config.py, which reads user preferences and API keys from ~/.config/watch/.env. The setup.py script (skills/watch/scripts/setup.py) performs pre-flight validation, checking for required system binaries including ffmpeg and yt-dlp, and guides users through installation procedures when dependencies are missing.

Distribution Packaging

The build-skill.sh shell script (skills/watch/scripts/build-skill.sh) creates the distributable dist/watch.skill archive specifically formatted for upload to claude.ai and the Agent Skills marketplace. This build process bundles the contract, scripts, and metadata into a single installable unit.

# Build the distributable skill package

bash skills/watch/scripts/build-skill.sh

# Output: dist/watch.skill

Repository-Level Scaffolding

Beyond the self-contained skill package, the repository root contains host-specific integration layers and supporting materials that enable multi-platform deployment.

Plugin Manifests

Three distinct plugin directories support different AI host ecosystems:

• .claude-plugin/plugin.json - Manifest for Claude Code integration
• .codex-plugin/plugin.json - Configuration for Codex and general Agent Skills hosts
• .agents/plugins/marketplace.json - Marketplace listing metadata for generic agent interfaces

Testing and Documentation

The tests/ directory contains a comprehensive Pytest suite that validates skill behavior without requiring network access, mocking external APIs like Groq and OpenAI. Documentation spans README.md (which includes the file structure visualization), AGENTS.md, CLAUDE.md, and CHANGELOG.md for project metadata and version history. The hooks/ directory provides session-start status hooks specific to the Claude Code environment.

Summary

• The Claude Video skill lives under skills/watch/ as a self-contained package containing the SKILL.md contract and eight pipeline scripts
• watch.py serves as the entry point, orchestrating download, frame extraction, and transcription phases
• download.py wraps yt-dlp, frames.py handles ffmpeg processing, and transcribe.py/whisper.py manage audio-to-text conversion
• config.py loads user settings from ~/.config/watch/.env, while setup.py validates binary dependencies
• Host-specific manifests in .claude-plugin/, .codex-plugin/, and .agents/ enable cross-platform compatibility
• The build-skill.sh script generates distributable archives for marketplace deployment according to the bradautomates/claude-video source code

Frequently Asked Questions

Where is the main entry point for the Claude Video skill?

The primary entry point is skills/watch/scripts/watch.py, which orchestrates the complete video processing pipeline from URL download through frame extraction and transcription. This script receives the /watch command from Claude Code and coordinates downstream modules including download.py, frames.py, and transcribe.py based on the provided arguments.

How does the skill handle configuration and API keys?

Configuration management is centralized in skills/watch/scripts/config.py, which reads sensitive settings and API keys from ~/.config/watch/.env in the user's home directory. This separation keeps credentials out of version control while allowing the whisper.py module to authenticate with both Groq and OpenAI Whisper endpoints using pure-stdlib HTTP clients.

What is the purpose of the build-skill.sh script?

The build-skill.sh script located at skills/watch/scripts/build-skill.sh packages the skill into dist/watch.skill, a distributable archive formatted for upload to the Claude.ai marketplace and other Agent Skills hosts. This build process ensures the SKILL.md contract, all Python scripts, and metadata are bundled correctly for distribution via npx skills add or direct marketplace installation.

Can I run the Claude Video skill outside of Claude Code?

Yes, the skill operates as a standalone Python module compatible with any Agent Skills host or direct execution. You can invoke the entry point using python -m skills.watch.scripts.watch with command-line arguments like --detail balanced or --whisper openai, making it suitable for Codex, Cursor, and custom automation pipelines requiring programmatic video analysis.

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