[DOCS] Plugins in `.claude/skills` auto-load not documented — marketplace not required

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"When to use plugins vs standalone configuration" section and "Test your plugins locally" section

Current Documentation

The docs describe three ways to load plugins: --plugin-dir for local development, --plugin-url for session-only loading from a URL, and marketplace installation via /plugin install. No other loading method is mentioned.

From the plugins page, the "When to use plugins vs standalone configuration" section (https://code.claude.com/docs/en/plugins):

| Standalone (.claude/ directory) | /hello | Personal workflows, project-specific customizations, quick experiments | | Plugins (directories with .claude-plugin/plugin.json) | /plugin-name:hello | Sharing with teammates, distributing to community, versioned releases, reusable across projects |

The "Share your plugins" section says:

3. Create or use a marketplace: Distribute through plugin marketplaces for installation

The skills page (https://code.claude.com/docs/en/skills) lists .claude/skills/ as a location for skills only — it does not mention that plugin directories can also be placed there for automatic loading:

| Location | Path | Applies to | | :--------- | :-------------------------------------------------- | :----------------------------- | | Personal | ~/.claude/skills/<skill-name>/SKILL.md | All your projects | | Project | .claude/skills/<skill-name>/SKILL.md | This project only | | Plugin | <plugin>/skills/<skill-name>/SKILL.md | Where plugin is enabled |

What's Wrong or Missing?

Starting in v2.1.157, Claude Code automatically discovers and loads plugins placed in .claude/skills/ directories — no marketplace, --plugin-dir, or --plugin-url required. A plugin directory (with .claude-plugin/plugin.json, skills/, hooks/, etc.) inside .claude/skills/ is picked up automatically, the same way skills are. This is a significant simplification for teams and individuals who want to use plugins without setting up a marketplace.

The documentation does not reference this feature anywhere:

A. Missing loading method on plugins page

The plugins page only documents --plugin-dir, --plugin-url, and marketplace installation. It should also document that plugins in .claude/skills/ are auto-loaded.

B. Missing mention on skills page

The skills page does not mention that .claude/skills/ directories can contain plugin directories with .claude-plugin/plugin.json in addition to skill directories with SKILL.md.

C. Discover page assumes marketplace is required

The discover-and-install page only covers marketplace-based installation and --plugin-dir for development, reinforcing the incorrect assumption that a marketplace is always required to share and load plugins.

Suggested Improvement

Option A: Full coverage (recommended)

Plugins page — Add a section or callout documenting that plugins placed in .claude/skills/ are automatically loaded:

Auto-load plugins from .claude/skills/ Claude Code automatically discovers and loads plugins stored in .claude/skills/ directories. This works the same as skill auto-discovery: place a plugin directory (containing .claude-plugin/plugin.json) inside .claude/skills/ and it loads without --plugin-dir or a marketplace. `` .claude/skills/ ├── my-skill/ │ └── SKILL.md # Regular skill (auto-loaded) └── my-plugin/ # Plugin with manifest (auto-loaded) ├── .claude-plugin/ │ └── plugin.json └── skills/ └── review/ └── SKILL.md ``

Also update the comparison table to add a row or note:

| Plugins in .claude/skills/ | /plugin-name:hello | Sharing via version control (committed to repo), quick plugin iteration without marketplace setup |

Skills page — Update the "Where skills live" table and note to mention plugin directories:

| Plugin in .claude/skills/ | .claude/skills/<plugin-name>/.claude-plugin/plugin.json | This project only, no marketplace required |

Discover and install page — Add a note that plugins can also be loaded from .claude/skills/ without marketplace installation.

Option B: Minimum fix

Add a brief mention in the plugins page test section and the skills page location table that .claude/skills/ can contain plugin directories for auto-loading.

Impact

Medium - Makes feature difficult to understand

Additional Context

Changelog entry (v2.1.157):

Plugins in .claude/skills directories are now automatically loaded, no marketplace required

Affected Pages:

| Page | Section | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/plugins | "When to use plugins vs standalone configuration" | Only lists standalone .claude/ and plugins with .claude-plugin/plugin.json without mentioning .claude/skills/ auto-load |
| https://code.claude.com/docs/en/plugins | "Share your plugins" | Says "Create or use a marketplace" — no mention of .claude/skills/ as an alternative |
| https://code.claude.com/docs/en/skills | "Where skills live" | Only lists SKILL.md files, not plugin directories |
| https://code.claude.com/docs/en/discover-plugins | Throughout | Only covers marketplace installation |

Total scope: 3 pages affected