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

> Explore the Claude Video skill file structure within skills watch. Discover SKILL.md and eight scripts that manage video downloads, frame extraction, and transcription.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: architecture
- Published: 2026-07-28

---

**The Claude Video skill resides in the `skills/watch/` directory as a self-contained package containing [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file at [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script at [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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.

```python

# 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/frames.py) module ([`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) script ([`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) ([`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), which reads user preferences and API keys from `~/.config/watch/.env`. The [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) script ([`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/build-skill.sh) shell script ([`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/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.

```bash

# 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`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json)** - Manifest for Claude Code integration
- **[`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json)** - Configuration for Codex and general Agent Skills hosts
- **[`.agents/plugins/marketplace.json`](https://github.com/bradautomates/claude-video/blob/main/.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`](https://github.com/bradautomates/claude-video/blob/main/README.md) (which includes the file structure visualization), [`AGENTS.md`](https://github.com/bradautomates/claude-video/blob/main/AGENTS.md), [`CLAUDE.md`](https://github.com/bradautomates/claude-video/blob/main/CLAUDE.md), and [`CHANGELOG.md`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/download.py), [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), and [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/build-skill.sh) script located at [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.