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

The 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.

The 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 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, a fully-compliant implementation located at quickdesign/.claude-plugin/plugin.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 through automated checks.

Validation Workflow Location

The GitHub Action definition resides in .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. 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 in a .claude-plugin/ subdirectory. The repository contains multiple reference implementations:

• quickdesign/.claude-plugin/plugin.json — media generation plugin with extensive keywords
• testdino/.claude-plugin/plugin.json — testing utility plugin
• 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 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 enforces compliance automatically
• The GitHub Action validate-plugins blocks merges for any invalid manifest
• Plugins must place 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 relative to your plugin's root directory. The validation workflow searches this exact path pattern across all plugin submissions.

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