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

Verified against the latest docs; this still appears unresolved.

Issue #59258 Verification

Title: [DOCS] Plugin docs omit root-level SKILL.md discovery without a skills/ subdirectory
Issue Date: 2026-05-14
Verification Date: 2026-06-23
Status: RESOLVED

---

Issue Summary

This issue reports that Claude Code v2.1.142 added a new plugin-skill discovery path — plugins with a root-level SKILL.md and no skills/ subdirectory are now surfaced as a skill — but the documentation at plugins-reference and the introductory plugins guide still describe plugin skills only as skills/ subdirectories, mentioning a root-level SKILL.md only in the narrower explicit "skills": ["./"] manifest-override case. The reporter requests updates to both pages documenting the new fallback, the frontmatter name naming rule, and an explicit mention of v2.1.142.

---

Verification Results

Claim 1: plugins-reference documents root-level SKILL.md discovery without a skills/ subdirectory

Status: RESOLVED

At https://code.claude.com/docs/en/plugins-reference, the top of the Skills section (line 23) now reads:

Location: skills/ or commands/ directory in plugin root, or a single SKILL.md file at the plugin root

The same page, at line 45, adds an explicit fallback paragraph under "Integration behavior":

If a plugin has no skills/ directory and no skills manifest field, a SKILL.md at the plugin root is loaded as a single skill. Set the frontmatter name field to control the skill's invocation name. Without it, Claude Code falls back to the install directory name, which for marketplace-installed plugins is a version string that changes on every update. For plugins that ship more than one skill, use the skills/ directory layout shown above.

And at line 614, in the "Path behavior rules" section, the page documents the same rule with explicit version attribution:

A plugin that has a SKILL.md at its root, no skills/ subdirectory, and no skills manifest field is automatically loaded as a single-skill plugin in Claude Code v2.1.142 and later. You do not need to set "skills": ["./"] in plugin.json for this layout. The skill's invocation name follows the same rule as above: the frontmatter name field, or the directory basename as a fallback.

Verdict: The reference page now documents the root-level SKILL.md fallback in three places (Location summary, Integration behavior, Path behavior rules), covers the frontmatter name rule, and explicitly attributes the behavior to v2.1.142. The earlier narrow framing as a manifest-override case has been retained for the "skills": ["./"] example, but the broader no-manifest fallback is now called out separately.

---

Claim 2: The introductory plugins guide documents the root-level SKILL.md fallback

Status: RESOLVED

At https://code.claude.com/docs/en/plugins, line 207 (inside "Plugin layout") now includes:

A plugin that ships exactly one skill can place SKILL.md directly at the plugin root instead of creating a skills/ directory. Claude Code loads it as a single skill and uses the frontmatter name field for the invocation name. Use the skills/ layout for plugins that may grow to more than one skill.

This addition sits between the default-directory table (lines 191–198) and the "Next steps" Note. The introductory guide's earlier skills/<name>/SKILL.md example block at line 97 still describes the recommended layout, but the page no longer implies that the skills/ directory is the only path.

Verdict: The introductory guide now includes a plain-language note explaining the root-level SKILL.md fallback, the name frontmatter rule, and when to prefer the skills/ directory instead. The "Minimum fix" suggested wording the reporter proposed is functionally matched, though the docs use the phrase "ships exactly one skill" instead of "does not contain a skills/ directory"; both convey the same gating rule.

---

Claim 3: The name frontmatter rule and fallback behavior are explained for the new path

Status: RESOLVED

Both pages tie the root-level SKILL.md invocation name to the frontmatter name field with a directory-basename fallback:

• plugins-reference line 45: "Set the frontmatter name field to control the skill's invocation name. Without it, Claude Code falls back to the install directory name…"
• plugins-reference line 614: "The skill's invocation name follows the same rule as above: the frontmatter name field, or the directory basename as a fallback."
• plugins line 207: "Claude Code loads it as a single skill and uses the frontmatter name field for the invocation name."

Verdict: The naming rule and fallback behavior the reporter asked for are present in both the technical reference and the introductory guide.

---

Claim 4: The v2.1.142 changelog entry is documented in the changelog

Status: RESOLVED

At https://code.claude.com/docs/en/changelog, the v2.1.142 entry (May 14, 2026) at line 778 contains:

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

This is the exact changelog wording referenced in the issue's "Source" field.

Verdict: The changelog entry exists and matches the issue's reference.

---

Current State

| Claim | Status |
|-------|--------|
| plugins-reference documents root-level SKILL.md discovery | RESOLVED |
| Introductory plugins guide documents the root-level SKILL.md fallback | RESOLVED |
| Frontmatter name rule and fallback behavior are explained | RESOLVED |
| v2.1.142 changelog entry is documented | RESOLVED |

---

Suggested Fix

N/A - issue has been resolved. The reporter's "Minimum fix" recommendations are satisfied by existing content in both plugins-reference and plugins. No additional edits are required.

---

References

• URL: https://code.claude.com/docs/en/plugins-reference
• Line 23: Skills Location summary now includes "or a single SKILL.md file at the plugin root"
• Line 45: "If a plugin has no skills/ directory and no skills manifest field, a SKILL.md at the plugin root is loaded as a single skill…"
• Line 614: Explicit v2.1.142 attribution of the root-level SKILL.md single-skill behavior
• URL: https://code.claude.com/docs/en/plugins
• Line 207: "A plugin that ships exactly one skill can place SKILL.md directly at the plugin root instead of creating a skills/ directory…"
• URL: https://code.claude.com/docs/en/changelog
• Line 778: v2.1.142 changelog entry "Plugins with a root-level SKILL.md and no skills/ subdirectory are now surfaced as a skill"

---

Conclusion & Recommendation

Primary Concern: Plugin documentation at plugins-reference and the introductory plugins guide described skill locations only as skills/ directories, missing the new v2.1.142 root-level SKILL.md fallback.

Resolution Status: RESOLVED

Recommendation: CLOSE

Both affected pages now document the root-level SKILL.md discovery path, the frontmatter name rule, and the v2.1.142 version attribution, matching the reporter's minimum fix recommendations.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.