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

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 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, 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 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 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 itself, typically using dirname and readlink -f operations.

Because SKILL_DIR is derived from the location of 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, setup.py, and 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.

# 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 mandates a Step 0 preflight process that runs 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 and documenting the requirement in 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.

# 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 with appropriate flags.

According to the specification in SKILL.md, the execution flow proceeds as follows: the host calls 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.

# 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 defines the contract, the actual implementation resides in the skills/watch/scripts/ directory. The orchestration flow relies on several specialized modules:

• scripts/watch.py serves as the primary entry point, coordinating the download, frame extraction, and transcription pipeline.
• scripts/setup.py handles environment validation and dependency installation.
• scripts/download.py wraps yt-dlp to fetch videos and native captions from hosting platforms.
• scripts/frames.py implements the ffmpeg-based frame extraction logic using scene detection algorithms.
• 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, maintaining a clean separation between the declarative contract and imperative logic.

Cross-Platform Compatibility and Documentation

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 at 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 to validate ffmpeg, yt-dlp, and Whisper API prerequisites.
• The document outlines the complete invocation flow from command parsing through 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, 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 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, 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.

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