# How the Claude Video /watch Skill Is Structured to Work Across Multiple AI Agent Hosts > Discover how the Claude Video /watch skill achieves cross-host compatibility. Learn how it resolves runtime location from SKILL.md for seamless execution across Claude Code, Codex, Cursor, GitHub Copilot, and more. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: architecture - Published: 2026-08-01 --- **The /watch skill operates as a self-contained unit inside `skills/watch/` that resolves its runtime location from [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) rather than using host-specific environment variables, allowing identical execution across Claude Code, Codex, Cursor, GitHub Copilot, and other Agent-Skills-compatible hosts.** The `bradautomates/claude-video` repository demonstrates a host-agnostic architecture for AI agent skills. By packaging the **/watch** command as a portable, path-agnostic module, the codebase eliminates hardcoded dependencies on specific agent platforms. This design ensures that whether you install the skill via Claude AI's marketplace, Codex's plugin system, or generic npx workflows, the underlying functionality behaves identically. ## The Self-Contained Skill Architecture The entire **watch** skill lives within a single directory tree at `skills/watch/`, making it an atomic unit that any host can copy and execute without modification. ### Single-Source Contract via SKILL.md The file [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) serves as the canonical contract between the skill and its host. Its front-matter declares the slash command (`name: watch`, `user-invocable: true`) that exposes `/watch` to users. Crucially, this file also defines the runtime resolution strategy: > "Set `SKILL_DIR` to the **absolute path of the directory containing THIS [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md)** you just Read. The scripts are always a direct sibling of this file ([`SKILL_DIR/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/SKILL_DIR/scripts/watch.py))." This self-referential path resolution ensures that hosts never need to export variables like `CLAUDE_SKILL_DIR` or `CODEX_SKILL_DIR`. Instead, the agent derives `SKILL_DIR` dynamically from the location of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) itself. ### Path-Agnostic Script Entry Point The main execution logic resides in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). Hosts invoke this script using the runtime-resolved `SKILL_DIR` variable: ```bash python3 "${SKILL_DIR}/scripts/watch.py" "" ``` Because `SKILL_DIR` is calculated from the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) location at runtime, this command works identically whether the skill is installed under Claude Code (`~/.claude/plugins/...`), Codex (`~/.codex/...`), or generic agent directories (`~/.agents/...`). ## Host-Agnostic Manifest Files Rather than embedding host-specific logic, the repository provides separate manifest files that all point to the same skill directory. ### Codex/Cursor/Copilot Support The [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json) file configures the skill for OpenAI Codex, Cursor, GitHub Copilot, and generic "npx skills add" workflows: ```json { "skills": "./skills/" } ``` This entry instructs the Agent-Skills CLI to copy the entire `skills/` directory during installation. ### Claude Code Integration Similarly, [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json) targets Claude Code specifically but uses the identical path structure: ```json { "skills": "./skills/" } ``` Both manifests ensure that the complete `watch` folder—including [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and its sibling `scripts/` directory—is copied wholesale during installation. ## Distribution and Installation Mechanics The repository includes tooling to ensure that every host receives an identical skill bundle regardless of distribution channel. ### Building the Distributable Bundle The script [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) creates a reproducible archive using git: ```bash bash skills/watch/scripts/build-skill.sh ``` This command executes `git archive` targeting `HEAD:skills/watch`, producing `dist/watch.skill` containing exactly one top-level directory (`watch/`) with [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and `scripts/`. This guarantees that **every host receives an identical layout** when the skill is uploaded to Claude AI or installed via `npx`. ### Marketplace Listings The [`.agents/plugins/marketplace.json`](https://github.com/bradautomates/claude-video/blob/main/.agents/plugins/marketplace.json) file provides a marketplace descriptor for generic agent platforms. This file references the same `watch` folder structure, maintaining consistency across distribution channels. ## Runtime Execution Flow Once installed, the skill executes identically across all hosts through a standardized pre-flight and entry sequence. ### Pre-Flight Validation with setup.py Every `/watch` invocation begins by running [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py), which performs host-agnostic validation: ```bash python3 "${SKILL_DIR}/scripts/setup.py" --json ``` This script checks for `ffmpeg` and `yt-dlp` binaries, validates optional Whisper API keys, and scaffolds a hidden `.env` file under `~/.config/watch`. Because it launches from the same `SKILL_DIR`-relative location on every platform, behavior remains consistent. ### Main Entry Point in watch.py After pre-flight validation, the host executes the main logic: ```bash python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/abc123" --detail balanced --fps 2 ``` The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script handles video downloading, frame extraction, and optional transcription without requiring any host-specific configuration. ## Summary - **Self-contained packaging**: The entire skill resides in `skills/watch/`, ensuring atomic installation across hosts. - **Runtime path resolution**: `SKILL_DIR` derives from the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) location rather than host-specific environment variables. - **Dual manifest support**: [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json) and [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json) both point to `./skills/`, enabling installation on Claude Code, Codex, Cursor, and GitHub Copilot. - **Reproducible builds**: [`build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/build-skill.sh) uses `git archive` to create identical zip bundles for all distribution channels. - **Host-agnostic execution**: [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) and [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) operate relative to `SKILL_DIR`, eliminating platform-specific logic from the runtime. ## Frequently Asked Questions ### How does the skill determine its installation directory without host-specific variables? The skill uses the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file as an anchor. According to the contract defined in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md), the runtime sets `SKILL_DIR` to the **absolute path of the directory containing [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md)**. This allows the scripts to locate siblings like [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py) without relying on environment variables such as `CLAUDE_SKILL_DIR` or `CODEX_SKILL_DIR`. ### Can I install this skill on AI agents other than Claude Code? Yes. The repository includes [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json) specifically for OpenAI Codex, Cursor, and GitHub Copilot, while [`.agents/plugins/marketplace.json`](https://github.com/bradautomates/claude-video/blob/main/.agents/plugins/marketplace.json) supports generic agent platforms. All manifests reference the same `./skills/` directory, ensuring the `/watch` command behaves identically across any Agent-Skills-compatible host. ### What happens during the pre-flight check when I run /watch? Before executing the main logic, the skill automatically runs [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) to validate dependencies. This script checks for required binaries (`ffmpeg`, `yt-dlp`), verifies optional Whisper API configurations, and creates a configuration directory at `~/.config/watch/.env`. The check runs from the `SKILL_DIR`-relative path, ensuring consistent behavior regardless of which AI agent host invokes it. ### How is the skill packaged for distribution to Claude AI? The [`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) script creates the distributable using `git archive HEAD:skills/watch`, which outputs a zip file containing exactly one `watch/` directory with [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and the `scripts/` folder. This standardized structure guarantees that the Claude AI marketplace receives the same file layout as installations via `npx skills add`.