claude-code - 💡(How to fix) Fix [Bug] Skill discovery and @path resolution fail in git worktrees with new files

[Bug] Skill discovery and @path references don't resolve files introduced in a git worktree

Summary

When developing a new skill or referencing a new doc inside a git worktree (files that exist on a feature branch but not yet on main), Claude Code's skill catalog and @path/to/file reference expansion both silently fail to resolve those files — even when the session is launched with the worktree as CWD.

Expected behavior

When Claude Code is launched with CWD inside a git worktree, skill discovery and @path resolution should use the worktree's working tree. New skill files at <worktree>/.claude/commands/<name>.md should appear in the skill catalog, and @<worktree-relative-path> references should expand to the file's current on-disk contents.

Actual behavior

1. New skill files in the worktree are invisible to the skill catalog. A skill committed on a feature branch but not yet merged to main isn't registered. Typing /<new-skill-name> either errors, silently falls through, or — most dangerously — resolves to a different registered skill whose name happens to be close enough for the fuzzy matcher.
2. @path/to/new-file.md references fail to expand when the path points to a file introduced on the feature branch and not present on main.

Why this is painful

It creates a chicken-and-egg problem for skill authoring. The natural iteration loop is:

1. Create worktree + branch
2. Draft new skill file
3. Invoke the skill to observe behavior
4. Iterate
5. Merge when satisfied

Step 3 is impossible without shipping first. Authors can't dogfood new skills before merge, forcing blind PRs or awkward manual invocation ("read the skill file yourself and follow its steps"). The same applies to drafting documentation that the skill references — you can't preview the @path expansion until the file is on main.

Safety-relevant sub-issue

When a slash command doesn't resolve to a registered skill, the CLI appears to substitute a different skill rather than erroring. This silent substitution is dangerous for destructive skills. Concrete example: a user types /my-new-readonly-skill, which isn't registered because it's worktree-only, and the session instead launches a registered skill that performs branch-merging, cleanup, or other non-reversible actions.

The user has no indication the command they invoked isn't the command that ran. A clean Unknown skill: /<name> error would be the safer default.

Environment Info

• Platform: darwin
• Terminal: iTerm.app
• Version: 2.1.114
• Feedback ID: 7dc3ff91-4937-4548-8db3-d686a8c3b02f

Note: Content was truncated.