How Claude Video Ensures Consistent Behavior Across Different Hosts

Claude Video implements a self-contained skill package that isolates all runtime code from the host environment, guaranteeing identical execution whether running in Claude Code, Codex, Cursor, Copilot, or any other Agent Skills host.

The bradautomates/claude-video repository solves environment drift by treating the entire skills/watch/ directory as an immutable deployment unit. This architecture ensures consistent behavior across different hosts through strict host-agnostic boundaries and portable path resolution strategies.

Self-Contained Skill Architecture

The Skill Contract and Runtime Co-location

Unlike traditional CLI tools that separate documentation from execution, Claude Video colocates its skill contract (SKILL.md) with its runtime scripts (scripts/…) inside skills/watch/. As documented in AGENTS.md, this design eliminates the "missing scripts" problem that previously broke installations on non-Claude hosts by ensuring the contract and its implementation always travel together.

Single-Folder Deployment Model

The installation process—whether invoked via npx skills add or manual cloning—copies the entire skills/watch/ directory as a single atomic unit. According to the source code in AGENTS.md, this single-folder deployment ensures that the contract and its scripts remain together, preventing the classic configuration drift where host-specific paths cause runtime failures.

Host-Agnostic Path Resolution

The SKILL.md file defines SKILL_DIR as the absolute path of the directory containing this SKILL.md (line 20). Every script invocation uses ${SKILL_DIR}/scripts/... rather than host-specific variables like ${CLAUDE_SKILL_DIR}. This resolution strategy works identically across Claude Code, Codex, Cursor, Copilot, and any other Agent Skills host, as the variable resolves at runtime to wherever the skill is physically located.

You can invoke the main entry point directly using this portable path resolution:

# Assume SKILL_DIR points to the folder containing SKILL.md

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

Synchronized Command Generation

The slash command /watch is generated directly from the front-matter in SKILL.md (name: watch, user-invocable: true) at line 2. Because the command derives from the same file that drives runtime execution, behavior stays synchronized across all surfaces. There is no separate command wrapper that could drift out of sync with the implementation.

Users invoke the skill identically on any host:

/watch https://youtu.be/dQw4w9WgXcQ  Explain the chorus.

Portable Configuration and Pre-Flight Checks

The scripts/setup.py module (line 2) performs host-independent validation of prerequisites including ffmpeg and yt-dlp installation. It also scaffolds a portable configuration under ~/.config/watch/.env. Because the same script executes on every invocation regardless of host, each environment enforces identical prerequisites and configuration structure.

Run the setup explicitly to verify your environment:

python3 "${SKILL_DIR}/scripts/setup.py" --json   # Emits JSON status, creates ~/.config/watch/.env

Deterministic Distribution Packaging

The scripts/build-skill.sh script (line 5) archives the entire skills/watch/ subtree into a single .skill zip file. This packaging preserves the exact directory layout required by every host, ensuring that the distributed artifact matches the development structure byte-for-byte. The resulting archive contains everything needed to run the skill without additional host configuration.

Create the distributable package:

bash skills/watch/scripts/build-skill.sh   # Produces dist/watch.skill

Summary

• Self-contained skills/watch/ directory ensures all dependencies and scripts travel together as a single unit
• SKILL_DIR variable provides host-agnostic path resolution without hardcoding host-specific environment variables
• Front-matter driven command generation prevents interface drift between the slash command and its implementation
• setup.py pre-flight checks enforce consistent prerequisites across all environments
• .skill archives preserve exact directory layouts for deterministic distribution

Frequently Asked Questions

What makes Claude Video "host-agnostic"?

Claude Video avoids host-specific variables like ${CLAUDE_SKILL_DIR} by resolving paths relative to SKILL_DIR, which is defined in SKILL.md as the absolute path of the directory containing the contract file. This allows the same code to run in Claude Code, Codex, Cursor, or Copilot without modification, as each host resolves the variable to its own installation path at runtime.

How does the skill handle missing dependencies on different systems?

The scripts/setup.py file runs host-independent checks for ffmpeg and yt-dlp availability before executing video processing tasks. If dependencies are missing, the script emits a JSON status report detailing the failure. This ensures that every host enforces identical prerequisites, preventing "works on my machine" scenarios where one environment has hidden system dependencies.

Can I run Claude Video outside of Claude Code?

Yes. Because the skill uses standard Python 3 and shell scripts with no proprietary APIs, you can invoke scripts/watch.py directly using the ${SKILL_DIR} path resolution pattern. This makes the skill portable to any environment that can execute Python, including local development machines or CI/CD pipelines, provided the setup script has initialized the ~/.config/watch configuration directory.

Why does the skill use a .skill archive format?

The .skill file produced by build-skill.sh is a standard zip archive that preserves the exact directory structure of skills/watch/. This format ensures that when the skill is installed on different hosts, the relative paths between SKILL.md and scripts/ remain constant. The archive functions as an immutable artifact, guaranteeing that the version running in production matches the version tested during development.

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