claude-code - 💡(How to fix) Fix [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:

1. 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:

Total scope: 3 pages affected