Claude Code Plugin System — Complete Reference

my-plugin/
├── PLUGIN.md                          # Plugin manifest (REQUIRED)
├── package.json                       # NPM metadata
├── skills/                            # Custom skills (optional)
│   ├── my-skill-1/
│   │   ├── SKILL.md
│   │   └── scripts/
│   └── my-skill-2/
│       ├── SKILL.md
│       └── scripts/
├── agents/                            # Custom agents (optional)
│   ├── agent-1.md
│   └── agent-2.md
├── hooks/                             # Claude Code hooks (optional)
│   ├── pre-tool-use/
│   │   └── validator.js
│   └── post-execution/
│       └── reporter.js
├── mcp-servers/                       # MCP server definitions (optional)
│   ├── server-1.json
│   └── server-2.json
├── commands/                          # Slash commands (optional)
│   ├── /analyze
│   │   └── COMMAND.md
│   └── /review
│       └── COMMAND.md
└── docs/
    ├── README.md
    ├── GETTING-STARTED.md
    └── API-REFERENCE.md

---
name: my-plugin                       # kebab-case, unique in marketplace
version: 1.2.0                         # Semantic versioning
description: >                         # Max 200 characters
  What the plugin does. Keywords at the end.
  Keywords: data-processing, workflow, automation
author: "My Name / Company"
license: MIT                           # SPDX License ID
repository: "https://github.com/user/repo"
homepage: "https://plugin.example.com"
bugs: "https://github.com/user/repo/issues"

# === Plugin Components ===
includes:
  skills: ["./skills"]                # Directories with skills
  agents: ["./agents"]                # Agent definitions
  mcp-servers: ["./mcp-servers"]      # MCP servers
  hooks: ["./hooks"]                  # Pre/Post execution hooks
  commands: ["./commands"]            # Slash commands

# === Dependencies ===
requires:
  claude-code: ">=0.20.0"             # Minimum Claude Code version
  plugins: ["plugin-base"]            # Other plugins

# === Permissions ===
permissions:
  - tool:read                         # Allows Read tool
  - tool:write                        # Allows Write tool
  - tool:bash                         # Allows Bash execution
  - network:outbound                  # Outbound network requests
  - credential:vault                  # Access to vault secrets
  - filesystem:sandbox                # Sandbox filesystem

# === Marketplace Metadata ===
categories: ["data-processing", "automation", "integration"]
tags: ["enterprise", "security", "compliance"]
featured: false
rating: 4.8
downloads: 12341
compatibility: ["macos", "linux", "windows"]

keywords: "data processing workflow automation integration security"
---

# Search in marketplace
claude plugin search "data processing"

# Filter by category
claude plugin search --category "automation" --sort downloads

# List all plugins
claude plugin list --remote

# Standard marketplace (anthropics/claude-plugins-official)
claude plugin add marketplace:plugin-name

# Example: CSV Processor plugin
claude plugin add marketplace:csv-processor

# With specific version
claude plugin add marketplace:[email protected]

# With auto-update
claude plugin add marketplace:csv-processor --auto-update

# Directly from GitHub
claude plugin add github:username/repo

# With specific branch
claude plugin add github:username/repo#develop

# With specific tag
claude plugin add github:username/repo#v1.2.0

# Examples
claude plugin add github:anthropics/claude-plugins-official#main
claude plugin add github:buildwithclaude/awesome-plugins#main

# From local directory
claude plugin add ./my-plugin

# From ZIP archive
claude plugin add ./plugins/my-plugin.zip

# Symlink (for development)
claude plugin add --symlink ./my-plugin

# Configure private registry
claude config set plugin-registry https://registry.private.com

# Authentication
claude config set plugin-registry-token $TOKEN

# Installation from private registry
claude plugin add private:my-company-plugin

# Show installed plugins
claude plugin list --installed

# Plugin status
claude plugin info plugin-name

# Plugin version
claude plugin version plugin-name

# Check dependencies
claude plugin deps plugin-name

# Check permissions
claude plugin perms plugin-name

# Enable/disable plugin
claude plugin enable plugin-name
claude plugin disable plugin-name

# Update plugin
claude plugin update plugin-name
claude plugin update --all

# Install specific version
claude plugin update [email protected]

# Remove plugin
claude plugin remove plugin-name

# Rollback to previous version
claude plugin rollback plugin-name

# Edit plugin configuration
claude plugin config plugin-name

# Change permissions
claude plugin perms plugin-name --deny tool:bash

