# How SKILL_DIR Resolution Works in claude-video Across Claude Code, Cursor, and Other Hosts

> Discover how SKILL_DIR resolution in claude-video ensures skill commands work seamlessly across Claude Code, Cursor, and other hosts without complex configuration. Learn more here.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: internals
- Published: 2026-07-14

---

**In claude-video, SKILL_DIR is derived from the absolute path of the SKILL.md file being read, enabling the same skill commands to work across Claude Code, Cursor, Codex, and generic agents without host-specific configuration.**

The `claude-video` repository distributes its functionality as a self-contained skill located in `skills/watch/`. To maintain portability across different AI coding assistants, the skill relies on a standardized resolution mechanism that determines the installation location at runtime. This approach eliminates the need for hardcoded paths or host-specific environment variables like `CLAUDE_SKILL_DIR`.

## The SKILL_DIR Resolution Mechanism

When a user invokes the `watch` skill (e.g., `/watch <url-or-path>`), the host-specific harness first reads the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file to understand the skill's capabilities. The environment variable **SKILL_DIR** is then set to the absolute directory path containing that [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file.

```text
SKILL_DIR = <absolute path of the directory containing the SKILL.md you just Read>

```

This resolution logic is 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-L27】.

## Host-Specific Path Mappings

Different AI assistants install skills in distinct locations, but the resolution algorithm remains identical across all platforms.

### Claude Code Resolution Path

On Claude Code, the harness reads the skill definition from a versioned cache directory:

- **Example path**: `~/.claude/plugins/cache/claude-video/watch/<ver>/skills/watch/SKILL.md`
- **Resolved SKILL_DIR**: `…/skills/watch`

### Cursor and Codex Resolution Path

Cursor and the Codex CLI use a flattened directory structure:

- **Example path**: `~/.codex/skills/watch/SKILL.md`
- **Resolved SKILL_DIR**: `~/.codex/skills/watch`

### Generic Agents Resolution Path

For other agent platforms like Gemini-CLI, the skill follows a standardized location:

- **Example path**: `~/.agents/skills/watch/SKILL.md`
- **Resolved SKILL_DIR**: `~/.agents/skills/watch`

## Implementation in the watch Skill

Once `SKILL_DIR` is resolved, all helper scripts are referenced relative to this base directory. The entry point [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py) is always invoked using the same command pattern regardless of the host:

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

```

This host-agnostic approach ensures that the skill's entry point script ([`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)) is located consistently across installations. The same Bash execution block works unchanged whether the underlying path comes from Claude Code's cache or Cursor's skills directory.

### Practical Resolution Example

The following snippet demonstrates how a skill harness should resolve `SKILL_DIR` and execute the watch script:

```bash

# Resolve SKILL_DIR from the location of SKILL.md

SKILL_DIR="$(dirname "$(read ~/.claude/plugins/cache/claude-video/watch/0.2.0/skills/watch/SKILL.md)")"

# Verify the entry point 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

# Run the watch script (same command works on every host)

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

```

## Error Handling and Validation

The skill implements defensive checks to ensure installation integrity. If the resolved `SKILL_DIR` does not contain [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py), the operation aborts immediately with a clear error message【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/SKILL.md#L30-L36】.

This validation occurs in both the main execution flow and the setup routine defined in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py). By checking for the existence of the Python helper before attempting execution, the skill prevents cryptic failures from mismatched or incomplete installations.

## Key Files Supporting SKILL_DIR Resolution

- **[`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md)**: Defines the canonical skill contract and SKILL_DIR resolution rules【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/SKILL.md】
- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)**: Entry-point script referenced via `${SKILL_DIR}/scripts/watch.py`
- **[`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py)**: Pre-flight installer that validates `SKILL_DIR` before proceeding
- **[`AGENTS.md`](https://github.com/bradautomates/claude-video/blob/main/AGENTS.md)**: High-level documentation describing skill placement within the repository

## Summary

- **SKILL_DIR** is calculated as the parent directory of the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file being read by the host harness.
- The resolution mechanism works identically across Claude Code (`~/.claude/plugins/...`), Cursor/Codex (`~/.codex/skills/...`), and generic agents (`~/.agents/skills/...`).
- All script invocations use the portable pattern `python3 "${SKILL_DIR}/scripts/watch.py"` regardless of the underlying host.
- Built-in validation in [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) ensures that [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py) exists before execution, preventing runtime errors from corrupted installations.

## Frequently Asked Questions

### What happens if SKILL_DIR is set incorrectly?

If `SKILL_DIR` resolves to a directory that does not contain [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py), the skill aborts with a clear error message stating that the script is not found under the current `SKILL_DIR` path. This check occurs before any attempt to execute Python code, protecting against mismatched installations or missing dependencies.

### Can I use claude-video with custom skill directories?

Yes, because `SKILL_DIR` is derived from the location of [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) rather than hardcoded host paths, you can install the skill in any directory structure. As long as the host reads the [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file from your custom location, the `dirname` resolution will correctly identify the skill root and locate the `scripts/` subdirectory accordingly.

### How does the skill verify the installation is correct?

The skill validates the installation by checking for the existence of `$SKILL_DIR/scripts/watch.py` before execution. This verification is implemented in the command template defined in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) and reinforced by the setup routine in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py). If the file is missing, the user receives an immediate error indicating that the skill directory may be corrupted or incomplete.

### Is this resolution method compatible with future AI coding assistants?

Yes, the resolution method is designed to be forward-compatible with any Agent-Skills platform. Because it relies only on the universal convention of `SKILL_DIR` being the directory containing [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md)—rather than host-specific environment variables or registry keys—it requires no modifications to support new hosts like future Gemini-CLI versions or other AI assistants that follow the skill specification.