[DOCS] "Automatic Discovery from Nested Directories" for skills does not work as documented

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/skills#automatic-discovery-from-nested-directories

Section/Topic

Automatic Discovery from Nested Directories (under Skills)

Current Documentation

The docs state:

When you work with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills/ directories. For example, if you're editing a file in packages/frontend/, Claude Code also looks for skills in packages/frontend/.claude/skills/. This supports monorepo setups where packages have their own skills.

The implication here is that when you edit a file inside a subdirectory, Claude Code should walk up from that file and discover any .claude/skills/ directories along the path. So editing packages/frontend/src/App.tsx should pick up skills defined in packages/frontend/.claude/skills/.

What's Wrong or Missing?

This doesn't work. Skills in nested .claude/skills/ directories are not discovered or loaded. Tested in both the Claude CLI (terminal claude command) and the Claude Code VS Code extension.

Steps to reproduce

Set up a project with a nested skill:

my-project/
├── .claude/skills/           # root-level skills (these work fine)
├── packages/
│   └── frontend/
│       ├── src/
│       │   └── App.tsx       # file to edit
│       └── .claude/
│           └── skills/
│               └── my-skill/
│                   └── SKILL.md

1. Give the SKILL.md valid frontmatter with a name and description.
2. Open Claude Code at the project root.
3. Edit or work with a file inside packages/frontend/ (e.g. packages/frontend/src/App.tsx).
4. Try to autocomplete the nested skill with /my-skill - it doesn't show up.
5. Try prompting Claude with something that matches the skill's description - the skill is not triggered.

Expected behavior

Per the docs, editing a file inside packages/frontend/ should cause Claude Code to discover skills in packages/frontend/.claude/skills/. Those skills should then be available via autocomplete and/or automatic invocation based on their description.

Actual behavior

Only skills in the project root .claude/skills/ and personal ~/.claude/skills/ are ever discovered. Nested .claude/skills/ directories are ignored regardless of which files you're editing. The skills don't appear in autocomplete, can't be invoked with /skill-name, and Claude doesn't pick them up automatically.

This is either a bug in the discovery logic or the docs describe a feature that isn't implemented yet.

Suggested Improvement

1. If this is a bug: Fix nested directory skill discovery so it works as documented. When editing files in a subdirectory, Claude Code should find .claude/skills/ directories along the path from the edited file to the project root.
2. If this isn't implemented yet: Update the docs to indicate that, or remove the section until it ships.
3. If there's a prerequisite I'm missing (like needing --add-dir or some config): Document it. The current docs imply this should work automatically.

Impact

High - Prevents users from using a feature

Additional Context

• Tested with latest versions of both the Claude CLI and Claude Code VS Code extension (March 2026).
• Root-level skills (.claude/skills/) and personal skills (~/.claude/skills/) work fine.
• The docs also mention a separate "Skills from additional directories" feature using --add-dir. The nested auto-discovery described here should work without that flag.