Home / Extending: skills, MCP, subagents, hooks, plugins
Plugins: bundling skills, hooks, MCP and agents
A plugin bundles skills, hooks, MCP servers and commands into a single versioned directory, installable and shareable in one go, with a single manifest that lives apart from everything else.
A plugin bundles skills, hooks, MCP servers and commands into a single versioned directory, installable and shareable in one go. The official documentation describes this directory as a bundle, the same unit tested locally then published to a shared library (source code.claude.com/docs/en/plugins, accessed on 2026-09-02).
What a plugin can contain
At the root of the plugin, each directory carries a specific role. skills/ gathers the plugin's skills, in the same SKILL.md format as a personal or project skill. commands/ keeps the historical flat-file command mechanism, still supported in parallel. hooks/ carries a hooks.json file that declares the lifecycle events the plugin handles. .mcp.json declares the MCP servers bundled with it, available as soon as it is installed. agents/ defines sub-agents dedicated to the plugin. .lsp.json adds language servers, monitors/ with its monitors.json file watches logs in the background, and bin/ adds executables directly to the path used by the Bash tool. A settings.json file at the same level sets default settings for the plugin, but only the agent and subagentStatusLine keys are currently supported there.
The manifest, and a common pitfall
Only one file lives in .claude-plugin/: plugin.json, the manifest. It carries name, description, version and author. The name field also becomes the namespace for the plugin's commands: a skill named bonjour in a plugin named mon-plugin is invoked with the command /mon-plugin:bonjour. The documentation explicitly flags the most frequent mistake on this point: placing skills/, commands/, agents/ or hooks/ inside .claude-plugin/ instead of setting them at the root of the plugin, alongside this folder.
mon-plugin/
.claude-plugin/
plugin.json
skills/
bonjour/
SKILL.md
hooks/
hooks.json
.mcp.jsonTesting before publishing
The command claude --plugin-dir ./mon-plugin loads the plugin for a local session, a .zip archive of the same content also works. The command /reload-plugins reloads active plugins without restarting the session, useful while editing hooks.json or a skill. Before submitting a plugin to a shared library, claude plugin validate ./mon-plugin checks its structure. Two public marketplaces, maintained by Anthropic, then distribute plugins: claude-plugins-official, curated, already registered on Claude Code's first interactive launch, and claude-community, open to third-party submissions after review, added with the command /plugin marketplace add anthropics/claude-plugins-community.
The same mechanism that makes a standalone skill work, described in creating your own skill or your own command, applies unchanged to a skill housed in skills/ inside a plugin: the SKILL.md format does not change, only the container does.
What a plugin bundles into a single directory
Only two keys in a plugin's settings.json
A developer creates a directory named mon-plugin, writes the .claude-plugin/plugin.json file with the name, description and version fields, places a skills/ folder at the root of the plugin with a skill inside it, then runs the command claude --plugin-dir ./mon-plugin, which loads the plugin for the session and shows this skill in the list of available skills.
Write, in one sentence, what this situation establishes, and in one sentence what it does not establish.
What this establishes: The local loading, with this precise directory structure, made the skill visible in the list presented by this session.
What this does not establish: That the same structure, once published on one of the two public marketplaces, would behave identically when installed by someone else.
The three most common miscalibrations
- Too broad This session proves that any directory structure would work the same way with claude --plugin-dir.
- Too narrow This session proves nothing at all, since a single plugin containing a single skill was loaded on a single machine.
- Off the mark This session confirms that the command claude --plugin-dir also accepts a .zip archive of the same content instead of a directory.
- A plugin is a single directory that bundles skills, hooks, MCP servers, agents and commands, installable and shareable in one go.
- The plugin.json manifest lives alone in .claude-plugin/, never the skills, hooks, agents or commands directories, which stay at the root of the plugin.
- The name declared in plugin.json serves as the namespace for the plugin's commands, for example /mon-plugin:bonjour for a skill named bonjour.
- The command claude --plugin-dir tests a plugin locally before publication, and /reload-plugins reloads changes without restarting the session.
- Two public marketplaces maintained by Anthropic distribute plugins, one curated from the first launch, the other open to reviewed third-party submissions.
Choose two or three skills or hooks tied to the same need that you already have on your machine, create a directory with a minimal .claude-plugin/plugin.json subfolder, move them into the skills/ and hooks/ subfolders at the root, then load the whole thing with claude --plugin-dir followed by the path to this directory.
These points depend on an interface or a rule that may have changed since this was written. Check them on your own screen before relying on them.
- The complete list of optional fields in the plugin.json manifest and of the directories supported at the root of a plugin changes with every version of Claude Code, to be rechecked at https://code.claude.com/docs/en/plugins before publishing a real plugin.
Every datable claim in this lesson links here to the public text behind it. A source that does not open proves nothing.
- Anthropic, Claude Code, plugins reference consultée le 2026-09-02