Anthropic: plugins

Source: Create plugins

Checked: 13 July 2026. Component types and supported plugin settings remain product-version dependent.

Evidence type: product documentation and explicit packaging recommendations.

Standalone versus plugin

Anthropic recommends standalone .claude/ configuration for a single project, personal workflows, and experimentation. Plugins are for cross-project reuse, team or community distribution, versioned releases, easy updates, and conflict- free namespacing. The recommended lifecycle is to iterate locally first and convert to a plugin when the workflow is ready to share.

Package boundary

A plugin may contain:

• one or more skills;
• custom agents;
• lifecycle hooks;
• MCP server configuration;
• language-server configuration;
• background monitors;
• executables placed on the agent shell’s path;
• a limited set of default settings.

The manifest identifies the namespace, description, version, and optional ownership metadata. If an explicit version exists, consumers receive updates only when it changes; a git-distributed plugin can instead use commit identity. Components live at the plugin root, not inside the manifest directory.

The documented package layout is:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── bin/
├── .mcp.json
├── .lsp.json
└── settings.json

Only plugin.json belongs under .claude-plugin/. A plugin-root CLAUDE.md does not become project context; distributable instructions belong in a skill. The manifest is optional when all components use standard locations, although an explicit manifest gives the package stable identity and ownership metadata.

The bundle should remain cohesive. The fact that plugins can include many component types is not a reason to combine unrelated capabilities under one release lifecycle.

Useful component patterns

• Prefer existing official LSP plugins for common languages; custom LSP packages still require the language-server binary on each machine.
• Background monitors can turn log, file, or external-status lines into live agent notifications. This makes observability available without a prompt to start watching, but also creates continuous context and process cost.
• Plugin defaults can activate a custom main agent with defined prompt, tool, and model constraints.
• Plugin-provided binaries make deterministic mechanics available without teaching the agent how to reconstruct them.

At the time checked, plugin settings.json supports only agent and subagentStatusLine; unknown keys are silently ignored. Plugin defaults take priority over settings embedded in the manifest, so tests should verify the effective configuration rather than only validating JSON shape.

Testing and release

Useful development behaviours include:

• claude --plugin-dir ./my-plugin for session-local source loading;
• repeated --plugin-dir flags to compose development plugins;
• /reload-plugins to reload skills, agents, hooks, MCP, and LSP components;
• a local plugin taking precedence over an installed copy with the same name, unless managed policy forces the installed state; and
• --plugin-url for a trusted session-only archive, with startup continuing without the plugin if retrieval or validation fails.

Marketplace installations are copied into ~/.claude/plugins/cache, with each version isolated. Old versions receive a seven-day grace period so existing sessions keep working. Installed plugins cannot escape their package through external file references; symlinks are preserved only when they resolve inside the plugin directory.

Anthropic supports direct local loading, local precedence over a marketplace copy for development, hot reload, multiple simultaneous plugins, and session- only loading from trusted archives. The documented test sequence checks every skill, agent visibility, and hook behaviour independently.

Before sharing, add installation and usage documentation, choose a versioning strategy, test with other users, validate the package, and distribute through an appropriate public or private marketplace. Remote archives and third-party marketplaces are trust boundaries. Community submission includes validation and automated safety screening; approval does not eliminate consumer review.

When migrating standalone configuration, remove the originals after verifying the package because local definitions can override or duplicate plugin components.

Standards implications

• Promote proven local workflows; do not design every experiment as a shared package.
• Require manifest ownership, documentation, versioning, changelog, validation, component tests, and a retirement path.
• Define plugin cohesion and security-review criteria, especially for binaries, hooks, monitors, MCP servers, and remote archives.
• Use namespaces and controlled distribution to prevent collision and drift.