Required Fields for plugin.json in Claude Marketplace Submissions

The Claude Marketplace requires eight mandatory top-level fields in every 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 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, a minimal commands block looks like this:

"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. The workflow in .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:

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

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

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