How to correctly structure a Claude Code plugin so it actually loads
Developers building plugins for Claude Code often encounter a silent loading failure caused by a single structural mistake in their directory layout. The core issue is placing skill or agent directories inside the .claude-plugin/ folder, which should contain only the plugin.json manifest file. All functional components — such as skills/, agents/, hooks/, and .mcp.json — must sit at the plugin root level, not nested under the manifest directory. For simple single-skill plugins, even the manifest is optional; a lone SKILL.md file at the plugin root is enough for Claude Code to auto-discover and load the plugin. Developers can either load plugins on demand using the --plugin-dir flag or set them up persistently via the claude plugin init command, which scaffolds the correct structure automatically.
This is an AI-generated summary. ShortSingh links to the original source for the complete article.
Discussion (0)
Log in to join the discussion and vote.
Log in