Plugins

Plugins bundle skills, subagents, hooks, MCP servers, and slash commands into a single distributable unit. A plugin is a directory with a plugin.json manifest. Install one from the marketplace, write your own, or distribute yours to your team. This lesson covers the full plugin lifecycle.

What you'll learn

• Plugins are directories with a plugin.json manifest, they bundle skills, agents, hooks, MCP configs, and commands
• claude plugin install <name> installs from the marketplace; claude plugins list shows installed plugins
• A skill folder becomes a plugin by adding a .claude-plugin/plugin.json , no separate repo needed

The problem

You've built a useful skill, a custom subagent, and a hook that formats code on save. Now you want to share them with your team, or reuse them across projects. Copying files between .claude/ directories doesn't scale. Plugins solve this by packaging everything into one installable unit.

Options & when to use each

Approach	Good for	When to use it
Marketplace plugin	Public, community-maintained extensions	General-purpose tools anyone can use
Private plugin repo	Team-internal tools	Company-specific workflows, internal APIs
Skill-directory plugin	Simple single-project extensions	When you just need a skill + hooks, no separate repo
Manual file sharing	One-off sharing	Testing before packaging as a plugin

Build it

Step 1: Install a plugin from the marketplace

Use the CLI to securely download and install verified plugins directly from the Claude Code marketplace.

claude plugin install <plugin-name>

Step 2: List installed plugins

Run this command to display all currently installed plugins and verify their active status within your workspace.

claude plugins list

Step 3: Turn a skill into a plugin

Add .claude-plugin/plugin.json to your skill directory:

{
  "name": "my-workflow",
  "version": "1.0.0",
  "description": "Custom workflow for our team"
}

The skill directory now loads as a plugin named my-workflow@skills-dir. It can bundle agents, hooks, and MCP servers alongside the skill.

Step 4: Manage plugins

Maintain your plugin ecosystem by using these built-in commands to remove outdated extensions or upgrade them to their latest versions.

claude plugin remove <name>   # uninstall
claude plugin update <name>   # update to latest

What goes wrong

Mistake	How you notice it	The fix
Plugin not appearing after install	claude plugins list shows it but commands don't work	Run /reload-plugins or restart the session
Plugin conflict with same-named skill	One overrides the other unexpectedly	Plugin skills use plugin-name:skill-name namespace. Check for name conflicts with claude plugins list
Workspace trust blocks plugin	Plugin files in .claude/skills/ require trust	Accept the workspace trust dialog. Project-level plugins need trust for the directory

Confirm it worked

Run these steps to install a test plugin and verify that its bundled commands immediately become available in your interactive session.

# 1. Install a plugin
claude plugin install <name>

# 2. Verify it appears
claude plugins list

# 3. Test a bundled command in an interactive session
claude
# /plugin-command

Next: GitHub Integration & PR Reviews