# Claude Plugin.json Schema: Required Fields and Validation Rules Explained

> Understand the Claude plugin.json schema Learn required fields like name, version, and description and explore validation rules. Ensure your plugin meets all criteria for successful integration.

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

---

**The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) schema for Claude plugins requires nine mandatory fields (`name`, `version`, `description`, `icon`, `author`, `homepage`, `repository`, `license`, `keywords`) and validates against a JSON Schema stored at [`.github/actions/validate-plugins/policy/schema.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/policy/schema.json).**

The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file serves as the manifest for every Claude plugin in the **anthropics/claude-plugins-community** repository. This single file determines whether Claude can discover, render, and execute your plugin correctly. All submissions are automatically validated through the `validate-plugins` GitHub Action, which rejects any file that deviates from the schema's strict type and format requirements.

## Required Fields in the Plugin.json Schema

Every [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) must include these nine fields. Omitting any causes the validation workflow to fail.

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Human-readable identifier displayed in the Claude UI |
| `version` | string | Semantic version (e.g., `1.0.0`, `0.8.0-beta`) |
| `description` | string | Short summary appearing in the marketplace listing |
| `icon` | string | Relative path from plugin root to an SVG or PNG file |
| `author` | object | Must contain `name` (string); optionally `url` (string URL) |
| `homepage` | string (URL) | Landing page or documentation URL |
| `repository` | string (URL) | Source code repository URL |
| `license` | string | SPDX-compatible identifier (e.g., `MIT`, `Apache-2.0`) |
| `keywords` | array of strings | Discovery tags for marketplace search |

The schema enforces **type safety** for each field and **URL validation** for `homepage` and `repository`. Malformed URLs trigger immediate CI failures.

## Optional Fields in the Plugin.json Schema

Two fields extend the manifest for advanced use cases:

| Field | Type | Purpose |
|-------|------|---------|
| `manifest_version` | string | Format version of the schema; currently `1` |
| `api` | object | Describes additional endpoints for complex plugins |

These remain backward-compatible. Existing plugins without them continue to validate successfully.

## Complete Plugin.json Example

Below is the **quickdesign** plugin's [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json), a fully-compliant implementation located at [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json):

```json
{
  "name": "quickdesign",
  "version": "0.8.0",
  "description": "AI media generation skill for the QuickDesign CLI. Seedance 2.0 R2V (universal default for UGC / talking-avatar / promo), Sora 2, Kling, Nano Banana 2 (multi-ref image edit), video upscale. Multi-segment voice continuity, multi-product reference composition, anatomy self-check, model-agnostic concepts + per-model reference cards.",
  "icon": "./icon.svg",
  "author": {
    "name": "QuickDesign",
    "url": "https://quickdesign.io"
  },
  "homepage": "https://github.com/ottasilver/quickdesign-cli",
  "repository": "https://github.com/ottasilver/quickdesign-cli",
  "license": "MIT",
  "keywords": [
    "ai",
    "video-generation",
    "image-generation",
    "ugc",
    "seedance",
    "sora",
    "kling",
    "nano-banana"
  ]
}

```

The `author` object structure follows the nested schema exactly: `name` is required, `url` is optional. All URL fields use absolute HTTPS paths.

## Schema Validation and CI Enforcement

The **anthropics/claude-plugins-community** repository validates every [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) through automated checks.

### Validation Workflow Location

The GitHub Action definition resides in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml). This workflow triggers on every push and pull request, scanning all plugin directories for schema compliance.

### JSON Schema Source

The authoritative schema lives at [`.github/actions/validate-plugins/policy/schema.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/policy/schema.json). This file defines:

- Type constraints for each field
- Regular expressions for URL validation
- Required field arrays
- Nested object structures (e.g., the `author` object)

### Validation Behavior

Any deviation from the schema causes the `validate-plugins` action to fail with specific error messages indicating:

- Missing required fields
- Type mismatches (e.g., `keywords` as string instead of array)
- Malformed URLs
- Invalid SPDX license identifiers

## File Structure Convention

Every plugin must place [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) in a `.claude-plugin/` subdirectory. The repository contains multiple reference implementations:

- [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json) — media generation plugin with extensive keywords
- [`testdino/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/plugin.json) — testing utility plugin
- [`eli5/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/eli5/.claude-plugin/plugin.json) — explanation-focused plugin

This consistent structure allows the validation workflow to locate manifests predictably across all community submissions.

## Summary

- The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) schema requires **nine mandatory fields** with strict type and format validation
- **Two optional fields** (`manifest_version`, `api`) support advanced plugin features
- The **JSON Schema** at [`.github/actions/validate-plugins/policy/schema.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/policy/schema.json) enforces compliance automatically
- The **GitHub Action** `validate-plugins` blocks merges for any invalid manifest
- Plugins must place [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) inside a `.claude-plugin/` directory

## Frequently Asked Questions

### What happens if my plugin.json fails schema validation?

The `validate-plugins` workflow fails the CI check, preventing merge. Error messages specify exactly which field violates which constraint—missing required fields, incorrect types, or malformed URLs.

### Can I use a custom license identifier in plugin.json?

No. The `license` field requires **SPDX-compatible identifiers** such as `MIT`, `Apache-2.0`, or `GPL-3.0`. Custom strings fail validation.

### Is the manifest_version field required in plugin.json?

No. `manifest_version` is optional and defaults to the current format version. Include it only if your plugin targets a specific schema revision explicitly.

### Where must I place the plugin.json file?

Place it in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) relative to your plugin's root directory. The validation workflow searches this exact path pattern across all plugin submissions.