Plugins: Packaging and Distributing Capabilities

In the previous chapters, we learned about Hooks (event-driven automation) and Skills (reusable prompt templates). But when your team accumulates many related Hooks, Skills, and even MCP server configurations, managing and distributing them individually becomes difficult. Plugins solve this problem — they package related capabilities into an installable, distributable unit.

Think of a Plugin as a “capability package”: it can simultaneously contain multiple Skills, multiple Hooks, and MCP server configurations, providing a complete enhanced experience around a specific domain (such as testing, deployment, or code quality).

Plugin Directory Structure

A Plugin follows a conventional directory structure:

PLUGIN.md is the Plugin’s manifest file, describing the Plugin’s name, purpose, and included capabilities:

# Testing Plugin

A comprehensive testing plugin for Claude Code.

## Skills
- /test-unit — Run unit tests for specified files or modules
- /test-e2e — Run end-to-end test suites
- /test-coverage — Generate and analyze test coverage reports

## Hooks
- PostToolUse: Auto-lint after file writes
- PreToolUse: Block commits without passing tests

## MCP Servers
- coverage-server: Provides real-time coverage data

Plugin Components

A Plugin can contain any combination of these three capability types:

Skills (Prompt Templates)

Skills within a Plugin are identical to standalone Skills — they are Markdown files invoked via slash commands. The only difference is they are organized under the Plugin’s skills/ directory.

# skills/test-unit.md

Run unit tests for the specified file or module.

Steps:
1. Identify the test framework (Jest, Vitest, Mocha, etc.)
2. Find corresponding test files for the target
3. Execute tests with verbose output
4. If tests fail, analyze failures and suggest fixes
5. Report coverage for the tested files

Hooks (Automated Triggers)

Plugin Hooks are configured in hooks/settings.json and merged into the user’s Hook configuration upon installation:

{
"hooks": {
  "PostToolUse": [
    {
      "matcher": "Write",
      "command": "npx eslint --fix $CLAUDE_FILE_PATH 2>/dev/null || true"
    }
  ],
  "PreToolUse": [
    {
      "matcher": "Bash",
      "command": "echo $CLAUDE_TOOL_INPUT | grep -q 'git push' && npm test || true"
    }
  ]
}
}

MCP Server Configuration

Plugins can configure MCP servers, extending the external data sources and tools that Claude Code can access:

{
"mcpServers": {
  "coverage-server": {
    "command": "npx",
    "args": ["coverage-mcp-server", "--root", "."],
    "env": {
      "COVERAGE_DIR": "./coverage"
    }
  }
}
}

Plugin vs Standalone Skills

Why use Plugins instead of managing Skills and Hooks independently?

Distribution Methods

Plugins can be distributed through multiple channels:

Git Repositories

The most common distribution method. Teams and communities publish Plugins as Git repositories:

# Install a Plugin
claude plugin add https://github.com/team/testing-plugin

# Install from a specific branch
claude plugin add https://github.com/team/testing-plugin --branch v2

npm Packages

For the Node.js ecosystem, Plugins can be distributed as npm packages:

# Install as an npm package
claude plugin add @team/claude-testing-plugin

Local Paths

During development, install from a local path:

# Install from a local path
claude plugin add ./my-local-plugin

Configuration and Installation

Plugin installation information is recorded in the configuration file:

{
"plugins": [
  {
    "name": "testing-plugin",
    "source": "https://github.com/team/testing-plugin",
    "version": "1.2.0",
    "enabled": true
  },
  {
    "name": "deploy-plugin",
    "source": "@team/claude-deploy-plugin",
    "version": "3.0.1",
    "enabled": true
  }
]
}

Each Plugin can be individually enabled or disabled — you can temporarily turn off certain features without uninstalling.

Example: Testing Plugin

Let’s look at a complete Testing Plugin that provides comprehensive enhancement around the “testing” domain:

Once installed, this Plugin provides:

1. Use /test to have Claude intelligently find and run relevant tests
2. Auto-run ESLint fix after every file write
3. Auto-run the test suite before pushing code
4. Claude can access real-time test coverage data through the MCP server

This is the power of Plugins — not a single feature, but a complete workflow enhancement around a specific domain.

Plugin Design Principles

• Single domain: A Plugin focuses on one domain (testing, deployment, code quality, etc.) — don’t mix unrelated functionality.
• Progressive enhancement: Each capability in a Plugin should be independently valuable, even if only a subset is used.
• Complete documentation: PLUGIN.md should clearly describe every capability and how to use it.
• Version compatibility: Maintain backward compatibility when updating Plugins to avoid breaking existing workflows.
• Least privilege: MCP server configurations should follow the principle of least privilege, requesting only necessary permissions.

Relationship to the Ecosystem

Plugins are the highest-level abstraction in Claude Code’s extension ecosystem:

From low-level tool calls, to the MCP protocol at the middle layer, to Hook automation and Skill workflow encapsulation, and finally Plugins packaging everything together — this forms Claude Code’s complete capability extension system.