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

> Master the plugin.json schema for Claude plugins. Learn how to define your plugin's metadata, entrypoint, and command signatures with this complete reference guide.

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

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/cli.js), [`main.py`](https://github.com/anthropics/claude-plugins-community/blob/main/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.

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) for a simple CLI plugin providing a single greeting command:

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/plugin.json) (minimal) and [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.