Plugins — Packaging & Distribution

You have built custom skills, configured agents, and wired up hooks in your .claude/ directory. That works well for a single project, but the moment you want the same functionality across multiple repositories or shared with teammates, copy-pasting files breaks down. Plugins solve this by packaging your extensions into portable, versioned units that anyone can install with a single command.

In this lesson, you will learn the full plugin lifecycle: creating the manifest, bundling components, testing locally, managing costs along the way, and distributing plugins to your team or the community.

What Are Plugins?

Plugins are self-contained packages that extend Claude Code with custom skills, agents, hooks, MCP servers, and LSP servers. Unlike standalone configuration files that live in your .claude/ directory, plugins are installable, versioned, and shareable.

The key difference is namespacing. A skill in .claude/commands/review.md creates /review. The same skill inside a plugin named code-tools creates /code-tools:review. This prevents naming collisions when multiple plugins define similarly named commands.

Here is a quick comparison of when to use each approach:

Plugin Structure

Every plugin lives in its own directory. The only special directory is .claude-plugin/, which holds the manifest. Everything else sits at the plugin root:

my-plugin/
├── .claude-plugin/           # Metadata directory
│   └── plugin.json           # Plugin manifest (only file here)
├── commands/                 # Slash commands (markdown files)
│   └── deploy.md
├── skills/                   # Agent Skills (SKILL.md in subdirectories)
│   └── code-review/
│       └── SKILL.md
├── agents/                   # Custom subagents
│   └── security-reviewer.md
├── hooks/                    # Event handlers
│   └── hooks.json
├── .mcp.json                 # MCP server configurations
├── .lsp.json                 # LSP server configurations
└── scripts/                  # Supporting scripts for hooks
    └── format-code.sh

The plugin.json Manifest

The manifest at .claude-plugin/plugin.json defines your plugin's identity and configuration. The only required field is name, but a well-documented manifest makes your plugin easier to discover and maintain.

Here is a complete example:

{
  "name": "deployment-tools",
  "version": "1.2.0",
  "description": "Deployment automation skills and pre-deploy safety checks",
  "author": {
    "name": "DevOps Team",
    "email": "devops@company.com",
    "url": "https://github.com/company"
  },
  "homepage": "https://docs.company.com/claude-plugins/deployment-tools",
  "repository": "https://github.com/company/deployment-tools-plugin",
  "license": "MIT",
  "keywords": ["deployment", "ci-cd", "automation"]
}

Here is what each field does:

You can also specify custom component paths if your directories do not follow the default layout:

{
  "name": "my-plugin",
  "commands": ["./custom/commands/"],
  "agents": ["./custom/agents/reviewer.md"],
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json"
}

Custom paths supplement default directories. If both commands/ and a custom path exist, both are loaded.

Creating a Plugin Step-by-Step

Let us build a plugin called pr-helper that adds a code review skill and a specialized review agent.

mkdir -p pr-helper/.claude-plugin
mkdir -p pr-helper/skills/review
mkdir -p pr-helper/agents

{
  "name": "pr-helper",
  "version": "1.0.0",
  "description": "PR review skill and specialized review agent",
  "author": {
    "name": "Your Name"
  }
}

---
name: review
description: Reviews code changes for bugs, security issues, and best practices. Use when reviewing PRs or analyzing code quality.
---
 
When reviewing code, check for:
 
1. **Correctness**: Logic errors, off-by-one mistakes, unhandled edge cases
2. **Security**: SQL injection, XSS, hardcoded secrets, unsafe deserialization
3. **Performance**: N+1 queries, unnecessary re-renders, missing indexes
4. **Readability**: Unclear naming, missing comments on non-obvious logic
5. **Test coverage**: Untested branches, missing edge case tests
 
Format findings as a numbered list with severity (critical/warning/suggestion) and specific line references.

---
name: security-reviewer
description: Specialized agent that audits code changes for security vulnerabilities, unsafe patterns, and compliance issues.
---
 
You are a security-focused code reviewer. When invoked, perform a thorough security audit of the code or changes presented to you.
 
Focus areas:
- Authentication and authorization flaws
- Input validation and sanitization gaps
- Sensitive data exposure (API keys, tokens, PII in logs)
- Dependency vulnerabilities (known CVEs in imported packages)
- Injection attacks (SQL, command, template)
- Insecure cryptographic practices
 
For each finding, provide:
1. Severity level (Critical / High / Medium / Low)
2. Location (file and line)
3. Description of the vulnerability
4. Recommended fix with a code example
 
If no security issues are found, state that explicitly with a brief summary of what was checked.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint-check.sh"
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "pr-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/pr-db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    }
  }
}

Testing Locally

Use the --plugin-dir flag to load your plugin during development without installing it:

claude --plugin-dir ./pr-helper

Once Claude Code starts, verify your plugin works:

