How the Claude Video /watch Skill Is Structured to Work Across Multiple AI Agent Hosts

The /watch skill operates as a self-contained unit inside skills/watch/ that resolves its runtime location from 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 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 you just Read. The scripts are always a direct sibling of this file (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 itself.

Path-Agnostic Script Entry Point

The main execution logic resides in skills/watch/scripts/watch.py. Hosts invoke this script using the runtime-resolved SKILL_DIR variable:

python3 "${SKILL_DIR}/scripts/watch.py" "<source>"

Because SKILL_DIR is calculated from the 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 file configures the skill for OpenAI Codex, Cursor, GitHub Copilot, and generic "npx skills add" workflows:

{
  "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 targets Claude Code specifically but uses the identical path structure:

{
  "skills": "./skills/"
}

Both manifests ensure that the complete watch folder—including 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 creates a reproducible archive using git:

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 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 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, which performs host-agnostic validation:

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:

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/abc123" --detail balanced --fps 2

The 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 location rather than host-specific environment variables.
• Dual manifest support: .codex-plugin/plugin.json and .claude-plugin/plugin.json both point to ./skills/, enabling installation on Claude Code, Codex, Cursor, and GitHub Copilot.
• Reproducible builds: build-skill.sh uses git archive to create identical zip bundles for all distribution channels.
• Host-agnostic execution: setup.py and 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 file as an anchor. According to the contract defined in skills/watch/SKILL.md, the runtime sets SKILL_DIR to the absolute path of the directory containing SKILL.md. This allows the scripts to locate siblings like 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 specifically for OpenAI Codex, Cursor, and GitHub Copilot, while .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 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 script creates the distributable using git archive HEAD:skills/watch, which outputs a zip file containing exactly one watch/ directory with 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.

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