# Plugin Manifest Format for Claude Plugins: Schema, Validation, and Examples

> Explore the Claude plugin manifest format, a JSON schema defining metadata and configuration. Learn about validation and see examples to build your own Claude plugins.

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

---

**The Claude plugin manifest format is a JSON schema defined in either [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) or [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) that specifies metadata, user configuration options, and MCP server connections, validated by the Claude CLI using the `resolve_external_manifest()` function in the community validation toolkit.**

Claude plugins published to the marketplace require a structured metadata file that defines capabilities, authorship, and runtime configuration. In the `anthropics/claude-plugins-community` repository, this **plugin manifest format** follows a strict JSON schema enforced by the `validate-plugins` GitHub Action and the Claude CLI validation tool.

## Core Manifest Schema and Required Fields

Every **plugin manifest** must include four fundamental fields that establish the plugin's identity and versioning:

- **`name`** – A unique string identifier that serves as the command namespace for the plugin.
- **`description`** – A human-readable summary displayed in the marketplace.
- **`version`** – A semantic version string following the `MAJOR.MINOR.PATCH` format.
- **`author`** – An object containing `"name"` and `"email"` strings that identifies the maintainer.

These fields form the minimal valid manifest that the Claude marketplace will accept. According to the validation logic in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh), the `resolve_external_manifest()` function checks for these required keys before allowing publication.

## Optional Fields and Configuration Options

Beyond the core schema, the manifest supports several optional fields that enhance discoverability and functionality:

- **`homepage`** – URL string pointing to documentation or the plugin's website.
- **`repository`** – Source code location, typically a GitHub URL.
- **`license`** – SPDX license identifier (e.g., `"MIT"`, `"Apache-2.0"`).
- **`keywords`** – Array of strings used as tags for marketplace search and filtering.

### User Configuration with `userConfig`

The **`userConfig`** object declares configuration values that end-users set during installation. Each key defines a specific setting with the following structure:

```json
{
  "CONFIG_KEY_NAME": {
    "title": "Human-readable label",
    "description": "Detailed explanation of the setting",
    "type": "string",
    "sensitive": true
  }
}

```

The **`sensitive`** boolean flag determines whether the value appears in logs. When set to `true`, the Claude CLI masks the value in output, protecting API keys and secrets.

### MCP Server Declarations with `mcpServers`

The **`mcpServers`** object describes Model Context Protocol server connections required by the plugin. This field enables the marketplace loader to provision necessary infrastructure:

```json
{
  "mcpServers": {
    "prod": {
      "url": "https://mcp.mycompany.com",
      "auth": {
        "type": "token",
        "envVar": "MCP_TOKEN"
      }
    }
  }
}

```

## Manifest Location and Discovery

The validation system searches for the manifest in two specific locations, checking them in order:

1. [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)
2. [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) (repository root)

As implemented in `anthropics/claude-plugins-community`, the `resolve_external_manifest()` function in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh) implements this lookup logic (lines 152–166 of the script). If neither file exists and the plugin operates under `strict:false` mode (skills-only plugins), the function synthesizes a minimal manifest containing only the `name` field.

This synthesis behavior mirrors the runtime behavior of the Claude marketplace, ensuring that every plugin has a valid manifest for validation purposes. The test suite in [`.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) (lines 66–68) verifies this fallback mechanism.

## Validation Workflow and CLI Integration

The **plugin manifest format** undergoes a three-stage validation process before marketplace acceptance:

1. **Detection** – The `validate-plugins` GitHub Action scans the repository for [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) first, falling back to [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) at the root.

2. **Synthesis** – For entries marked `strict:false` without a manifest, the action creates a minimal JSON file containing only the required `name` field via `resolve_external_manifest()`.

3. **Schema Validation** – The CLI command `claude plugin validate <manifest-path>` verifies that the JSON conforms to the schema, checking for unknown keys, missing required fields, and type mismatches.

You can run this validation locally before submission:

```bash

# Validate from the .claude-plugin directory

claude plugin validate .claude-plugin/plugin.json

# Or validate a root-level manifest

claude plugin validate plugin.json

```

The CLI outputs either a success message or a detailed list of schema violations, including invalid field types or prohibited top-level keys.

## Complete Manifest Example: Tres Finance Plugin

The following example from the `tres-finance-plugin` in the community repository demonstrates a production-ready manifest with all optional fields populated:

```json
{
  "name": "tres-finance-plugin",
  "description": "The first official TRES Finance plugin for Claude Code — blockchain accounting workflows, ledger management, and transaction analysis. Connects to the hosted TRES Finance MCP server; collects no usage telemetry.",
  "version": "1.12.1",
  "author": {
    "name": "Nadav Gilliam",
    "email": "nadav@tres.finance"
  },
  "homepage": "https://tres.finance",
  "repository": "https://github.com/Tres-Finance-Public/tres-claude-plugin",
  "license": "MIT",
  "keywords": [
    "tres-finance",
    "blockchain",
    "accounting",
    "ledger",
    "crypto"
  ],
  "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
    }
  }
}

```

This manifest leverages the [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) path and includes sensitive configuration handling for API credentials.

## Summary

- The **plugin manifest format for Claude plugins** requires a JSON file at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) or [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) containing at minimum `name`, `description`, `version`, and `author` fields.
- The `userConfig` object enables secure collection of user-specific settings, with the `sensitive` flag protecting credentials from log exposure.
- The `mcpServers` field declares required Model Context Protocol connections for marketplace provisioning.
- Validation occurs through the `validate-plugins` GitHub Action, which uses `resolve_external_manifest()` in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh) to locate or synthesize manifests.
- Run `claude plugin validate <path>` locally to verify schema compliance before submitting to the community repository.

## Frequently Asked Questions

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

Place your manifest in either [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) (preferred) or [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) at the repository root. The validation system checks the `.claude-plugin/` directory first, as defined in the `resolve_external_manifest()` function within [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh).

### What happens if I don't include a manifest file?

If you submit a skills-only plugin without a manifest under `strict:false` mode, the marketplace validation synthesizes a minimal manifest containing only the `name` field. However, you should provide a full manifest to maximize discoverability and enable user configuration features.

### How do I validate my plugin manifest locally?

Use the Claude CLI command `claude plugin validate` followed by the path to your manifest file. For example: `claude plugin validate .claude-plugin/plugin.json`. The CLI will report schema violations such as missing required fields, incorrect types, or unknown keys.

### What is the purpose of the `sensitive` flag in `userConfig`?

The **`sensitive`** boolean in `userConfig` entries marks values that should be hidden from logs and CLI output. Set this to `true` for API keys, tokens, and passwords to prevent accidental exposure during plugin operation or debugging sessions.