[DOCS] Plugin skill docs conflict on invocation naming for custom `skills` paths

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Plugin skill naming in the "Add a skill" section, plus the plugin.json skills manifest field documentation for custom paths

Current Documentation

The plugins guide currently says:

"Skills live in the skills/ directory. Each skill is a folder containing a SKILL.md file. The folder name becomes the skill name, prefixed with the plugin's namespace (hello/ in a plugin named my-first-plugin creates /my-first-plugin:hello)."

The same page later says:

"Each SKILL.md needs frontmatter with name and description fields, followed by instructions:"

The general skills docs say:

"The name field becomes the /slash-command, and the description helps Claude decide when to load it automatically."

"name ... Display name for the skill. If omitted, uses the directory name."

The plugins reference also says:

"skills ... Custom skill directories (replaces default skills/)"

"Components from custom paths use the same naming and namespacing rules"

What's Wrong or Missing?

Changelog v2.1.94 states:

Plugin skills declared via "skills": ["./"] now use the skill's frontmatter name for the invocation name instead of the directory basename, giving a stable name across install methods

The current documentation does not clearly state that rule for plugin-shipped skills.

A. Plugin docs describe the invocation name inconsistently

The plugin tutorial says the folder name becomes the skill name, but the general skills docs say the frontmatter name becomes the slash command and the directory name is only the fallback. Users converting an existing skill into a plugin, or moving a plugin skill to a custom manifest path, cannot tell whether /plugin-name:... comes from the directory basename or from SKILL.md frontmatter.

B. Custom plugin.json skills paths do not explain naming behavior

plugins-reference documents that skills can point at custom directories, but it does not explain how invocation names are resolved for custom paths such as "skills": ["./"] or that the frontmatter name keeps the invocation stable across install methods.

Suggested Improvement

Add a short "Invocation name" note to both plugins and plugins-reference:

• Plugin skill invocation names use the skill's frontmatter name
• If name is omitted, Claude falls back to the skill directory name
• The final command remains namespaced as /plugin-name:skill-name
• This rule applies to the default skills/ directory and to manifest-defined custom skills paths, including "skills": ["./"]

An explicit example would make the rule much easier to understand:

{
"name": "my-plugin",
"skills": ["./"]
}

---
name: code-review
description: Reviews code
---

If that SKILL.md lives in a folder like review/, the docs should state that the invocation is /my-plugin:code-review, not /my-plugin:review.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/plugins | Plugin tutorial says the folder name becomes the skill name |
| https://code.claude.com/docs/en/plugins-reference | Documents custom skills paths, but not how invocation names are derived |
| https://code.claude.com/docs/en/skills | Canonical skill naming rule already says frontmatter name becomes the slash command |

Total scope: 3 pages affected

Source: Changelog v2.1.94

Exact changelog entry: Plugin skills declared via "skills": ["./"] now use the skill's frontmatter name for the invocation name instead of the directory basename, giving a stable name across install methods