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

> Learn how SKILL.md resolves script paths across hosts for Claude Video. Discover its three environment-agnostic steps for uniform script referencing in your projects.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-08-02

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) explicitly instruct the host:

```bash
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:

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) lives at `.` or traverse upward from an unknown working directory.
- **Single verification point**: Lines 30-36 of [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) include a guard block that checks [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py) exists under `SKILL_DIR`, aborting with a clear error if resolution failed.

## Practical Implementation Examples

### Basic Skill Invocation

```bash

# 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

```bash

# 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:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) | Defines the `SKILL_DIR` contract and host-agnostic command patterns | [View on GitHub](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) |
| [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) lines 18-30 | Explicit `SKILL_DIR` derivation instructions | [View lines 18-30](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md#L18-L30) |
| [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) lines 30-36 | Installation verification guard block | [View lines 30-36](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md#L30-L36) |
| [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) | Main entry point invoked via `${SKILL_DIR}/scripts/watch.py` | [View on GitHub](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) |
| [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) | Helper script using identical resolution pattern | [View on GitHub](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) |

## 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`](https://github.com/bradautomates/claude-video/blob/main/./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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) include explicit existence checks that fail clearly rather than silently.
- **Consistent pattern**: All scripts—[`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) checks for [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), return its absolute path, and execute the commands defined therein. All path logic is self-contained in the skill itself.