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

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 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 file itself. As 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-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:

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

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【/cache/repos/github.com/bradautomates/claude-video/main/skills/watch/SKILL.md#L139-L141】 demonstrate calling the main watch script:

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, watch.py, and download.py—are referenced via ${SKILL_DIR}/scripts/<script>.py.
• A validation check ensures 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 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 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 and other bundled files.

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

The skill includes a validation guard in 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, which defines the SKILL_DIR resolution logic. Supporting documentation appears in AGENTS.md (explaining the strategy) and CHANGELOG.md (documenting the transition from environment variables). The actual scripts referenced by this pattern include skills/watch/scripts/watch.py and skills/watch/scripts/setup.py.

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