# Set API key or credentials
claude plugin creds plugin-name --set OPENAI_API_KEY=$TOKEN

# Plugin environment variables
claude plugin env plugin-name --set VAR=value

# View plugin logs
claude plugin logs plugin-name

# Enable debug mode
claude plugin debug plugin-name

# Validate plugin
claude plugin validate plugin-name

# Health check
claude plugin health plugin-name

# Run tests
claude plugin test plugin-name

---
# .claude/skills/my-skill/SKILL.md
name: my-skill
description: "Does something useful. Trigger: something, useful"
version: 1.0.0
model: sonnet
allowed-tools: [Read, Grep, Bash]
user-invocable: true
last-verified: 2026-03-21
---

# My Skill — What it does

## Process

1. Validate input
2. Process data
3. Format output

The skill works with these file types:
- JSON input from user
- CSV output for processing
- Markdown for documentation

---
# agents/my-agent.md
name: my-agent
description: "Specialist for data analysis"
model: opus
tools: [Read, Grep, Glob, Bash, Write, Edit]
disallowedTools: []
maxTurns: 100
skills:
  - my-skill
  - data-processor
---

# My Agent — Data Analysis Specialist

## Identity

I am an expert in data analysis and visualization.

## Workflow

1. Read and validate data
2. Detect anomalies
3. Extract insights
4. Generate report

// hooks/pre-tool-use/validator.js
module.exports = {
  name: 'input-validator',
  event: 'pre-tool-use',
  async handler(context) {
    const { tool, args } = context;

    // Validation for Bash calls
    if (tool === 'Bash') {
      const dangerousPatterns = ['rm -rf', 'sudo', 'reboot'];
      const cmd = args.command || '';

      if (dangerousPatterns.some(p => cmd.includes(p))) {
        throw new Error(`Dangerous command blocked: ${cmd}`);
      }
    }

    return context; // Pass through or block
  }
};

claude plugin add marketplace:claude-mem

# LiteLLM Plugin Manager
from litellm import Router
from litellm.plugins import PluginRegistry

# Initialize plugin registry
registry = PluginRegistry(
    registry_url="https://registry.enterprise.com",
    auth_token=os.environ["REGISTRY_TOKEN"],
    enable_audit_log=True
)

# Plugin installation with governance
router = Router(
    model_list=[
        {
            "model_name": "claude-opus",
            "litellm_params": {
                "model": "claude-3-opus-20240229",
                "api_key": os.environ["ANTHROPIC_API_KEY"]
            }
        }
    ],
    plugins=[
        {
            "name": "csv-processor",
            "version": "2.1.0",
            "permissions": ["tool:read", "tool:bash"],
            "rate_limit": {"requests": 100, "period": 3600},
            "timeout": 30,
            "require_approval": False
        },
        {
            "name": "production-workflow",
            "version": "1.0.0",
            "permissions": ["tool:write", "network:outbound"],
            "require_approval": True,
            "audit_log": True
        }
    ]
)

# Audit trail
async def log_plugin_usage(plugin_name, action, user_id, result):
    await registry.audit_log({
        "timestamp": datetime.now(),
        "plugin": plugin_name,
        "action": action,
        "user_id": user_id,
        "result": "success" if result else "failed"
    })

# Plugin version pinning for stability
@router.log_hook
def version_lock_check(model, messages, kwargs):
    required_versions = {
        "csv-processor": "2.1.0",
        "humanizer-pro": "3.0.0"
    }

    for plugin, version in required_versions.items():
        current = registry.get_plugin_version(plugin)
        if current != version:
            raise Exception(f"Plugin {plugin} version mismatch: {current} != {version}")

# Plugin permissions are explicit
permissions:
  # Tool access
  - tool:read              # Read filesystem
  - tool:write             # Write filesystem
  - tool:bash              # Shell commands
  - tool:glob              # Pattern matching

  # Network
  - network:outbound       # External HTTP/HTTPS
  - network:dns            # DNS lookups

  # Credentials
  - credential:vault       # Access vault secrets
  - credential:env         # Environment variables

  # System
  - system:memory          # RAM-intensive operations
  - system:cpu             # CPU-intensive operations

# Strict sandbox (read-only)
claude plugin add marketplace:plugin-name --sandbox strict

# Standard sandbox (limited tools)
claude plugin add marketplace:plugin-name --sandbox standard

# No sandbox (full access)
claude plugin add marketplace:plugin-name --sandbox none