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

The SKILL.md path is resolved by deriving SKILL_DIR from the absolute path of the file returned when the skill harness reads 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 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 file. This variable serves as the anchor for all subsequent script calls.

According to the contract defined in skills/watch/SKILL.md (lines 18-28), the resolution follows this sequence:

1. The skill harness Reads the 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)
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 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 - Main entry point for video processing
• skills/watch/scripts/setup.py - Pre-flight verification of binaries and environment
• skills/watch/scripts/download.py - yt-dlp wrapper for video acquisition
• 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 (lines 30-36), if the derived 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:

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

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

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 file returned by the harness read operation, not from environment variables
• The parent directory of 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, setup.py, download.py, 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 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 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. 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 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.

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