Plugins

Package Claude Code skills, agents, hooks, MCP servers, and settings into reusable extensions for teams and projects.

What Plugins Are

Plugins are the packaging layer for Claude Code extensions. A plugin can bundle skills, subagents, hooks, MCP servers, and default settings into one versioned unit.

Use standalone .claude/ configuration while you are experimenting. Convert to a plugin when the setup should be shared, versioned, installed across projects, or distributed through a marketplace.

Standalone vs Plugin

Plugin namespacing prevents two teams from accidentally shipping different /review commands with the same name.

What a Plugin Can Contain

The result is a portable agent environment rather than a pile of copied instructions.

Basic Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── review/
│       └── SKILL.md
├── agents/
│   └── api-reviewer.md
└── hooks/
  └── format-after-edit.json

The manifest gives Claude Code the plugin identity:

{
"name": "team-engineering",
"description": "Shared review, verification, and release workflows",
"version": "1.0.0",
"author": {
  "name": "Engineering Platform"
}
}

When to Create a Plugin

Create a plugin when:

• Multiple repositories need the same skills or subagents.
• The setup has become stable enough to version.
• You want teammates to install and update it consistently.
• You need namespacing to avoid command conflicts.
• You are preparing an internal or public marketplace package.

Keep it standalone when the workflow is still changing daily or only matters in one repo.

Migration Pattern

1. Start with project-local .claude/skills/, .claude/agents/, hooks, and MCP config.
2. Remove project-specific secrets and hard-coded paths.
3. Create .claude-plugin/plugin.json.
4. Move reusable pieces into plugin directories.
5. Test locally with the plugin directory before sharing.
6. Publish through your team's chosen distribution path.

Safety Notes

• Do not hide destructive behavior inside a plugin. Make high-impact hooks obvious.
• Keep secrets in user or environment configuration, not plugin files.
• Document required external tools and MCP servers.
• Prefer narrow subagent tools and permission modes.
• Version breaking changes carefully.

Official References

• Create plugins↗
• Discover and install prebuilt plugins↗
• Plugins reference↗
• Extend Claude Code↗