Understanding the plugin.json Schema for Claude Plugins: A Complete Reference

The plugin.json schema for Claude plugins requires a strict JSON manifest file located in a hidden .claude-plugin directory that defines the plugin's metadata, entrypoint, and command signatures using JSON Schema definitions for parameters and outputs.

Every Claude plugin in the anthropics/claude-plugins-community repository must include a valid plugin.json manifest file following this schema. The Claude platform validates this file through automated CI checks before any plugin can be published or invoked, ensuring consistency and type safety across the plugin ecosystem.

Core Structure of the plugin.json Schema

The manifest file resides at .claude-plugin/plugin.json in the plugin's root directory. It supports ten top-level properties, with eight being strictly required for validation.

Required Fields

Every plugin.json must include these mandatory properties:

• name – A unique identifier in kebab-case format (e.g., tres-finance-plugin). This name becomes the CLI invocation prefix (/tres-finance-plugin:command).

• description – Human-readable summary of the plugin's capabilities displayed in the marketplace and Claude's UI.

• version – Valid SemVer string (e.g., 1.2.3) following semantic versioning specifications.

• author – Object containing author metadata with typical fields: name, email, and url.

• license – Valid SPDX identifier (e.g., MIT, Apache-2.0) specifying the software license.

• entrypoint – Relative path to the executable script (commonly cli.js, main.py, or similar) that Claude invokes to run the plugin.

• type – Enumeration string accepting either cli for command-line tools or agent for Claude-agent integrations.

• commands – Array of command objects defining callable operations. The schema requires at least one command per plugin.

• manifest_version – Fixed string value of "1" indicating the internal format version of the manifest specification.

Optional Fields

The schema also supports these optional configuration properties:

• runtime – Object specifying environment requirements (e.g., node: >=14, python: >=3.9) or Docker image references.

• environment – Key-value mapping of environment variable names to default values or placeholders for user-configured secrets.

• dependencies – Array of external package names (e.g., axios, openai) validated for licensing compatibility.

• metadata – Free-form object for additional author-defined information such as tags, repository, or homepage URLs.

Defining Commands with JSON Schema

The commands array forms the core interface between Claude and your plugin. Each command object requires four specific properties:

name – Kebab-case identifier for the subcommand (e.g., get-balance, send-report).

description – Short explanation displayed in command palettes and help text.

parameters – Valid JSON Schema object describing input arguments. This must specify type, properties, and required fields to enable Claude's type checking and auto-completion.

output – JSON Schema object defining the return value structure, allowing Claude to parse and present results correctly.

{
  "commands": [
    {
      "name": "hello",
      "description": "Returns a greeting for the supplied name.",
      "parameters": {
        "type": "object",
        "properties": {
          "name": { 
            "type": "string", 
            "description": "Name of the person to greet" 
          }
        },
        "required": ["name"]
      },
      "output": {
        "type": "object",
        "properties": {
          "greeting": { 
            "type": "string", 
            "description": "The generated greeting" 
          }
        },
        "required": ["greeting"]
      }
    }
  ]
}

CI Validation and Schema Enforcement

The anthropics/claude-plugins-community repository enforces schema compliance through automated validation. The CI pipeline executes the validate-plugins GitHub Action, which runs the Bash script located at .github/actions/validate-plugins/scripts/41-validate-aux-files.sh.

This validator performs strict checks on every pull request:

• Presence verification – Confirms all required fields (name, description, version, author, entrypoint, commands, type, manifest_version) exist.
• Type validation – Ensures version matches SemVer regex patterns and license contains valid SPDX identifiers.
• Schema integrity – Validates that parameters and output objects conform to proper JSON Schema specifications.
• Command requirements – Verifies at least one command exists in the commands array.

If validation fails, the CI job aborts immediately, preventing malformed plugins from reaching the marketplace.

Complete Minimal Example

Below is a fully-compliant plugin.json for a simple CLI plugin providing a single greeting command:

{
  "name": "hello-plugin",
  "description": "A tiny plugin that returns a friendly greeting.",
  "version": "1.0.0",
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "url": "https://github.com/janedoe"
  },
  "license": "MIT",
  "entrypoint": "cli.js",
  "type": "cli",
  "manifest_version": "1",
  "commands": [
    {
      "name": "hello",
      "description": "Returns a greeting for the supplied name.",
      "parameters": {
        "type": "object",
        "properties": {
          "name": { 
            "type": "string", 
            "description": "Name of the person to greet" 
          }
        },
        "required": ["name"]
      },
      "output": {
        "type": "object",
        "properties": {
          "greeting": { 
            "type": "string", 
            "description": "The generated greeting" 
          }
        },
        "required": ["greeting"]
      }
    }
  ]
}

For complex implementations, examine the tres-finance-plugin manifest at tres-finance-plugin/.claude-plugin/plugin.json, which demonstrates multiple commands, runtime specifications, and environment variable configurations.

Summary

• Location: Every Claude plugin requires a .claude-plugin/plugin.json manifest file in the repository root.
• Schema: The file must include nine required fields including name (kebab-case), version (SemVer), entrypoint, type (cli or agent), and a commands array with at least one command.
• Type Safety: Command definitions require JSON Schema objects for both parameters and output to enable Claude's argument validation and response parsing.
• Validation: The 41-validate-aux-files.sh script enforces schema compliance in the CI pipeline, checking SPDX licenses, SemVer formats, and required field presence.
• Examples: Reference implementations exist in testdino/.claude-plugin/plugin.json (minimal) and tres-finance-plugin/.claude-plugin/plugin.json (complex).

Frequently Asked Questions

What license identifiers are valid for the plugin.json schema?

The schema accepts any valid SPDX license identifier (e.g., MIT, Apache-2.0, BSD-3-Clause). The CI pipeline validates these strings against the SPDX specification during the 41-validate-aux-files.sh check. Using custom license strings or omitting the field will cause validation to fail.

Can I create a Claude plugin without defining any commands?

No. The schema requires at least one command object in the commands array. Each command must specify name, description, parameters, and output properties using valid JSON Schema definitions. Plugins without callable operations cannot pass the automated CI validation in anthropics/claude-plugins-community.

Where does the plugin.json file need to be located?

The manifest must reside in a hidden directory named .claude-plugin at your plugin's root level, specifically at .claude-plugin/plugin.json. The validation scripts search for this exact path pattern. While some legacy implementations used a global repository manifest, current plugins require this subdirectory structure.

What is the difference between the cli and agent types in plugin.json?

The type field accepts two values: cli for traditional command-line tools that execute scripts and return output, and agent for plugins that integrate directly with Claude's agent architecture for multi-turn conversations. The type determines how Claude invokes the entrypoint and handles response streaming.

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