Plugins — Shareable Extensions

Plugins are self-contained, versioned bundles of skills, agents, hooks, and MCP servers that can be shared across teams and distributed via marketplaces.

Plugins vs. Standalone Configuration

Approach	Skill names	Best for
Standalone (`.claude/` directory)	`/hello`	Personal, project-specific, quick experiments
Plugins (self-contained directories)	`/plugin-name:hello`	Sharing with team, distributing, versioned releases

Start with standalone config in .claude/ for quick iteration, then convert to a plugin when ready to share.

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest (metadata)
├── skills/
│   └── hello/
│       └── SKILL.md         # Custom skills
├── agents/
│   └── reviewer.md          # Custom subagents
├── hooks/
│   └── hooks.json           # Event hooks
├── .mcp.json                # MCP server configs
├── .lsp.json                # LSP server configs (code intelligence)
├── monitors/
│   └── monitors.json        # Background monitors
├── bin/                     # Executables added to PATH
└── settings.json            # Default settings when plugin is enabled

Important: commands/, agents/, skills/, hooks/ go at the plugin ROOT — NOT inside .claude-plugin/.

Quick Start: Create Your First Plugin

1. Create the directory and manifest

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Field	Purpose
`name`	Unique ID and skill namespace. Skills become `/my-first-plugin:skill-name`
`description`	Shown in the plugin manager
`version`	If set, updates only come when you bump this. If omitted, every git commit is a new version
`author`	Optional attribution

2. Add a skill

mkdir -p my-first-plugin/skills/hello

---
description: Greet the user with a friendly message
---

Greet the user named "$ARGUMENTS" warmly and ask how you can help today.

3. Test locally

claude --plugin-dir ./my-first-plugin

Then try:

/my-first-plugin:hello Alex

Install Plugins via CLI

# Initialize a plugin in your skills directory (auto-loaded)
claude plugin init my-tool
# Creates ~/.claude/skills/my-tool/ — loads automatically as my-tool@skills-dir

# Validate before submitting
claude plugin validate

Plugin Components

Skills

skills/
  code-review/
    SKILL.md        # Claude invokes this automatically when relevant

Agents

agents/
  security-reviewer.md    # Custom subagent

Hooks

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{"type": "command", "command": "npm run lint:fix"}]
    }]
  }
}

MCP Servers

{
  "mcpServers": {
    "my-api": {
      "command": "node",
      "args": ["./bin/mcp-server.js"]
    }
  }
}

LSP Servers (Code Intelligence)

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {".go": "go"}
  }
}

Background Monitors

[{
  "name": "error-log",
  "command": "tail -F ./logs/error.log",
  "description": "Application error log"
}]

Each stdout line from command is delivered to Claude as a notification.

Default Settings

// settings.json (at plugin root)
{
  "agent": "security-reviewer"   // Activate a plugin agent as main thread
}

Installing Plugins

In VS Code

Type /plugins → graphical plugin manager → browse and install.

From CLI

/plugin install typescript-lsp@claude-plugins-official
/plugin install my-plugin@my-marketplace

Load without installing (dev/test)

claude --plugin-dir ./my-plugin
claude --plugin-dir ./my-plugin.zip
claude --plugin-url https://example.com/my-plugin.zip

# Multiple plugins
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Plugin Scopes

When installing, choose:

Personal (~/.claude/skills/) — all your projects
Project (.claude/skills/) — committed, shared with team
Local (project-level, not committed) — only you, this repo

Convert Existing Config to Plugin

mkdir -p my-plugin/.claude-plugin

# Create plugin.json with name, description, version

# Copy existing files
cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

# For hooks, create hooks/hooks.json from your settings.json hooks object

# Test
claude --plugin-dir ./my-plugin

# Remove originals to avoid duplicates
rm -rf .claude/commands .claude/agents .claude/skills

Distributing: Marketplaces

A marketplace is a git repository with a marketplace.json listing available plugins.

Official marketplaces:

claude-plugins-official — curated by Anthropic (auto-registered on first launch)
claude-community — third-party submissions: /plugin marketplace add anthropics/claude-plugins-community

Add your own:

/plugin marketplace add https://github.com/your-org/your-plugins

Submit to community marketplace:

Reload Plugins

After making changes to a plugin:

/reload-plugins

No need to restart Claude Code.

Real-World Plugin Examples

Team Conventions Plugin

Ship your org’s coding standards as a plugin:

skills/pr-review/SKILL.md — PR checklist
skills/migration/SKILL.md — database migration patterns
hooks/hooks.json — auto-lint on file save
agents/security-reviewer.md — security-focused code reviewer

Platform Monitoring Plugin

.mcp.json — connect to your internal metrics API
monitors/monitors.json — tail error logs in background
skills/incident-response/SKILL.md — incident runbook

Code Intelligence Plugin

.lsp.json — language server for your custom DSL
Enables go-to-definition, find-references, type errors

🧠 Quick Recall

Trick: “A plugin is the shipping box for skills + hooks + MCP + agents.”

👨‍🏫 Teach It

Show: install one from claude-plugins-official live.
They’ll trip on: forgetting /reload-plugins after installing.

Learning path: ⬅ 26-mcp-real-examples.md · Index · ➡ 28-agents-overview.md

Written by Fenil Patel