[DOCS] Plugin docs omit root-level `SKILL.md` discovery without a `skills/` subdirectory

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Skills, Component path fields, and plugin skill file-location rules

Current Documentation

The docs currently describe plugin skills only as skills/ subdirectories by default:

Plugins add skills to Claude Code, creating /name shortcuts that you or Claude can invoke. Location: skills/ or commands/ directory in plugin root File format: Skills are directories with SKILL.md; commands are simple markdown files

The introductory plugin guide says the same thing:

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 only documented root-level SKILL.md case is an explicit manifest override:

When a skill path points to a directory that contains a SKILL.md directly, for example "skills": ["./"] pointing to the plugin root, the frontmatter name field in SKILL.md determines the skill's invocation name. This gives a stable name regardless of the install directory. If name is not set in the frontmatter, the directory basename is used as a fallback.

What's Wrong or Missing?

Claude Code v2.1.142 added another plugin-skill discovery path: plugins with a root-level SKILL.md and no skills/ subdirectory are now surfaced as a skill.

That behavior is not documented in the default plugin layout or skill-location guidance.

As written now, the docs imply that plugin authors must either:

1. create skills/<name>/SKILL.md, or
2. add an explicit manifest "skills": ["./"] override.

They do not explain that a plugin can now expose a skill from a root-level SKILL.md even without a skills/ subdirectory.

This leaves a new user-facing plugin packaging behavior undocumented, and it is especially confusing because the existing docs already mention a root-level SKILL.md only in the narrower manifest-override case.

Suggested Improvement

Update plugins-reference and the introductory plugins guide to document the new fallback clearly.

Minimum fix:

• In plugins-reference, add a note near the Skills section and file-location rules that if a plugin has no skills/ subdirectory, a root-level SKILL.md is surfaced as a plugin skill.
• Clarify the naming rule for that fallback, including that the name frontmatter field determines the invocation name when present.
• In plugins, add a short note that skills/<name>/SKILL.md remains the recommended structure, but a lone root-level SKILL.md is also recognized in v2.1.142+ when no skills/ directory exists.

Suggested wording:

If a plugin does not contain a skills/ directory, Claude Code also treats a root-level SKILL.md as a plugin skill. Use name frontmatter to control the invoked skill name; otherwise Claude falls back to the directory basename.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/plugins-reference | Technical reference currently documents skills/ directories by default and root-level SKILL.md only for explicit "skills": ["./"] manifest paths |
| https://code.claude.com/docs/en/plugins | Introductory plugin authoring guide says skills live in skills/ and gives only skills/<name>/SKILL.md examples |

Total scope: 2 pages affected

Source: Changelog v2.1.142

Exact changelog entry:

Plugins with a root-level SKILL.md and no skills/ subdirectory are now surfaced as a skill