# How SKILL.md Path Resolution Works Across Different Agent Hosts in claude-video

> Learn how SKILL.md path resolution works across agent hosts like Claude Code, Codex, Cursor, and Gemini CLI. Ensure consistent script execution without host specific variables.

- 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) path is resolved by deriving `SKILL_DIR` from the absolute path of the file returned when the skill harness reads [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), ensuring consistent script execution across Claude Code, Codex, Cursor, and Gemini CLI without host-specific environment variables.**

The `bradautomates/claude-video` repository implements a portable skill system that runs across multiple AI agent hosts. The key to this portability lies in how the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) path is resolved, allowing the same skill bundle to execute correctly regardless of whether it's installed under Claude Code's plugin cache, Codex's skill directory, or a generic agent path.

## Understanding SKILL_DIR Resolution

When a `/watch` skill is invoked, the harness first determines **`SKILL_DIR`**, the absolute directory containing the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file. This variable serves as the anchor for all subsequent script calls.

According to the contract defined in **[`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md)** (lines 18-28), the resolution follows this sequence:

1. The skill harness `Read`s the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file from its installed location
2. The read result includes the absolute path of the file (e.g., [`/home/user/.codex/skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main//home/user/.codex/skills/watch/SKILL.md))
3. `SKILL_DIR` is set to the **parent directory** of that file
4. All scripts are referenced as `${SKILL_DIR}/scripts/...`

This approach eliminates dependency on host-specific environment variables like `$CLAUDE_SKILL_DIR` or `$CODEX_SKILL_DIR`, making the skill truly portable across different agent implementations.

## Host-Specific Installation Layouts

Because `SKILL_DIR` is calculated dynamically from the read result, the same skill works across varying directory structures:

| Host | Where [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) Lives | Calculated `SKILL_DIR` |
|------|------------------------|------------------------|
| Claude Code | `~/.claude/plugins/cache/claude-video/watch/<ver>/skills/watch/` | `…/skills/watch` |
| Codex / Cursor | `~/.codex/skills/watch/` | `~/.codex/skills/watch` |
| Agents (generic) | `~/.agents/skills/watch/` | `~/.agents/skills/watch` |

The skill bundle remains identical across all platforms. Only the absolute path returned by the harness differs, and `SKILL_DIR` adapts accordingly.

## Script Execution Flow

After resolving `SKILL_DIR`, the skill executes bundled scripts using consistent relative paths. The entry points include:

- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)** - Main entry point for video processing
- **[`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py)** - Pre-flight verification of binaries and environment
- **[`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py)** - yt-dlp wrapper for video acquisition
- **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)** - ffmpeg frame extraction utility

All scripts are referenced uniformly as `${SKILL_DIR}/scripts/<filename>`, ensuring the skill works regardless of where the repository is cloned or installed.

## Validation and Error Handling

The skill includes a guard block that validates the existence of required scripts before execution. As documented in **[`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md)** (lines 30-36), if the derived [`SKILL_DIR/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/SKILL_DIR/scripts/watch.py) file is missing, the skill aborts with a clear error message.

This validation prevents cryptic failures when the skill bundle is corrupted or installed incorrectly, directing users to check the `SKILL_DIR` calculation.

## Practical Implementation Examples

### Setting SKILL_DIR After Reading SKILL.md

When the harness returns the absolute path of the read file:

```bash

# The harness returns: /home/user/.codex/skills/watch/SKILL.md

READ_RESULT="/home/user/.codex/skills/watch/SKILL.md"

# Derive the directory containing SKILL.md

SKILL_DIR=$(dirname "$READ_RESULT")   # → /home/user/.codex/skills/watch

# Verify the entry-point script exists

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 the main script using the resolved SKILL_DIR

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

```

### Claude Code Implementation

On Claude Code, the harness automatically substitutes the cache path:

```bash

# Harness provides: /home/claude/.cache/claude-video/watch/v0.2.0/skills/watch/SKILL.md

SKILL_DIR="/home/claude/.cache/claude-video/watch/v0.2.0/skills/watch"

python3 "${SKILL_DIR}/scripts/watch.py" "my_video.mp4"

```

### Debugging Path Resolution

For troubleshooting installation issues:

```bash
SKILL_DIR="$(dirname "$(read /path/to/SKILL.md)")"
python3 "${SKILL_DIR}/scripts/watch.py" "$URL"

```

## Summary

- **`SKILL_DIR`** is derived from the absolute path of the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file returned by the harness read operation, not from environment variables
- The **parent directory** of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) becomes `SKILL_DIR`, with all scripts located under `${SKILL_DIR}/scripts/`
- This resolution method works identically across **Claude Code**, **Codex**, **Cursor**, and **Gemini CLI** without host-specific modifications
- A **guard block** validates script existence before execution, preventing failures from incorrect path resolution
- All bundled 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)**, **[`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py)**, **[`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)**) are referenced through the resolved `SKILL_DIR` variable

## Frequently Asked Questions

### Why not use environment variables like $CLAUDE_SKILL_DIR?

The skill avoids host-specific environment variables to maintain portability. By deriving `SKILL_DIR` from the absolute path of the read [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file, the same skill bundle works across Claude Code, Codex, Cursor, and generic agent hosts without requiring platform-specific configuration or conditional logic.

### What happens if the script file is missing after path resolution?

The skill aborts with a clear error message. As implemented in **[`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md)** lines 30-36, the validation checks if `${SKILL_DIR}/scripts/watch.py` exists before attempting execution. If the file is missing, the error explicitly states the expected path, making debugging installation issues straightforward.

### Does this resolution method work with nested skill directories?

Yes, because `SKILL_DIR` always resolves to the immediate parent directory of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md). Whether the file is located at `~/.codex/skills/watch/SKILL.md` or `~/.claude/plugins/cache/claude-video/watch/v1.0.0/skills/watch/SKILL.md`, the `dirname` operation correctly identifies the containing folder, and scripts remain accessible at the relative path `scripts/`.

### How does the harness know which SKILL.md to read?

The skill contract defined in the front-matter instructs the harness to read the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file bundled with the skill. The harness implementation varies by host (Claude Code reads from its plugin cache, Codex from its skills directory), but all return the absolute path of the file, enabling consistent `SKILL_DIR` resolution across platforms.