What Is the Purpose of the `.claude-plugin` Directory? A Complete Guide to Claude Code Plugin Structure

The .claude-plugin directory is the canonical storage location for Claude Code plugin metadata, configuration files, and marketplace manifests, enabling automatic discovery, validation, and secure loading of plugins.

Claude Code relies on this directory structure to manage plugins in a consistent, secure, and deterministic way. Every plugin in the anthropics/claude-plugins-community repository follows this convention, allowing the CLI to surface commands, validate integrity, and handle user-configurable secrets without exposing sensitive data.

Core Functions of the .claude-plugin Directory

The .claude-plugin directory serves four primary purposes that together create a robust plugin ecosystem.

Plugin Manifest Definition

Each plugin must contain a plugin.json file inside its .claude-plugin folder. This manifest defines the plugin's identity, version, author, and any secrets users need to configure.

Claude Code reads this file to expose the plugin's commands and enforce safety checks. For example, the TRES Finance plugin's manifest lives at [tres-finance-plugin/.claude-plugin/plugin.json](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json).

The userConfig section is particularly important—it declares sensitive fields like API keys separately from the main configuration, ensuring Claude Code can prompt for these values at runtime without hardcoding them.

Marketplace Index Aggregation

The top-level .claude-plugin/marketplace.json file serves as the central catalog for all community plugins. This file aggregates individual plugin manifests and enables the CLI to list and install plugins from a curated marketplace.

You can view the repository-wide marketplace file at [/.claude-plugin/marketplace.json](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json).

MCP Server Configuration

Optional .mcp.json files within .claude-plugin directories declare hosted MCP (Model Context Protocol) servers—the runtime that executes plugin skills. These files tell Claude Code where and how to execute plugin code.

Validation scripts in the CI pipeline explicitly look for .claude-plugin/.mcp.json files to ensure proper runtime configuration.

CI Validation Pipeline

GitHub Actions workflows such as [validate-plugins.yml](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) scan .claude-plugin/** paths to enforce that every plugin has:

• A well-formed plugin.json manifest
• All required fields present and valid
• No leaked secrets in configuration files

This automated validation prevents broken or insecure plugins from reaching users.

What the .claude-plugin Directory Enables

The standardized structure makes four key capabilities possible:

1. Automatic discovery — Claude Code detects plugins immediately when a repository is opened
2. Pre-installation validation — Integrity checks run before any plugin executes
3. Secure configuration UI — The userConfig schema generates prompts for required secrets
4. Nightly marketplace synchronization — The community's latest offerings stay in sync automatically

Practical Examples

Creating a Minimal plugin.json

Place this file at my-plugin/.claude-plugin/plugin.json:

{
  "name": "hello-world",
  "description": "A simple example that says hello.",
  "version": "0.1.0",
  "author": { "name": "Your Name" },
  "homepage": "https://github.com/your-org/hello-world-plugin",
  "userConfig": {
    "API_KEY": {
      "title": "API Key",
      "description": "Your optional API key for external services.",
      "type": "string",
      "sensitive": true
    }
  }
}

When loaded, Claude Code automatically surfaces a /hello-world command and prompts for API_KEY if the skill requires it.

Adding a Plugin to the Marketplace

Contribute to the community marketplace by adding an entry to the top-level marketplace.json:

{
  "name": "hello-world",
  "description": "A simple example that says hello.",
  "source": { "source": "url", "url": "https://github.com/your-org/hello-world-plugin.git", "sha": "⟨latest-commit⟩" },
  "homepage": "https://github.com/your-org/hello-world-plugin"
}

After merge, the nightly CI job updates the marketplace index, making the plugin installable via claude plugin install hello-world.

Key Files in the .claude-plugin Ecosystem

File	Location	Purpose
plugin.json	Per-plugin .claude-plugin/ directory	Defines plugin identity, version, author, and userConfig secrets
marketplace.json	Repository root .claude-plugin/ directory	Central catalog for CLI list/install operations
.mcp.json	Optional in .claude-plugin/ directories	Declares hosted MCP servers for skill execution
CI validation scripts	.github/workflows/validate-plugins.yml	Enforces structure, detects missing manifests, prevents secret leakage

Summary

• The .claude-plugin directory provides a self-contained, version-controlled source of truth for Claude Code plugins
• plugin.json defines each plugin's metadata and securely declares user-configurable secrets
• marketplace.json aggregates all community plugins for CLI discoverability
• .mcp.json optionally specifies runtime servers for skill execution
• CI validation ensures every plugin meets security and structural requirements before distribution

Frequently Asked Questions

What happens if a plugin is missing the .claude-plugin directory?

Claude Code will not recognize or load the plugin. The validation scripts in [validate-plugins.yml](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) explicitly scan for .claude-plugin/** patterns, and any submission missing this directory will fail CI checks and be blocked from the marketplace.

How does Claude Code handle sensitive configuration values?

The userConfig field in plugin.json defines secrets with "sensitive": true, which prevents these values from being written to disk in plain text. Instead, Claude Code prompts users at runtime and stores values securely, keeping them separate from the read-only plugin manifest.

Can a plugin have multiple .claude-plugin directories?

No. Each plugin repository should contain exactly one .claude-plugin directory at its root level with a single plugin.json file. The marketplace structure in anthropics/claude-plugins-community maps one directory per plugin to maintain clean dependency boundaries and deterministic loading behavior.

Is the .mcp.json file required for all plugins?

No. The .mcp.json file is optional and only needed when a plugin requires hosted MCP servers for runtime skill execution. Simple plugins that run entirely within Claude Code's built-in environment can omit this file entirely.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}