# What Is the Purpose of the `.claude-plugin` Directory in Claude Plugins?

> Discover the purpose of the .claude-plugin directory. Learn how this hidden folder stores manifest and metadata for Claude to load and validate plugins.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: deep-dive
- Published: 2026-09-06

---

**The `.claude-plugin` directory is a hidden configuration folder that stores the manifest and metadata files Claude uses to discover, validate, and load plugins.**

Every plugin in the [anthropics/claude-plugins-community](https://github.com/anthropics/claude-plugins-community) repository must include this directory at its root. It serves as the **authoritative source** for plugin configuration, enabling both local CLI operations and marketplace publishing workflows.

## Core Files Inside `.claude-plugin`

The `.claude-plugin` directory contains one required file and several optional assets that together define how Claude interacts with the plugin.

### [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json): The Primary Manifest

**[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** is the mandatory manifest file that describes the plugin's identity and capabilities. Claude's CLI and marketplace systems read this file to determine:

- Plugin name and version
- Entry points: **skills**, **agents**, **commands**, and **hooks**
- Required **MCP servers** (Model Context Protocol)

The validation script at [`validate-plugins/scripts/40-validate-cli-local.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins/scripts/40-validate-cli-local.sh) explicitly checks for this file's existence:

```bash

# From 40-validate-cli-local.sh

if [[ -f "$target/.claude-plugin/plugin.json" ]]; then
  printf '%s' "$target/.claude-plugin/plugin.json"
fi

```

A minimal valid [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) follows this structure:

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "skills": ["my-skill"],
  "agents": [],
  "commands": [],
  "mcpServers": {}
}

```

### [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json): Repository-Wide Index

When a repository contains multiple plugins—as the community repository does—[`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) at the repository root acts as a **central registry**. It enumerates each plugin's manifest path and provides additional marketplace metadata such as descriptions and icons.

According to the community repository's own [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), entries reference individual plugin manifests using paths like:

```json
{
  "plugins": [
    {
      "name": "example-plugin",
      "manifestPath": "plugins/example/.claude-plugin/plugin.json"
    }
  ]
}

```

The GitHub Actions workflow in [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) references this file directly:

```yaml

# From validate-plugins.yml

- name: Validate marketplace
  run: |
    # Validates .claude-plugin/marketplace.json structure

```

### Optional Assets

Plugin authors may include additional files inside `.claude-plugin/`:

| File | Purpose |
|------|---------|
| `icon.svg` | Visual icon displayed in marketplace listings |
| [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md) | Plugin-specific documentation (rarely used) |
| Custom resources | Any assets referenced by the manifest |

## How Claude Uses `.claude-plugin` During Installation

The `.claude-plugin` directory is integral to Claude's plugin lifecycle. When you execute installation commands, the CLI follows this discovery chain:

```bash

# Add the community marketplace as a source

claude plugin marketplace add anthropics/claude-plugins-community

# Reads: .claude-plugin/marketplace.json

# Install a specific plugin

claude plugin install my-plugin@claude-community

# Reads: my-plugin/.claude-plugin/plugin.json

```

Without the `.claude-plugin` directory and its [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest, Claude cannot identify or load the plugin.

## CI Validation and Security

The community repository enforces strict validation of `.claude-plugin` contents through automated scripts. The change detection script at [`validate-plugins/scripts/00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins/scripts/00-detect-changes.sh) scans for manifest files across the repository:

```bash

# From 00-detect-changes.sh (lines 110-118)

find . -type f -path '*/.claude-plugin/plugin.json' | while read -r manifest; do
  plugin_dir=$(dirname "$(dirname "$manifest")")
  # Security and structural validation follows

done

```

This scanning ensures:

1. Every plugin provides a valid [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)
2. Manifest syntax conforms to the expected schema
3. No unauthorized modifications bypass review

## Directory Structure Convention

A properly structured plugin repository follows this pattern:

```

my-claude-plugin/
├── .claude-plugin/
│   ├── plugin.json          # Required: manifest

│   └── icon.svg             # Optional: marketplace icon

├── src/                     # Source code implementation

├── tests/
├── README.md
└── LICENSE

```

The hidden `.claude-plugin` directory convention keeps configuration metadata separate from implementation code, making the plugin structure **clean and tooling-friendly**.

## Summary

- The `.claude-plugin` directory is the **mandatory configuration hub** for every Claude plugin
- **[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** defines the plugin's identity, version, and entry points—this file is required
- **[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** at repository root indexes multiple plugins for community distribution
- CI pipelines in `validate-plugins/scripts/` explicitly scan for [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) to enforce validation
- Optional assets like `icon.svg` enhance marketplace presentation
- Claude's CLI relies entirely on this directory to discover and load plugins

## Frequently Asked Questions

### What happens if my plugin is missing the `.claude-plugin` directory?

Claude will fail to recognize or install the plugin. The CLI installation command will return an error indicating no valid manifest was found, and the plugin will be excluded from marketplace listings.

### Can I rename `.claude-plugin` to something else?

No. The directory name is **hardcoded** in Claude's tooling. The validation scripts in `anthropics/claude-plugins-community` specifically search for paths matching `*/.claude-plugin/plugin.json`—any other name will cause validation and installation failures.

### Does `.claude-plugin` support subdirectories for organization?

The standard convention places files directly inside `.claude-plugin/`. While subdirectories for assets are technically possible, CI scripts expect [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) at the root of this directory. Keep the structure flat unless you verify compatibility with current validation tools.

### Is [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) required for single-plugin repositories?

No. **[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** is only needed when a repository contains multiple plugins that should appear as separate listings. Single-plugin repositories only require [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) at the plugin root.