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

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 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: The Primary Manifest

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 explicitly checks for this file's existence:

# 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 follows this structure:

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

marketplace.json: Repository-Wide Index

When a repository contains multiple plugins—as the community repository does—.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, entries reference individual plugin manifests using paths like:

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

The GitHub Actions workflow in validate-plugins.yml references this file directly:

# 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	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:

# 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 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 scans for manifest files across the repository:

# 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
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 defines the plugin's identity, version, and entry points—this file is required
• marketplace.json at repository root indexes multiple plugins for community distribution
• CI pipelines in validate-plugins/scripts/ explicitly scan for .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 at the root of this directory. Keep the structure flat unless you verify compatibility with current validation tools.

Is marketplace.json required for single-plugin repositories?

No. 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 at the plugin root.

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