How SKILL.md Resolves Script Paths Across Different Hosts for Claude Video

SKILL.md in the bradautomates/claude-video repository resolves script paths in three environment-agnostic steps: reading the SKILL.md file to obtain its absolute path, deriving SKILL_DIR as the containing directory, and referencing all scripts via ${SKILL_DIR}/scripts/<script>.py to guarantee uniform behavior across Claude Code, Codex, Cursor, Gemini CLI, and other hosts.

The skills/watch/SKILL.md file serves as the single source of truth for path resolution in the Claude Video skill. Because AI coding assistants install skills to different locations—~/.claude/plugins/cache/..., ~/.codex/skills/..., ~/.agents/skills/..., and others—the skill deliberately avoids host-specific environment variables and instead computes paths from the known location of SKILL.md itself.

The Three-Step Resolution Mechanism

Step 1: Read SKILL.md to Obtain Its Absolute Path

Every host that implements the skill protocol returns the absolute file path when it reads SKILL.md. This path is the anchor for all subsequent resolution.

Step 2: Derive SKILL_DIR from the File Location

Lines 18-30 of skills/watch/SKILL.md explicitly instruct the host:

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

This derivation is deterministic: strip the filename from the absolute path, and the remaining directory is SKILL_DIR.

Step 3: Reference Scripts with ${SKILL_DIR}

All script invocations use the computed variable:

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/example"

This pattern ensures the same command works identically regardless of where the skill was installed.

Why This Approach Eliminates Host Dependencies

The bradautomates/claude-video skill deliberately avoids common pitfalls that break cross-host compatibility:

• No harness-specific variables: CLAUDE_SKILL_DIR, CODEX_SKILL_DIR, and similar variables are undefined on most hosts. Hardcoding any of these would cause immediate failures.
• No relative path assumptions: The skill does not assume SKILL.md lives at . or traverse upward from an unknown working directory.
• Single verification point: Lines 30-36 of skills/watch/SKILL.md include a guard block that checks scripts/watch.py exists under SKILL_DIR, aborting with a clear error if resolution failed.

Practical Implementation Examples

Basic Skill Invocation

# Host provides this value after reading SKILL.md

SKILL_DIR="/home/user/.codex/skills/watch"

# Verify installation integrity (lines 30-36 guard logic)

if [ ! -f "$SKILL_DIR/scripts/watch.py" ]; then
  echo "ERROR: scripts/watch.py not found under SKILL_DIR=$SKILL_DIR" >&2
  exit 1
fi

# Execute main entry point

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/example"

Running Setup and Helper Scripts

# Pre-flight configuration check

python3 "${SKILL_DIR}/scripts/setup.py" --json

# All helper scripts share the same resolution pattern

python3 "${SKILL_DIR}/scripts/setup.py" --install-deps

Runtime Path Computation in Python

Scripts can also compute SKILL_DIR internally when needed:

import pathlib

# __file__ is .../skills/watch/scripts/watch.py

SKILL_DIR = pathlib.Path(__file__).resolve().parent.parent

# Result: .../skills/watch

This self-computation is useful when scripts need to locate adjacent resources without relying on environment variables passed from the host.

Key Files in the Resolution System

File	Purpose	Link
skills/watch/SKILL.md	Defines the SKILL_DIR contract and host-agnostic command patterns	View on GitHub
skills/watch/SKILL.md lines 18-30	Explicit SKILL_DIR derivation instructions	View lines 18-30
skills/watch/SKILL.md lines 30-36	Installation verification guard block	View lines 30-36
skills/watch/scripts/watch.py	Main entry point invoked via ${SKILL_DIR}/scripts/watch.py	View on GitHub
skills/watch/scripts/setup.py	Helper script using identical resolution pattern	View on GitHub

Comparison: SKILL_DIR vs. Host-Specific Variables

Approach	Portability	Maintenance	Failure Mode
SKILL_DIR (computed from file location)	Universal across all hosts	Single definition in SKILL.md	Clear error if file missing
CLAUDE_SKILL_DIR	Fails on Codex, Cursor, Gemini CLI	Requires host-specific branches	Undefined variable, cryptic failure
Relative paths (./scripts/watch.py)	Breaks with working directory changes	Fragile to invocation context	File not found at runtime

The bradautomates/claude-video implementation chooses the first approach exclusively, as implemented in the source code.

Summary

• SKILL.md resolution is file-location-based: Derive SKILL_DIR from the absolute path of the SKILL.md file the host already read.
• No host-specific variables: Avoid CLAUDE_SKILL_DIR and equivalents to guarantee cross-host compatibility.
• Verify before execute: Lines 30-36 of skills/watch/SKILL.md include explicit existence checks that fail clearly rather than silently.
• Consistent pattern: All scripts—watch.py, setup.py, and future additions—use ${SKILL_DIR}/scripts/<name>.py uniformly.

Frequently Asked Questions

What happens if SKILL_DIR is set incorrectly?

The guard block at lines 30-36 of skills/watch/SKILL.md checks for scripts/watch.py existence and exits with a descriptive error message. This prevents cryptic Python import failures and immediately identifies path resolution problems.

Can this pattern work for skills installed via different package managers?

Yes. The bradautomates/claude-video pattern works for any installation method—git clone, symlink, rsync, or future host-specific plugin managers—because it only requires that the host correctly report the absolute path of SKILL.md when read.

Why not use Python's __file__ attribute exclusively?

While __file__ works inside Python scripts (as shown in the runtime computation example), the host must first invoke the correct Python file. SKILL_DIR bridges the shell-to-Python boundary, ensuring the initial python3 command targets the right script regardless of the current working directory.

Does this approach require any host-side configuration?

No. The bradautomates/claude-video skill is designed for zero host configuration. The host only needs to implement the standard skill protocol: read SKILL.md, return its absolute path, and execute the commands defined therein. All path logic is self-contained in the skill itself.

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