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

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 file to understand the skill's capabilities. The environment variable SKILL_DIR is then set to the absolute directory path containing that SKILL.md file.

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【/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 is always invoked using the same command pattern regardless of the host:

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

This host-agnostic approach ensures that the skill's entry point script (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:

# 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, 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. 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: 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: Entry-point script referenced via ${SKILL_DIR}/scripts/watch.py
• skills/watch/scripts/setup.py: Pre-flight installer that validates SKILL_DIR before proceeding
• AGENTS.md: High-level documentation describing skill placement within the repository

Summary

• SKILL_DIR is calculated as the parent directory of the 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 and setup.py ensures that 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, 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 rather than hardcoded host paths, you can install the skill in any directory structure. As long as the host reads the 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 and reinforced by the setup routine in 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—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.

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