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

> Discover the purpose of the .claude-plugin directory. Learn how it holds manifest and metadata for Claude plugins, aiding validation and marketplace publishing. Isolate and port plugin configurations easily.

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

---

**The `.claude-plugin` directory serves as the canonical location for a Claude plugin's manifest and metadata, enabling validation, marketplace publishing, and runtime discovery while keeping plugin configuration isolated and portable.**

The `.claude-plugin` directory is the standardized entry point that identifies a repository as a Claude plugin project within the `anthropics/claude-plugins-community` ecosystem. Understanding the purpose of the `.claude-plugin` directory is essential for developers contributing to the community marketplace, as it determines how tooling discovers, validates, and distributes plugin functionality. This hidden directory encapsulates everything from manifest definitions to automated publishing configurations.

## Core Purpose and Structure

The `.claude-plugin` directory functions as the authoritative source of truth for plugin metadata, separating configuration from implementation code.

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

At the heart of the directory lies [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json), the primary manifest that describes the plugin's identity and capabilities. According to the `anthropics/claude-plugins-community` source code, this file defines critical metadata including the plugin name, description, version, author, licensing information, keywords, and any user-configurable parameters. The CLI and CI workflows prioritize this location, giving precedence to [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) over any top-level [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file that might exist elsewhere in the repository, as demonstrated in the `tres-finance-plugin` example.

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

The directory also contains [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json), a generated entry that the community marketplace consumes for plugin discovery and installation. This file exists at the repository root within [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) and provides the read-only mirror with structured data required to list the plugin in the community catalog. When a plugin is published, this file ensures that marketplace consumers can discover and install the extension without accessing the full source code.

## CI/CD Validation and Publishing

The presence of a `.claude-plugin` directory signals to automated systems that the repository contains a first-class Claude plugin requiring specialized processing.

### Automated Detection in GitHub Actions

GitHub Actions workflows such as **Validate-Plugins** and **Scan-Plugins** specifically scan for `*/.claude-plugin/plugin.json` to identify which directories contain valid plugin configurations. The detection logic, implemented in [`.github/actions/validate-plugins/scripts/00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/00-detect-changes.sh), uses path patterns like:

```bash
find . -mindepth 2 -path '*/.claude-plugin/plugin.json' -not -path './.git/*'

```

This pattern ensures that only actual plugin directories trigger validation processes, excluding the repository's `.git` metadata and other non-plugin paths.

### Validation Workflows

Once detected, the validation workflow verifies the manifest structure and enforces invariants such as required field presence and version formatting. The workflow can also synthesize a temporary manifest during PR checks to validate proposed changes before merging. The validation logic is documented in [`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md), which specifies that the `.claude-plugin` directory structure is mandatory for marketplace eligibility. Additionally, the policy defined in [`.github/actions/scan-plugins/policy/prompt.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/scan-plugins/policy/prompt.md) explicitly lists [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) as a supported surface file, distinguishing it from other configuration formats like [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json).

## Design Benefits: Isolation and Portability

Housing metadata within a dedicated hidden folder provides architectural advantages beyond simple organization. Keeping the manifest inside `.claude-plugin` avoids accidental clashes with other project files and makes the plugin portable—developers can copy the entire folder into a new repository, and the plugin will still be recognized by Claude's tooling without additional configuration. This isolation ensures that plugin metadata remains distinct from application code, third-party configurations, and documentation files that might populate the repository root.

## Loading Plugin Manifests Programmatically

Developers can interact with `.claude-plugin` directories programmatically to extract metadata. The following Python example demonstrates loading a manifest from the `testdino` plugin:

```python
import json, pathlib

# Load a plugin's manifest from its .claude-plugin directory

def load_manifest(plugin_root: str) -> dict:
    manifest_path = pathlib.Path(plugin_root) / ".claude-plugin" / "plugin.json"
    with manifest_path.open() as f:
        return json.load(f)

# Example usage with the testdino plugin

manifest = load_manifest("testdino")
print(f"Plugin {manifest['name']} v{manifest['version']}")

# → Plugin testdino v1.0.0

```

For CI pipelines or shell scripts, extracting specific marketplace data can be accomplished using standard Unix tools:

```bash

# Publishing the plugin to the marketplace uses the generated entry:

cat .claude-plugin/marketplace.json | jq '.[] | select(.name=="testdino")'

```

## Summary

- **The `.claude-plugin` directory** acts as the canonical location for Claude plugin manifests and metadata, recognized by both CLI tools and automated workflows.
- **[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** within this directory contains the authoritative plugin description, taking precedence over any root-level manifest files.
- **[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** enables community discovery by providing structured data to the read-only marketplace mirror.
- **CI/CD integration** relies on this directory structure; GitHub Actions scan for `*/.claude-plugin/plugin.json` to trigger validation, enforce invariants, and handle publishing workflows.
- **Portability design** ensures plugins can be moved between repositories while maintaining their identity and configuration integrity.

## Frequently Asked Questions

### What files must exist inside `.claude-plugin`?

At minimum, a valid Claude plugin requires [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) containing the manifest with fields like name, version, description, and author. Some plugins also include [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) if they are published to the community marketplace, though this is often generated during the publishing workflow rather than maintained manually.

### Can I place [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) at the repository root instead?

While a top-level [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) might be recognized by some tooling, the `anthropics/claude-plugins-community` source code explicitly prioritizes [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json). The CLI and validation workflows look for the manifest within the hidden directory first, making the root-level file a secondary or legacy option that may not trigger automated validation.

### How does the CI system detect plugin changes?

The validation system uses the shell script located at [`.github/actions/validate-plugins/scripts/00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/00-detect-changes.sh) to scan for modifications to `*/.claude-plugin/plugin.json` paths. This detection mechanism ensures that only plugin-related changes trigger the Validate-Plugins and Scan-Plugins workflows, optimizing CI resources and ensuring relevant tests run for pull requests.

### Is the `.claude-plugin` directory required for all Claude plugins?

For plugins intended for the `anthropics/claude-plugins-community` repository and marketplace, yes—the directory is mandatory. It signals to the community infrastructure that the repository contains a first-class Claude plugin. For private or internal plugins, adherence to this convention ensures compatibility with future tooling and potential migration paths to the community marketplace.