[DOCS] Skills docs omit the `<dir>:<name>` namespace for nested `.claude/skills` skill name clashes

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/skills

Section/Topic

"Automatic discovery from parent and nested directories" and the "How a skill gets its command name" table under "Configure skills"

Current Documentation

The Skills doc explains the new on-demand discovery of nested .claude/skills/ directories, and the "How a skill gets its command name" table lists four layouts, but it does not document the namespace format for nested skills that share a name with another skill:

When you work with files in subdirectories below your starting directory, Claude Code also discovers skills from nested .claude/skills/ directories on demand. 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.

| Skill location | Command name source | Example | | :------------------------------------------------------------- | :--------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | | Skill directory under ~/.claude/skills/ or .claude/skills/ | Directory name | .claude/skills/deploy-staging/SKILL.md → /deploy-staging | | File under .claude/commands/ | File name without extension | .claude/commands/deploy.md → /deploy | | Plugin skills/ subdirectory | Directory name, namespaced by plugin | my-plugin/skills/review/SKILL.md → /my-plugin:review | | Plugin root SKILL.md | Frontmatter name, with the plugin directory name as a fallback | my-plugin/SKILL.md with name: review → /my-plugin:review. See Path behavior rules |

What's Wrong or Missing?

The v2.1.178 changelog adds: "Skills in nested .claude/skills directories now load when working on files there; on a name clash, the nested skill appears as <dir>:<name> so both stay available." Neither the discovery paragraph nor the command-name table mentions this behavior, so a reader who hits a name clash has no way to know which skill they are invoking or how to invoke the nested copy directly.

A. Missing row in the command-name table

The "How a skill gets its command name" table covers personal, project, commands, and plugin layouts, but it omits the nested .claude/skills/<dir>/<name>/SKILL.md case and the <dir>:<name> namespace that is used when a nested skill's name collides with another skill in scope.

B. The discovery paragraph underspecifies the result

The paragraph only says skills from nested directories are "discovered" on demand. It does not explain that a name clash produces a directory-qualified invocation name, nor that this lets both copies coexist instead of one silently shadowing the other.

C. The "large-codebases" walkthrough also lacks the namespace rule

The "Add per-directory skills" walkthrough in large-codebases.md shows two example skills at packages/api/.claude/skills/api-testing/ and packages/web/.claude/skills/component-patterns/ and notes that "Neither directory's skills load during the other's tasks." It does not call out the <dir>:<name> format that would be used if those skills ever shared a name, or after the v2.1.178 changelog, after the directory-qualified name is being used in non-interactive permission prompts (the follow-up fix: "Fixed nested .claude/skills skills with directory-qualified names being blocked by permission prompts in non-interactive runs").

Suggested Improvement

Extend the "How a skill gets its command name" table with a fifth row covering nested skills, and add a short paragraph under "Automatic discovery from parent and nested directories" describing the namespace rule.

Add a row to the table:

| Nested `.claude/skills/<dir>/<name>/` (clash) | Directory name, qualified by the immediate parent dir | `packages/api/.claude/skills/deploy/SKILL.md` and a root `.claude/skills/deploy/SKILL.md` → both stay available; the nested copy is invoked as `/packages/api:deploy` |

Add to the discovery section, after the existing example:

When a nested skill's directory name matches a skill from a parent directory, in the starting directory, or in user or enterprise scope, the nested copy is exposed as `<dir>:<name>` (for example, `/packages/api:deploy`) so both stay available. The unqualified name continues to invoke the outer copy.

Optionally cross-link from large-codebases.md in the "Add per-directory skills" section with a one-liner: "If a per-directory skill ever shares a name with a skill from a parent scope, the nested copy is qualified as <dir>:<name> so both remain invocable; see Skills."

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/skills | Primary documentation location; command-name table and "Automatic discovery" section |
| https://code.claude.com/docs/en/large-codebases | "Add per-directory skills" walkthrough that demonstrates nested skill layout but does not document the namespace rule |
| https://code.claude.com/docs/en/changelog | v2.1.178 entry is the source of the new behavior; cross-reference for context |

Total scope: 2 documentation pages affected (plus changelog as the originating entry).

Related changelog context: v2.1.178 also includes a follow-up fix — "Fixed nested .claude/skills skills with directory-qualified names being blocked by permission prompts in non-interactive runs" — which only matters if users know the <dir>:<name> namespace exists in the first place. Documenting the rule also gives the follow-up fix a stable name in the docs.