# How SKILL.md Resolves Script Paths in a Harness-Agnostic Way

> Learn how SKILL.md resolves script paths harness-agnostic. Discover its method of deriving SKILL_DIR from absolute paths for robust script referencing.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-13

---

**SKILL.md resolves script paths in a harness-agnostic way by deriving `SKILL_DIR` from the absolute path returned when the harness reads the skill file, then referencing all bundled Python scripts relative to that directory.**

The `bradautomates/claude-video` repository demonstrates a portable approach to skill development that works across multiple AI agent hosts including Claude Code, Codex, Cursor, and Gemini CLI. By eliminating harness-specific environment variables and using absolute path derivation, the watch skill ensures consistent script execution regardless of where the skill is installed on the host system.

## How SKILL.md Establishes SKILL_DIR

The resolution strategy centers on treating the skill file location as the single source of truth for all path calculations. This approach eliminates assumptions about standard installation directories or host-specific conventions.

### Reading the Skill File

Every Agent Skills host provides the absolute path of the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file when it executes the `Read` tool. This path becomes the foundation for all subsequent file operations within the skill. Unlike static configuration files, this dynamic resolution adapts automatically to the actual installation location on any given machine.

### Deriving the Directory Path

`SKILL_DIR` is defined as the directory containing the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file itself. As documented in the "Resolve `SKILL_DIR`" section of [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md)【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/SKILL.md#L18-L28】, the sibling `scripts/` folder lives immediately next to the skill definition file. This relationship remains constant regardless of whether the skill is installed in `~/.claude/skills/`, `~/.codex/skills/`, or any custom location.

The derivation follows this pattern:

```bash

# SKILL_DIR is set from the Read result (harness-provided absolute path)

SKILL_DIR="/home/user/.codex/skills/watch"   # Example value from harness

# All scripts are referenced relative to this absolute base

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

```

## Eliminating Harness-Specific Dependencies

Older implementations relied on environment variables like `${CLAUDE_SKILL_DIR}`, which only exists in Claude Code environments. According to the changelog【/cache/repos/github.com/bradautomates/claude-video/main/CHANGELOG.md#L17】 and agents guide【/cache/repos/github.com/bradautomates/claude-video/main/AGENTS.md#L22】, this limitation prevented skills from running on other hosts. By using the path supplied by the `Read` result, the same logic executes correctly on every supported platform without conditional checks for host-specific variables.

## Validating Script Availability

Before executing any commands, [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) includes a defensive guard clause that verifies the expected directory structure exists. This check appears in lines 31-36 of the skill contract【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/SKILL.md#L31-L36】:

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

```

This validation ensures early failure with a clear error message if the skill layout is unexpected, preventing cryptic failures during script execution.

## Executing Scripts with Absolute Paths

All script invocations use the derived `${SKILL_DIR}` variable as a prefix. For example, lines 139-141 of [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md)【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/SKILL.md#L139-L141】 demonstrate calling the main watch script:

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

```

This pattern applies consistently across all bundled utilities:
- **setup.py**: `python3 "${SKILL_DIR}/scripts/setup.py" --json`
- **watch.py**: `python3 "${SKILL_DIR}/scripts/watch.py" "<video_url>"`
- **download.py**: Referenced similarly via `${SKILL_DIR}/scripts/download.py`

Because `${SKILL_DIR}` is an absolute path, these commands function correctly regardless of the current working directory or installation prefix.

## Cross-Harness Compatibility Mechanism

The harness-agnostic approach works because of three architectural decisions:

- **Absolute path guarantee**: The harness supplies the complete file location via the `Read` tool, which is always correct for the current installation context.
- **No hardcoded paths**: The skill never references `$HOME/.claude/...` or other host-specific directories.
- **Consistent variable reuse**: The same `SKILL_DIR` variable serves every subsequent script call, ensuring deterministic behavior across all operations.

## Summary

- **SKILL.md** in `bradautomates/claude-video` defines a portable method for script path resolution that functions across Claude Code, Codex, Cursor, and Gemini CLI.
- The **SKILL_DIR** variable derives from the absolute path returned when the harness reads the skill file, not from environment variables.
- All Python scripts in `skills/watch/scripts/`—including [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py), [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), and [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py)—are referenced via `${SKILL_DIR}/scripts/<script>.py`.
- A validation check ensures [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py) exists before execution, providing clear error messages for malformed installations.
- This approach replaced the older `${CLAUDE_SKILL_DIR}` method, eliminating host-specific dependencies.

## Frequently Asked Questions

### What makes this approach harness-agnostic compared to older methods?

Previous implementations relied on the `${CLAUDE_SKILL_DIR}` environment variable, which only exists in Claude Code. The current implementation in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) uses the absolute path provided by the harness's `Read` tool, which works identically across Claude Code, Codex, Cursor, and Gemini CLI without requiring host-specific conditional logic.

### How does the skill handle different installation directories across hosts?

Because `SKILL_DIR` is derived from the actual location of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) at runtime, the skill automatically adapts to any installation prefix. Whether the skill resides in `~/.claude/skills/watch/`, `~/.codex/skills/watch/`, or a custom path, the `${SKILL_DIR}` variable always points to the correct base directory for resolving [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py) and other bundled files.

### What happens if the scripts directory is missing from the installation?

The skill includes a validation guard in [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) that checks for the existence of `$SKILL_DIR/scripts/watch.py` before executing any commands. If the file is missing, the script outputs a clear error message indicating the problem and exits immediately, preventing confusing failures during later execution steps.

### Which files demonstrate the harness-agnostic path resolution pattern?

The primary implementation appears in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md), which defines the `SKILL_DIR` resolution logic. Supporting documentation appears in [`AGENTS.md`](https://github.com/bradautomates/claude-video/blob/main/AGENTS.md) (explaining the strategy) and [`CHANGELOG.md`](https://github.com/bradautomates/claude-video/blob/main/CHANGELOG.md) (documenting the transition from environment variables). The actual scripts referenced by this pattern include [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) and [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py).