# Understanding the Purpose of the SKILL.md File in Claude Video: The Canonical Contract for the Watch Skill

> Discover the SKILL.md file's purpose in Claude Video. It is the canonical contract for the watch skill, defining metadata, commands, and workflows for AI agent integration.

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

---

**[`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) serves as the canonical contract and single source of truth for the watch skill in the Claude Video repository, defining the metadata, user-invocable `/watch` command, and exact runtime workflows required for seamless integration across AI agent hosts including Claude Code, Codex, Cursor, and Gemini CLI.**

The [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file in the `bradautomates/claude-video` repository is not merely documentation—it is the executable specification that governs how the video analysis skill operates. Located at [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md), this markdown file contains the declarative configuration and procedural instructions that allow any compatible AI host to discover, validate, and execute the watch skill without host-specific modifications.

## Skill Metadata and Registration

The top front-matter section of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) functions as the skill's registration manifest. It declares the skill name (`watch`), semantic version, human-readable description, argument syntax patterns, and the specific tools the skill is permitted to invoke.

Crucially, this header marks the skill as **user-invocable**, which exposes the `/watch` slash command to end users within supported hosts. When Claude Code or similar environments load the skill, they parse this metadata to populate command palettes and validate permissions before allowing execution. This declarative approach ensures consistent behavior regardless of which AI agent hosts the skill.

## Runtime Path Resolution via SKILL_DIR

One of the most critical functions documented in [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) is the host-agnostic method for resolving the skill's installation directory. The file specifies that harnesses must compute `SKILL_DIR` as the absolute directory containing [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) itself, typically using `dirname` and `readlink -f` operations.

Because `SKILL_DIR` is derived from the location of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) rather than hardcoded paths or host-specific environment variables, the skill remains portable across different installation layouts. All bundled scripts—including [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py), and [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py)—are invoked relative to `${SKILL_DIR}/scripts/`, ensuring consistent file system operations whether the repository is cloned to `/usr/local/share/` or a user's home directory.

```bash

# Resolve SKILL_DIR in a host-agnostic manner

SKILL_DIR="$(dirname "$(readlink -f /path/to/SKILL.md)")"

# Invoke scripts relative to the discovered directory

python3 "${SKILL_DIR}/scripts/watch.py" --help

```

## Pre-Flight Setup Requirements

[`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) mandates a **Step 0** preflight process that runs [`scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/setup.py) before any video processing occurs. This validation step ensures required binaries—including `ffmpeg`, `yt-dlp`, and valid Whisper API keys—are present and functional on the host system.

By externalizing dependency checks into [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) and documenting the requirement in [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), the skill prevents runtime failures mid-processing. The setup script performs binary path resolution, version compatibility checks, and `.env` file scaffolding, failing fast with descriptive errors if the environment cannot support video download, frame extraction, or transcription workflows.

```bash

# Run the pre-flight check (silent on success)

python3 "${SKILL_DIR}/scripts/setup.py" --check

```

## Invocation Flow and Command Parsing

The file explicitly defines the user interaction protocol for the `/watch` command. When a user invokes `/watch <url-or-path> [question]`, the host must parse the arguments and delegate to [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py) with appropriate flags.

According to the specification in [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), the execution flow proceeds as follows: the host calls [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) with the video source and optional query parameters, reads the resulting frame paths from stdout, retrieves the generated transcript, and synthesizes a combined visual-transcript report for the user. This standardized interface allows the skill to handle various detail modes—such as `balanced` for scene-aware frames or `transcript` for audio-only analysis—without requiring host-level changes.

```bash

# Execute the watch skill on a YouTube URL with balanced detail

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/dQw4w9WgXcQ" \
    --detail balanced

# Focus on a 30-second segment with higher frame sampling

python3 "${SKILL_DIR}/scripts/watch.py" "video.mp4" \
    --start 00:45 --end 01:15 --fps 2

# Extract transcript only (no frames) for short clips

python3 "${SKILL_DIR}/scripts/watch.py" "https://vimeo.com/12345678" \
    --detail transcript

```

## Supporting Scripts and Implementation

While [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) defines the contract, the actual implementation resides in the `skills/watch/scripts/` directory. The orchestration flow relies on several specialized modules:

- **[`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py)** serves as the primary entry point, coordinating the download, frame extraction, and transcription pipeline.
- **[`scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/setup.py)** handles environment validation and dependency installation.
- **[`scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/download.py)** wraps `yt-dlp` to fetch videos and native captions from hosting platforms.
- **[`scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/frames.py)** implements the `ffmpeg`-based frame extraction logic using scene detection algorithms.
- **[`scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/transcribe.py)** manages caption selection and Whisper API fallback orchestration for audio transcription.

These implementations are invoked strictly through the interfaces defined in [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), maintaining a clean separation between the declarative contract and imperative logic.

## Cross-Platform Compatibility and Documentation

[`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) functions as the **authoritative descriptor** that guarantees consistent behavior across all supported Agent-Skills hosts. It contains usage recommendations, detail mode explanations, and failure-mode handling instructions that serve as the single source of truth for both developers integrating the skill and end users invoking it.

By standardizing the discovery mechanism, argument schema, and execution protocol in one machine-readable yet human-friendly file, `bradautomates/claude-video` eliminates host-specific customization code and ensures the watch skill operates identically whether invoked from Claude Code, Codex, Cursor, or emerging AI CLI tools.

## Summary

- **[`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md)** at [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) is the canonical contract defining the watch skill's metadata, commands, and execution flow.
- It declares the user-invocable `/watch` command and required tool permissions through standardized front-matter.
- The file specifies host-agnostic `SKILL_DIR` resolution, enabling portable script execution from `${SKILL_DIR}/scripts/`.
- It mandates a Step 0 preflight via [`scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/setup.py) to validate `ffmpeg`, `yt-dlp`, and Whisper API prerequisites.
- The document outlines the complete invocation flow from command parsing through [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) execution to final report generation.

## Frequently Asked Questions

### What information does the SKILL.md header contain?

The header contains YAML front-matter declaring the skill name (`watch`), version string, description, argument syntax, allowed tools list, and the `user_invocable` flag that exposes the `/watch` command to AI agent interfaces.

### How does Claude Code locate the watch skill scripts?

Claude Code computes `SKILL_DIR` by resolving the absolute directory containing [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), then executes scripts from `${SKILL_DIR}/scripts/`. This path resolution strategy works across different installation directories without requiring host-specific configuration or environment variables.

### Why is the pre-flight setup step required before running the watch skill?

The pre-flight step runs [`scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/setup.py) to verify that required binaries (`ffmpeg`, `yt-dlp`) and API credentials (Whisper) are present and functional. This prevents mid-process failures during video download or transcription and ensures the environment meets all runtime dependencies.

### Can the watch skill run without the SKILL.md file?

Technically the underlying Python scripts could execute independently, but the skill would lose its standardized integration contract. Without [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), AI hosts cannot discover the `/watch` command, validate permissions, or resolve script paths correctly, breaking the seamless integration with Claude Code and other agent platforms.