Skills not shown in autocomplete when .claude is a symlink

Resolved 💬 4 comments Opened Mar 20, 2026 by qwertyfinger Closed Mar 24, 2026

Description

When the .claude directory is a symlink (e.g., pointing to a git submodule), project-level skills defined in .claude/skills/ are not listed in autocomplete when typing / in the CLI. The skills do load into context and work when invoked via the Skill tool — only autocomplete discovery is broken.

Reproduction

  1. Create a git submodule (e.g., ai-spellbook) containing a .claude/skills/ directory with properly structured SKILL.md files (correct frontmatter with name, description, user-invocable: true)
  2. Symlink the project's .claude directory to the submodule: ln -s ai-spellbook/.claude .claude
  3. Start Claude Code in the project directory
  4. Type / — project skills do not appear in autocomplete
  5. Plugin-installed skills appear normally

Also tested

Replacing the directory-level symlink with a real .claude/ directory containing symlinked contents inside (e.g., skills -> ../ai-spellbook/.claude/skills) — autocomplete still does not discover the skills.

Expected behavior

Skills should appear in autocomplete regardless of whether .claude or its subdirectories are symlinks. This is a common setup for teams sharing Claude configuration across multiple repositories via git submodules.

Environment

  • macOS (Darwin 25.2.0)
  • Claude Code CLI (latest)
  • Skills have correct frontmatter and work when invoked directly

Related issues

  • #25903 — Symlinked rules files in ~/.claude/rules/ not loaded into context (same class of bug)
  • #27292 — Glob tool does not follow symlinks (possible root cause if skill discovery uses Glob)
  • #31056 — Custom subagents not discovered when .claude is a symlink (similar but for agents)

These issues suggest a broader pattern where symlinks are not consistently followed during content discovery.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