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

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)

At the heart of the directory lies 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 over any top-level plugin.json file that might exist elsewhere in the repository, as demonstrated in the tres-finance-plugin example.

Marketplace Integration (marketplace.json)

The directory also contains 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 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, uses path patterns like:

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, 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 explicitly lists .claude-plugin/plugin.json as a supported surface file, distinguishing it from other configuration formats like .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:

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:

# 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 within this directory contains the authoritative plugin description, taking precedence over any root-level manifest files.
• 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 containing the manifest with fields like name, version, description, and author. Some plugins also include .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 at the repository root instead?

While a top-level plugin.json might be recognized by some tooling, the anthropics/claude-plugins-community source code explicitly prioritizes .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 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.

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