• Run /pr-helper:review to test the skill
• Run /agents to confirm the security-reviewer agent appears
• Make a file edit to trigger any PostToolUse hooks
• Run /help to see your commands listed under the plugin namespace

You can load multiple plugins simultaneously:

claude --plugin-dir ./pr-helper --plugin-dir ./deploy-tools

If something is not working, run with the debug flag for detailed loading information:

claude --debug --plugin-dir ./pr-helper

This shows which plugins are being loaded, any manifest errors, and component registration details.

Debugging Checklist

Cost Management with /cost

Plugin development involves frequent testing cycles, and each interaction with Claude Code consumes API tokens. Keeping an eye on costs prevents surprises, especially when running multiple plugin-loaded sessions.

Checking Session Costs

Run /cost at any point during a session to see your current token usage:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    0 lines added, 0 lines removed

This shows cumulative API cost, time spent on API calls versus wall-clock time, and a summary of code changes made during the session.

Reducing Costs During Development

Several strategies help keep plugin development affordable:

• Use /clear between test runs: Stale context from previous tests wastes tokens on every subsequent message. Clear the conversation when switching between testing different plugin components.
• Choose the right model: Use /model to switch to Sonnet for routine testing. Reserve Opus for complex debugging sessions. For subagent tasks within plugins, specify model: haiku in agent configuration.
• Minimize MCP server overhead: Each MCP server adds tool definitions to context even when idle. Disable servers you are not actively testing with /mcp.
• Write specific test prompts: "Test the review skill on auth.ts" is cheaper than "test everything in the plugin."

Team Budget Management

For API users, workspace spend limits can be configured in the Anthropic Console. Admins can set per-workspace budgets and view cost and usage reporting. The average cost is roughly $6 per developer per day, with 90% of users staying below $12 per day.

Installing Plugins

Once a plugin is published or available from a marketplace, users install it through the /plugin interface or CLI commands.

From a Marketplace

The primary installation method uses marketplaces, which are catalogs of plugins hosted on GitHub, GitLab, or other git services:

# Add a marketplace first
/plugin marketplace add your-org/claude-plugins
 
# Then install a specific plugin
/plugin install pr-helper@your-org-claude-plugins

Installation Scopes

When installing a plugin, you choose a scope that determines visibility:

# Install to project scope so the entire team gets it
claude plugin install pr-helper@my-marketplace --scope project

Managing Installed Plugins

# List and manage via interactive UI
/plugin
 
# Disable without uninstalling
/plugin disable pr-helper@my-marketplace
 
# Re-enable
/plugin enable pr-helper@my-marketplace
 
# Remove completely
/plugin uninstall pr-helper@my-marketplace
 
# Update to latest version
/plugin update pr-helper@my-marketplace

Sharing and Distributing Plugins

Creating a Marketplace

A marketplace is a repository containing a .claude-plugin/marketplace.json file that catalogs your plugins:

{
  "name": "acme-tools",
  "owner": {
    "name": "Acme DevTools Team",
    "email": "devtools@acme.com"
  },
  "plugins": [
    {
      "name": "pr-helper",
      "source": "./plugins/pr-helper",
      "description": "PR review skill and security audit agent",
      "version": "1.0.0"
    },
    {
      "name": "deploy-tools",
      "source": {
        "source": "github",
        "repo": "acme/deploy-tools-plugin"
      },
      "description": "Deployment automation and safety checks"
    }
  ]
}

Plugin sources can be relative paths (for monorepo-style marketplaces), GitHub repositories, git URLs, npm packages, or pip packages.

Hosting on GitHub

Push your marketplace repository to GitHub and share with teammates:

# Teammates add the marketplace
/plugin marketplace add acme/claude-plugins
 
# Then install individual plugins
/plugin install pr-helper@acme-claude-plugins

For private repositories, Claude Code uses your existing git credential helpers. If git clone works for the repo in your terminal, it works in Claude Code.

Team-Wide Configuration

To automatically prompt team members to install your marketplace when they clone a project, add this to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "pr-helper@acme-tools": true,
    "deploy-tools@acme-tools": true
  }
}

When team members trust the repository folder, Claude Code prompts them to install these marketplaces and plugins automatically.

Validating Before Distribution

Always validate your marketplace before sharing:

# Validate from the marketplace directory
claude plugin validate .
 
# Or from within Claude Code
/plugin validate .

This catches JSON syntax errors, missing required fields, invalid source paths, and duplicate plugin names.

Converting Standalone Config to a Plugin

If you already have working skills and hooks in your .claude/ directory, migration is straightforward:

mkdir -p my-plugin/.claude-plugin

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

claude --plugin-dir ./my-plugin

After migration, skill names change from /review to /my-plugin:review. Update any documentation or team instructions that reference the old names.

Next Steps

You now know how to create, test, and distribute plugins. In the final lesson of this course, we will pull everything together with real-world workflows that combine skills, agents, hooks, and plugins into a complete Claude Code power-user setup.