Claude Code plugins
Plugins package reusable Claude Code extensions so teams can share skills, subagents, hooks, and MCP servers with version control and marketplace distribution.
- Last verified
- Applies to
- Claude Code 2.1.x. CLI spellings were checked on local version 2.1.198; official docs may describe newer 2.1.x behavior.
- Verification method
- Plugin validation, local loading, namespacing, and trust boundaries were checked in local CLI help and official docs. No marketplace, remote archive, or user plugin directory was changed.
Reproducible practice
Validate a minimal plugin locally before any marketplace install
Prove manifest structure, namespacing, and local load behavior from a disposable directory without touching user plugin state.
Prerequisites
- Claude Code with `plugin validate` and `--plugin-dir` available.
- A unique temporary directory.
- No remote plugin URL or unreviewed executable component.
Steps
Create a minimal local plugin
Keep the manifest and skill at documented plugin-root locations.
Step 1 PLUGIN_LAB=$(mktemp -d "${TMPDIR:-/tmp}/claude-plugin.XXXXXX") printf '%s\n' "$PLUGIN_LAB" mkdir -p "$PLUGIN_LAB/.claude-plugin" "$PLUGIN_LAB/skills/hello" printf '%s\n' '{"name":"local-audit","version":"0.0.1","description":"Disposable validation fixture","author":{"name":"Local fixture"}}' > "$PLUGIN_LAB/.claude-plugin/plugin.json" printf '%s\n' '---' 'description: Return a fixed local test greeting.' 'disable-model-invocation: true' '---' '' 'Say: local plugin fixture loaded.' > "$PLUGIN_LAB/skills/hello/SKILL.md"Validate without installing
Use the CLI validator against the exact temporary path.
Step 2 claude plugin validate "$PLUGIN_LAB"Load for one session
Start with `--plugin-dir` and inspect `/help`; no marketplace or persistent install is required.
Step 3 claude --plugin-dir "$PLUGIN_LAB"Review before distribution
Inspect hooks, MCP, binaries, settings, licenses, and update source before considering a marketplace.
Expected result
Validation passes, the skill appears under the `local-audit` namespace for one session, and no persistent plugin is installed.
Validation
- Run `claude plugin validate` after every manifest change.
- Confirm no unexpected hooks, MCP servers, monitors, or binaries exist.
- List installed plugins and verify the fixture was not persisted.
Failure handling
Validation fails
Fix the reported manifest or layout error; do not bypass validation by installing.
Unexpected component loads
Exit immediately and inspect the plugin root before another session.
Cleanup or rollback
- Exit the local session, verify PLUGIN_LAB is the printed mktemp path, then remove only that directory.
- If a real plugin was installed, disable it before uninstalling and preserve incident evidence.
Boundaries and when not to use it
- Plugins can ship hooks, MCP servers, binaries, agents, and settings; treat installation as code execution.
- A valid manifest proves structure, not trustworthiness or safe runtime behavior.
Plugins vs standalone .claude config
Standalone files in `.claude/` are fast for personal experiments. Plugins are better when you need sharing, namespacing, updates, and reuse across repositories.
Standalone
Best for one repo, quick iteration, and short skill names like `/deploy`.
Read guidePlugins
Best for team distribution, marketplaces, and namespaced skills like `/my-plugin:deploy`.
Read guideMigration path
Start standalone, then convert to a plugin when the workflow is stable enough to share.
Read guideWhat a plugin can contain
A plugin directory can include a manifest plus skills, agents, hooks, and MCP server definitions. Marketplaces let organizations curate approved plugins for developers.
| Command | Description |
|---|---|
/plugin | Open the plugin manager inside a session. |
claude plugin install | Install a plugin from a marketplace or local path. |
claude --plugin-dir | Load a plugin directory for local testing. |
{
"name": "my-first-plugin",
"description": "Team workflow helpers",
"version": "1.0.0"
}Build and test a plugin
Create a plugin folder, add a manifest under `.claude-plugin/plugin.json`, place skills or hooks inside the plugin tree, then test with `--plugin-dir` before publishing to a marketplace.
Manifest
Define name, description, and version so Claude Code can display the plugin correctly.
Read guideLocal test
Use `--plugin-dir ./my-plugin` to iterate without publishing.
Read guideMarketplace
Distribute approved plugins through an org marketplace for consistent team installs.
Read guidePlugin ecosystem connections
Plugins often bundle capabilities documented elsewhere. Know where to look when a plugin misbehaves or needs extension.
Skills inside plugins
Plugin skills use namespaced slash commands such as `/my-plugin:deploy`.
Read guideHooks inside plugins
Ship validation or formatting hooks with the plugin manifest.
Read guideMCP servers
Bundle org-approved MCP servers for consistent external tool access.
Read guideSubagents
Package review or research agents for parallel team workflows.
Read guideWhen plugins help most
Plugins shine for code review packs, security guidance, release automation, design-system workflows, and any extension that multiple repositories should load the same way.
Code review
Bundle review skills and hooks that enforce team standards on every diff.
Read guideSecurity
Ship security-guidance-style checks as an installable plugin instead of copy-pasting rules.
Read guidePlatform teams
Publish internal MCP and skill packs once, then install them across many services.
Read guidePlugin checklist
Start standalone
Prototype skills and hooks in `.claude/` before packaging a plugin.
Read guideNamespace skills
Expect plugin skills to use `/plugin-name:skill` names to avoid collisions.
Read guideVersion the manifest
Bump plugin version when behavior changes so teams can track upgrades.
Read guideTest with --plugin-dir
Validate the plugin locally before publishing to a marketplace.
Read guide