[DOCS] CLI reference missing --worktree skill and hook loading behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/cli-reference

Section/Topic

--worktree / -w flag documentation

Current Documentation

The CLI reference documents --worktree as:

--worktree, -w | Start Claude in an isolated git worktree at <repo>/.claude/worktrees/<name>. ...

The hooks page documents WorktreeCreate and WorktreeRemove hook events but says nothing about skill/hook discovery from the worktree path. The skills page mentions worktrees only in the context of the /batch skill using isolated worktrees.

What's Wrong or Missing?

Changelog v2.1.78 fixed --worktree not loading skills and hooks from the worktree directory. This reveals that when using --worktree, Claude Code is expected to discover and load skills and hooks from the worktree directory — not just from the original repository root.

This scoping behavior is not documented. Users creating worktree-specific skills or hooks have no guidance on:

• Whether skills/hooks in the worktree directory are automatically loaded
• How worktree skill/hook resolution interacts with the parent repo's skills/hooks
• Whether .claude/ configuration in the worktree is respected

Suggested Improvement

Add a note to the --worktree flag description in the CLI reference:

When using --worktree, Claude Code loads skills and hooks from the worktree directory in addition to global configuration. This allows worktree-specific customization.

Also add a cross-reference note in the skills and hooks pages mentioning worktree-scoped discovery.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/cli-reference | --worktree flag description |
| https://code.claude.com/docs/en/skills | Skill discovery and loading |
| https://code.claude.com/docs/en/hooks | Hook discovery and loading |

Total scope: 3 pages affected

Source: Changelog v2.1.78

Fixed --worktree flag not loading skills and hooks from the worktree directory