How the SKILL.md Contract Enables Cross-Host Compatibility in bradautomates/claude-video

The 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 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 lines 18-26, each host computes a SKILL_DIR variable that points to the absolute directory containing the SKILL.md file itself:

SKILL_DIR="<absolute path of the directory containing the SKILL.md you Read>"

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:

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

Structured Front-Matter Metadata

The top of 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 explicitly warn against moving 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 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, each host must run a Python helper script to validate the environment before executing the main watch logic:

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, extracting frames via scripts/frames.py, and generating transcripts via 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 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 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 contract is a markdown file located at 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 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 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.

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