Claude Code plugin structure: the minimal layout that actually loads
You wrote a skill, it works in ~/.claude/skills/ , and now you want to hand it to a teammate — so you wrap it in a plugin. You create the folder, add a manifest, restart Claude Code… and nothing loads. No error that helps, no skill in the list. Nine times out of ten the cause is one wrong assumption about the directory layout. This post is the minimal structure that actually loads, verified…
The minimal structure for a Claude Code plugin involves creating a directory with two key components: the plugin root and a .claude-plugin subdirectory. Inside the plugin root, the only mandatory item is a manifest file named .mcp.json. This file holds metadata such as the plugin's name, description, and version.
The .claude-plugin directory should contain exactly one file: plugin.json. This manifest file is essential as it provides additional information for the plugin manager, such as a stable name, description, and version field. It's important to note that all other directories like skills/, agents/, hooks/, and commands/ must be placed at the plugin root level and not inside the .claude-plugin directory.
If your plugin contains only a single skill, you can simplify the structure by placing a SKILL.md file directly at the plugin root. This file serves as the sole skill and can be invoked using the frontmatter name field. When your plugin grows beyond a single skill, you can organize skills into separate directories within the skills/ folder.
Claude Code plugins are not restricted to a single layout; they can grow as needed. When developing a plugin, you can test it using the claude --plugin-dir flag or create a persistent local plugin by running claude plugin init <plugin-name>. This command scaffolds a new plugin directory with a manifest and starter files. Remember, if you distribute your plugin via git, you must explicitly set the version field in plugin.json to avoid frequent updates due to minor changes.
In summary, the key points to remember are:
1. Place all directories (skills/, agents/, hooks/, commands/) at the plugin root level.
2. Only plugin.json should reside inside the .claude-plugin directory.
3. For a single-skill plugin, you can use a SKILL.md file at the root.
4. Set the version field in plugin.json when distributing via git to maintain consistent releases.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
