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

The Claude plugin manifest format is a JSON schema defined in either .claude-plugin/plugin.json or 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, 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:

{
  "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:

{
  "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
2. plugin.json (repository root)

As implemented in anthropics/claude-plugins-community, the resolve_external_manifest() function in .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 (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 first, falling back to 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:

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

{
  "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 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 or 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 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 (preferred) or 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.

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.

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