# How the SKILL.md Contract Enables Cross-Host Compatibility in bradautomates/claude-video > Discover how the SKILL.md contract in bradautomates/claude-video ensures cross-host compatibility by enabling dynamic script path resolution. Learn more! - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: internals - Published: 2026-07-09 --- **The [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file acts as a universal contract that allows AI hosts like Claude Code, Codex, and Cursor to dynamically resolve script paths using the `${SKILL_DIR}` variable, eliminating the need for host-specific environment variables or installation paths.** The `claude-video` repository implements a portable skill architecture where a single [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) contract defines how multiple AI coding agents discover, validate, and execute video processing capabilities. This design ensures that the **watch** skill functions identically across Claude Code, Codex, Cursor, and Gemini CLI without requiring platform-specific modifications or hardcoded paths. ## Host-Agnostic Path Resolution The contract establishes a universal path resolution strategy that works regardless of where the skill is installed. According to the source code in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) lines 18-26, each host computes a `SKILL_DIR` variable that points to the **absolute directory containing the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file itself**: ```bash SKILL_DIR="" ``` This approach eliminates reliance on host-specific environment variables such as `CLAUDE_SKILL_DIR`. Whether the skill resides at `~/.claude/plugins/cache/.../skills/watch` (Claude Code), `~/.codex/skills/watch` (Codex), or `~/.agents/skills/watch` (Agents), the same substitution logic applies. All subsequent commands reference implementation scripts using this resolved variable: ```bash python3 "${SKILL_DIR}/scripts/watch.py" "" ``` ## Structured Front-Matter Metadata The top of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) contains YAML front-matter that provides machine-readable metadata for host registration. As defined in lines 1-12 of the contract file, this metadata includes the skill name, version, description, and permitted tools. Hosts parse this front-matter to automatically register the `/watch` slash command (derived from `name: watch` and `user-invocable: true`), enforce the allowlist of permitted tools (Bash, Read, AskUserQuestion), and provide repository links via the `homepage` and `repository` fields. Because this metadata is read directly from the same file that the host already fetched during initialization, the contract remains **in sync** across all installations. ## Self-Contained Skill Architecture The repository organizes the contract and its implementation scripts under a unified `skills/watch/` directory. Lines 14-17 of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) explicitly warn against moving [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) or the `scripts/` folder out of this directory, as doing so would break the cross-host compatibility mechanism. When a host executes `npx skills add …`, it copies the entire `skills/watch/` directory while preserving the relative layout required by the contract. This self-contained structure ensures that paths like [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py) remain valid relative to `SKILL_DIR` regardless of the absolute installation location on the filesystem. ## Pre-Flight and Runtime Orchestration The contract defines a deterministic execution flow that includes a **Step 0** pre-flight check. As specified in lines 39-48 of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), each host must run a Python helper script to validate the environment before executing the main watch logic: ```bash python3 "${SKILL_DIR}/scripts/setup.py" --json ``` This pre-flight check works identically across all hosts because it relies solely on the previously resolved `${SKILL_DIR}` variable. All subsequent steps—downloading video via [`scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/download.py), extracting frames via [`scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/frames.py), and generating transcripts via [`scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/transcribe.py)—follow the same host-agnostic pattern. ## Extensibility for Future Hosts Any future AI agent or coding assistant can adopt the watch skill without requiring code changes to the repository. The contract requires only three steps for host implementation: 1. **Read** the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file to extract metadata and execution steps. 2. **Compute** `SKILL_DIR` as the directory containing the contract file. 3. **Invoke** scripts using the `${SKILL_DIR}` substitution pattern. This abstraction eliminates the need for host-specific adapters or conditional logic, making the skill truly portable across the ecosystem. ## Summary The [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) contract in `bradautomates/claude-video` enables cross-host compatibility through four key mechanisms: - **Universal path resolution** via the `${SKILL_DIR}` variable that adapts to any installation location. - **Standardized metadata** in YAML front-matter for automatic command registration and tool enforcement. - **Self-contained directory structure** that preserves relative paths when copied between hosts. - **Deterministic execution flow** with pre-flight checks that run identically across Claude Code, Codex, Cursor, and Gemini CLI. ## Frequently Asked Questions ### What is the SKILL.md contract in the claude-video repository? The [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) contract is a markdown file located at [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) that serves as the single source of truth for the watch skill's metadata, execution steps, and path resolution logic. It contains YAML front-matter describing the skill's capabilities and instructions for computing `SKILL_DIR`, allowing any compatible AI host to execute the bundled Python scripts without prior configuration. ### How does SKILL_DIR resolution work across different AI hosts? Each host computes `SKILL_DIR` by taking the absolute path of the directory containing the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file it just read. According to lines 18-26 of the contract, this variable substitutes for the script location in all execution commands, such as `python3 "${SKILL_DIR}/scripts/watch.py"`. This method works universally because it relies on the contract file's location rather than hardcoded installation paths or environment variables. ### Why is the SKILL.md contract considered host-agnostic? The contract is host-agnostic because it specifies no dependencies on platform-specific features, environment variables, or filesystem layouts. By defining `SKILL_DIR` relative to the contract file itself and requiring only standard POSIX path resolution, the same instructions work whether the skill runs under Claude Code's plugin cache, Codex's skill directory, or any future Agent Skills implementation. ### Can I move the SKILL.md file to a different directory within the repository? No. Lines 14-17 of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) explicitly warn against moving the contract file or the `scripts/` directory out of the `skills/watch/` folder. Doing so would break the path resolution mechanism because `SKILL_DIR` is computed based on the contract's location, and all script references are relative to that root.