[BUG] Skill-scoped hooks cannot access skill resources - missing CLAUDE_SKILL_ROOT

[BUG] Skill-scoped hooks cannot access skill resources - missing CLAUDE_SKILL_ROOT

Description

Skill-scoped hooks defined in ~/.claude/skills/<skill-name>/SKILL.md cannot reliably reference their own skill's scripts or resources because:

1. Hooks execute with cwd=$CLAUDE_PROJECT_DIR (not $CLAUDE_SKILL_ROOT)
2. CLAUDE_SKILL_ROOT environment variable is not available in hook execution context
3. Documentation example implies different behavior

This makes it impossible for skills to run initialization scripts or setup commands that live within the skill directory.

Documentation vs. Reality

Documentation example (https://code.claude.com/docs/en/hooks):

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

This implies hooks execute with cwd=$CLAUDE_SKILL_ROOT or can use relative paths to skill resources.

Actual behavior:

• Hooks execute with cwd=$CLAUDE_PROJECT_DIR
• Only CLAUDE_PROJECT_DIR, CLAUDE_CODE_ENTRYPOINT, and CLAUDE_HOOK_AUTO_FIX are available
• CLAUDE_SKILL_ROOT is not set in hook environment

Reproduction

1. Create a test skill at ~/.claude/skills/alt/SKILL.md:

---
name: alt
description: Test skill
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "pwd"
          once: true
    - matcher: "Bash"
      hooks:
        - type: command
          command: "env | grep CLAUDE"
          once: true
---

1. Invoke the skill from a project directory: /Users/ken/dev/DLC/skill-hook-test

1. Observe hook output:

⎿  PreToolUse:Bash hook succeeded: /Users/ken/dev/DLC/skill-hook-test
⎿  PreToolUse:Bash hook succeeded: CLAUDE_HOOK_AUTO_FIX=true
   CLAUDE_CODE_ENTRYPOINT=cli
   CLAUDE_PROJECT_DIR=/Users/ken/dev/DLC/skill-hook-test

Result:

• pwd returns project directory, not skill directory
• CLAUDE_SKILL_ROOT is not available

Impact

Skills cannot:

• Run setup scripts from their own scripts/ directory
• Reference skill-local resources in hooks
• Create portable skills that work across different installations

Expected Behavior

One of the following should work:

Option 1: Execute hooks with cwd=$CLAUDE_SKILL_ROOT

• Makes documentation example work as-is
• Relative paths like ./scripts/setup.sh work naturally

Option 2: Provide CLAUDE_SKILL_ROOT environment variable

• Hooks can construct absolute paths: $CLAUDE_SKILL_ROOT/scripts/setup.sh
• More flexible, allows hooks to reference both project and skill resources

Option 3: Both

• Maximum flexibility
• Most consistent with how CLAUDE_PROJECT_DIR works

Workarounds

Currently, the only workaround is hardcoding absolute paths:

command: "/Users/username/.claude/skills/alt/scripts/setup.sh"

This breaks portability and defeats the purpose of skill-scoped hooks.

Environment

• Claude Code version: [latest as of 2026-01-11]
• Platform: macOS (Darwin 25.1.0)
• Skill location: ~/.claude/skills/alt/SKILL.md

Related

This is particularly important for skills that need to:

• Set up virtual environments
• Run initialization scripts
• Validate dependencies
• Configure resources before skill execution