# Claude plugin.json Schema Guide: Required Fields and File Structure

> Learn the Claude plugin.json schema and required fields. Explore essential elements like name, version, and description, plus optional commands, skills, and advanced integrations.

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

---

**The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest requires `name`, `version`, and `description` fields at minimum, while supporting optional arrays for `commands`, `skills`, `agents`, and `hooks`, plus `mcpServers` and `userConfig` objects for advanced integrations.**

The **anthropics/claude-plugins-community** repository relies on a standardized **plugin.json** schema to register and validate community-built Claude plugins. This Zod-validated manifest file—located at either [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) or [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)—defines everything from plugin metadata to external MCP server configurations.

## What is plugin.json?

The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file serves as the canonical manifest for every plugin in the **claude-plugins-community** ecosystem. It describes the plugin's identity, available commands, skill definitions, agent configurations, and optional external service connections. The marketplace's validation workflow, implemented in the repository's GitHub Actions, parses this file to ensure conformance before listing.

## Required Fields in the plugin.json Schema

### Core Required Fields

Three fields are mandatory for every plugin submission:

- **`name`** (string): A human-readable identifier unique within the marketplace (e.g., `quickdesign`).
- **`version`** (string): Semantic version following semver format (e.g., `1.2.3`).
- **`description`** (string): Concise summary displayed in marketplace listings.

In `strict: false` mode (skills-only plugins), the Zod validator synthesizes a minimal schema containing only the `name` field, though providing the full trio is recommended for clarity.

### Command, Skill, and Agent Arrays

While optional at the top level, these arrays require specific sub-fields when present:

- **`commands`**: Array of objects, each requiring `name` and `description` properties. Powers CLI and Claude UI exposure.
- **`skills`**: Array of objects with `name` and `description`. Enables "skills-only" mode functionality.
- **`agents`**: Array of objects with `name` and `description`. Defines custom Claude agents for specialized tasks.

### Lifecycle Hooks and MCP Integration

Extended functionality requires additional optional objects:

- **`hooks`**: Array defining lifecycle hooks (e.g., `post-run`) with `name`, `type` (`local` or `remote`), and `script` or `url` properties.
- **`mcpServers`**: Object mapping server names to MCP endpoint configurations, including `url` and authentication methods. Required only when integrating external Model Context Protocol services.

### User Configuration Schema

The **`userConfig`** field accepts an object defining typed configuration values that users must provide during installation. Each key maps to an object specifying `type` (e.g., `string`, `number`) and `description`, enabling safe, validated inputs through the marketplace interface.

## Schema Validation and Source Files

The authoritative **Zod schema** definition resides in the repository's validation action documentation at [`/.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main//.github/actions/validate-plugins/README.md). This file specifies type constraints, required relationships between fields, and validation rules for the marketplace submission process.

The manifest resolver script located at [`/.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main//.github/actions/validate-plugins/lib/common.sh) handles runtime discovery, checking for [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) in the root directory or within the `.claude-plugin/` subdirectory. This utility ensures consistent path resolution across local development and CI environments.

## Complete plugin.json Examples

### Minimal Valid Configuration

```json
{
  "name": "my-awesome-plugin",
  "version": "0.1.0",
  "description": "A tiny example plugin that demonstrates the required fields."
}

```

This minimal structure satisfies the validator for standard submissions. For `strict: false` skills-only plugins, the marketplace can auto-generate this skeleton if omitted.

### Full-Featured Production Example

```json
{
  "name": "quickdesign",
  "version": "1.4.2",
  "description": "Design-first AI assistant for video creation.",
  "commands": [
    {
      "name": "quickdesign:generate",
      "description": "Generate a storyboard from a prompt."
    }
  ],
  "skills": [
    {
      "name": "quickdesign:storyboarding",
      "description": "Break a concept into scenes."
    }
  ],
  "agents": [
    {
      "name": "quickdesign:assistant",
      "description": "Conversational agent that guides the user."
    }
  ],
  "hooks": [
    {
      "name": "post-run",
      "type": "local",
      "script": "scripts/post-run.sh"
    }
  ],
  "mcpServers": {
    "quickdesign-api": {
      "url": "https://api.quickdesign.example.com",
      "auth": "bearer"
    }
  },
  "userConfig": {
    "apiKey": {
      "type": "string",
      "description": "Your QuickDesign API key."
    }
  }
}

```

This example mirrors the structure found in [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json) within the community repository, demonstrating proper nesting of all optional schema extensions.

## Summary

- **`name`, `version`, and `description`** are the only universally required top-level fields in the **plugin.json** schema.
- **Arrays** for `commands`, `skills`, and `agents` enable core functionality but require internal `name` and `description` fields when populated.
- **`mcpServers`** and **`userConfig`** support external integrations and typed user inputs, respectively.
- The **Zod validation schema** lives in [`/.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main//.github/actions/validate-plugins/README.md), while manifest resolution logic resides in [`/.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main//.github/actions/validate-plugins/lib/common.sh).
- Files must be named [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and placed either in the repository root or under `.claude-plugin/`.

## Frequently Asked Questions

### What happens if I omit the version field in plugin.json?

The Zod-based validator in the **anthropics/claude-plugins-community** repository will reject the submission. The `version` field is mandatory for all plugins and must follow semantic versioning format to enable marketplace upgrades and compatibility tracking.

### Can I use plugin.json without defining any commands?

Yes. The `commands` array is optional at the top level. However, if you include the array, each object inside must contain both `name` and `description` properties. For skills-only plugins, use `strict: false` mode or rely on the `skills` array instead.

### Where does the validation schema for plugin.json live?

The source of truth is documented in [`/.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main//.github/actions/validate-plugins/README.md) within the repository. This file contains the Zod schema definition that the marketplace's GitHub Actions workflow uses to validate every submission.

### What is the difference between hooks and commands in the schema?

**Commands** define user-invocable actions surfaced in the Claude UI, while **hooks** specify lifecycle scripts that execute automatically at defined points (like `post-run`). Hooks require a `type` field (`local` or `remote`) and either a `script` path or URL, whereas commands require only descriptive metadata.