# Required Fields for plugin.json in Claude Marketplace Submissions

> Discover the eight essential fields required for your plugin.json in the Claude Marketplace. Ensure a smooth submission process by understanding name, description, version, author, license, homepage, runtime, and commands.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-12

---

**The Claude Marketplace requires eight mandatory top-level fields in every [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest—`name`, `description`, `version`, `author`, `license`, `homepage`, `runtime`, and `commands`—plus specific sub-fields for each command entry.**

The `anthropics/claude-plugins-community` repository hosts the official validation tooling and reference implementations for Claude plugins. Before a plugin appears in the Marketplace, the automated validator checks that the manifest contains all required metadata and command definitions. Missing any mandatory field triggers a CI failure that blocks the submission.

## Mandatory Top-Level Fields

### Core Metadata Fields

Every [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) must include six identity fields that define the plugin's presence in the catalog.

- **`name`**: The unique identifier used as the namespace in commands (e.g., `/tres-finance-plugin:my-skill`). This value must be distinct across the Marketplace.
- **`description`**: A concise, human-readable summary displayed in the Marketplace catalog.
- **`version`**: A semantic version string following `MAJOR.MINOR.PATCH` format (e.g., `1.2.0`). This enables the Marketplace to track updates and compatibility.
- **`author`**: The individual or organization responsible for the plugin.
- **`license`**: An SPDX-compatible license identifier (e.g., `MIT`, `Apache-2.0`).
- **`homepage`** (or **`repository`**): A URL pointing to the source repository or project homepage (e.g., `https://github.com/anthropics/claude-plugins-community/tree/main/tres-finance-plugin`).

### Runtime Specification

The **`runtime`** field specifies which Claude model version the plugin targets. Valid values follow the model snapshot format, such as `claude-3-5-sonnet-20240620`. This ensures compatibility between the plugin's skills and the underlying model capabilities.

### Command Definitions

The **`commands`** array defines the top-level instructions users invoke. Each object in this array must contain three sub-fields:

- **`name`**: The command trigger (e.g., `upload-wallets`).
- **`description`**: Brief explanation of what the command does.
- **`skill`**: The internal skill file the command invokes (e.g., `tres-wallets-upload`).

As implemented in [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json), a minimal commands block looks like this:

```json
"commands": [
  {
    "name": "upload-wallets",
    "description": "Upload wallet data",
    "skill": "tres-wallets-upload"
  }
]

```

## Optional Fields and MCP Configuration

While not required for all submissions, the **`mcpServers`** object is necessary when the plugin relies on external Multi-Chat-Plugin (MCP) services. When omitted, the plugin is considered "skills-only." If included, it defines external server connections with properties like `command` and `url`.

## Validation and CI Enforcement

The repository enforces these requirements through the `validate-plugins` GitHub Action defined in [`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md). The workflow in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) automatically runs `claude plugin validate` on every pull request. If any required key is missing or malformed, the CI emits an error such as *"plugin.json missing required field `name`"* and prevents merging.

## Complete plugin.json Examples

### Minimal Valid Manifest

The following example satisfies all mandatory requirements for the Claude Marketplace:

```json
{
  "name": "my-awesome-plugin",
  "description": "A short description shown in the Claude Marketplace.",
  "version": "0.1.0",
  "author": "Jane Doe",
  "license": "MIT",
  "homepage": "https://github.com/your-org/awesome-plugin",
  "runtime": "claude-3-5-sonnet-20240620",
  "commands": [
    {
      "name": "run-task",
      "description": "Execute the main task of the plugin.",
      "skill": "my-task"
    }
  ]
}

```

### Extended Manifest with MCP Servers

For plugins requiring external services, include the optional `mcpServers` block:

```json
{
  "name": "data-collector",
  "description": "Collects external data for downstream skills.",
  "version": "1.0.0",
  "author": "Acme Corp",
  "license": "Apache-2.0",
  "homepage": "https://github.com/acme/data-collector",
  "runtime": "claude-3-5-sonnet-20240620",
  "commands": [
    {
      "name": "fetch-records",
      "description": "Pull records from a remote API.",
      "skill": "fetch-records"
    }
  ],
  "mcpServers": {
    "recordsApi": {
      "command": "records:fetch",
      "url": "https://api.example.com/v1"
    }
  }
}

```

## Summary

- **Eight required top-level fields**: `name`, `description`, `version`, `author`, `license`, `homepage`, `runtime`, and `commands`.
- **Commands array structure**: Each command requires `name`, `description`, and `skill` sub-fields.
- **Strict validation**: The CI workflow in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) rejects submissions missing any mandatory field.
- **Optional MCP support**: The `mcpServers` field is only required for plugins utilizing external services.

## Frequently Asked Questions

### What happens if a required field is missing from plugin.json?

The automated validator in `.github/actions/validate-plugins` will emit a specific error message identifying the missing field, and the pull request check will fail. The submission cannot be merged into the Marketplace until the manifest is corrected.

### Can I use `repository` instead of `homepage` in the manifest?

Yes. While the field is commonly named `homepage`, the validator accepts `repository` as an alternative key for providing the source code URL. Either field satisfies the requirement for a project link.

### Where must plugin.json be located in the repository?

The file must reside in the `.claude-plugin/` directory at the root of your plugin folder (e.g., [`your-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/your-plugin/.claude-plugin/plugin.json)). The CI workflow specifically searches this path during validation.

### Is the `mcpServers` field required for all Claude plugins?

No. The `mcpServers` object is only required for "strict:false" plugins that depend on external MCP services. Skills-only plugins can omit this field entirely, while plugins requiring external data sources must define their server connections here.