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

> Discover the purpose of the .claude-plugin directory. Learn how it stores metadata, config files, and manifests for automatic discovery, validation, and secure loading of Claude plugins.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/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)](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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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)](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json).

### MCP Server Configuration

Optional [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)

Place this file at [`my-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/my-plugin/.claude-plugin/plugin.json):

```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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json):

```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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) | Per-plugin `.claude-plugin/` directory | Defines plugin identity, version, author, and `userConfig` secrets |
| [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) | Repository root `.claude-plugin/` directory | Central catalog for CLI list/install operations |
| [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) | Optional in `.claude-plugin/` directories | Declares hosted MCP servers for skill execution |
| CI validation scripts | [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** defines each plugin's metadata and securely declares user-configurable secrets
- **[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** aggregates all community plugins for CLI discoverability
- **[`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file required for all plugins?

No. The [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.