# Claude plugin.json Format: Complete Schema Guide for Claude Code Plugins

> Master the Claude plugin.json format with this complete schema guide. Define your plugin's metadata and runtime configuration using essential fields like name, version, and description.

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

---

**The Claude plugin.json format requires a JSON manifest with `name`, `version`, and `description` fields, optionally including `author`, `license`, `userConfig`, and `mcpServers` to define plugin metadata and runtime configuration.**

The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest serves as the entry point for every Claude plugin in the `anthropics/claude-plugins-community` repository. This file describes the plugin's identity, version, and capabilities while enabling the Claude Code CLI to validate, load, and execute plugin commands. Understanding the exact schema ensures your plugin passes automated validation and integrates seamlessly with the Claude marketplace.

## Required Fields in plugin.json

Every valid Claude plugin manifest must include three core fields. The validation logic in [`.github/actions/validate-plugins/scripts/30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/30-validate-cli-external.sh) enforces these requirements during CI checks.

### name

The `name` field provides a unique, URL-safe identifier for the plugin. This value becomes the command prefix when users invoke skills (e.g., `/<name>:<skill>`).

```json
{
  "name": "tres-finance-plugin"
}

```

### version

The `version` field follows semantic versioning (Semver) standards. The CLI validator checks that this string conforms to Semver compatibility rules.

```json
{
  "version": "1.12.1"
}

```

### description

The `description` field contains a human-readable summary of the plugin's purpose. This text appears in the Claude marketplace and helps users understand functionality at a glance.

```json
{
  "description": "The first official TRES Finance plugin for Claude Code..."
}

```

## Optional Metadata Fields

Beyond the required triad, the [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) format supports several optional fields that improve discoverability and provide attribution.

- **author**: An object containing `name`, `email`, and/or `url` identifying the creator
- **homepage**: URL pointing to documentation or the plugin's landing page
- **repository**: Source code URL used by the marketplace for attribution
- **license**: SPDX identifier (e.g., `"MIT"`, `"Apache-2.0"`)
- **keywords**: Array of tags for marketplace searchability (e.g., `["blockchain", "accounting"]`)
- **icon**: Relative path to an SVG file displayed in the Claude UI (e.g., `"./icon.svg"`)

## Runtime Configuration Schema

Claude plugins can declare runtime dependencies and user-configurable settings through specialized object fields.

### userConfig Schema

The `userConfig` field defines settings that end-users provide during installation. Each key maps to a configuration definition object specifying the data type and sensitivity.

**Configuration properties:**
- `title`: Human-readable label for the setting
- `description`: Help text explaining the parameter's purpose
- `type`: Data type (`string`, `number`, `boolean`, or `enum`)
- `sensitive`: Boolean flag indicating whether the value contains secrets (masks input when `true`)
- `enum`: Required when `type` is `"enum"`; specifies allowed values as an array

**Example from [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json):**

```json
{
  "userConfig": {
    "DEBANK_API_KEY": {
      "title": "DeBank API Key",
      "description": "Your DeBank Pro API key for balance validation (from https://cloud.debank.com)",
      "type": "string",
      "sensitive": true
    }
  }
}

```

### mcpServers

The `mcpServers` field describes hosted Model Context Protocol (MCP) server endpoints that the plugin can call at runtime. When present, the marketplace synthesizes connection details from this configuration. This enables plugins to communicate with external services through standardized MCP interfaces.

## File Location and Validation

The Claude Code CLI searches for the manifest in two locations:
1. [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) in the repository root
2. [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) in a subdirectory

The validation workflow, implemented in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh), locates the manifest and executes `claude plugin validate` to verify:
- Required fields are present and correctly typed
- No unknown top-level keys exist (strict validation mode)
- Semver compliance for the `version` field

For skills-only plugins without a manifest, the marketplace automatically synthesizes a minimal [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) containing only the `name` field, as demonstrated in the test suite at [`.github/actions/validate-plugins/test-external-manifest.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/test-external-manifest.sh).

## Complete plugin.json Examples

### Minimal Valid Manifest

The simplest valid [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) requires only the three mandatory fields:

```json
{
  "name": "my-awesome-plugin",
  "version": "0.1.0",
  "description": "A simple example plugin for Claude Code."
}

```

### Full-Featured Manifest

This example from [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json) demonstrates comprehensive metadata:

```json
{
  "name": "quickdesign",
  "version": "0.8.0",
  "description": "AI media generation skill for the QuickDesign CLI...",
  "icon": "./icon.svg",
  "author": {
    "name": "QuickDesign",
    "url": "https://quickdesign.io"
  },
  "homepage": "https://github.com/ottasilver/quickdesign-cli",
  "repository": "https://github.com/ottasilver/quickdesign-cli",
  "license": "MIT",
  "keywords": [
    "ai",
    "video-generation",
    "image-generation",
    "ugc"
  ]
}

```

## Summary

- The **Claude plugin.json format** requires three mandatory fields: `name` (URL-safe identifier), `version` (Semver string), and `description` (human-readable summary).
- Optional metadata fields include `author`, `license`, `keywords`, and `icon` to enhance marketplace discoverability.
- The `userConfig` object defines user-provided settings with type safety and sensitivity controls for API keys and secrets.
- The `mcpServers` field enables runtime communication with external MCP-compatible services.
- Validation occurs automatically via CI scripts in `anthropics/claude-plugins-community`, checking file locations ([`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) or [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)) and schema compliance.

## Frequently Asked Questions

### Where should I place the plugin.json file in my repository?

Claude Code searches for the manifest in two locations: either [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) in the repository root or [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) within a subdirectory. The CI validation scripts in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh) check both paths during automated testing.

### What happens if I don't include a plugin.json file?

If you omit the manifest, the Claude marketplace automatically synthesizes a minimal [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) containing only the `name` field extracted from the repository context. However, this synthesized version lacks `description`, `version`, and configuration options, limiting functionality and discoverability.

### How do I protect sensitive configuration values like API keys?

Set the `sensitive` property to `true` within the `userConfig` schema definition for that specific key. When users configure your plugin, Claude Code masks input for sensitive fields, preventing accidental exposure of credentials in logs or UI displays.

### Can I use any license identifier in the license field?

You should use valid SPDX license identifiers (e.g., `"MIT"`, `"Apache-2.0"`, `"BSD-3-Clause"`). While the validator may accept arbitrary strings, the marketplace displays standard SPDX identifiers correctly and links to official license texts for user reference.