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

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 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 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>).

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

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

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

Optional Metadata Fields

Beyond the required triad, the 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:

{
  "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 in the repository root
2. .claude-plugin/plugin.json in a subdirectory

The validation workflow, implemented in .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 containing only the name field, as demonstrated in the test suite at .github/actions/validate-plugins/test-external-manifest.sh.

Complete plugin.json Examples

Minimal Valid Manifest

The simplest valid plugin.json requires only the three mandatory fields:

{
  "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 demonstrates comprehensive metadata:

{
  "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 or .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 in the repository root or .claude-plugin/plugin.json within a subdirectory. The CI validation scripts in .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 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.

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