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

The 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 or .claude-plugin/plugin.json—defines everything from plugin metadata to external MCP server configurations.

What is plugin.json?

The 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. 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 handles runtime discovery, checking for 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

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

{
  "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 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, while manifest resolution logic resides in /.github/actions/validate-plugins/lib/common.sh.
• Files must be named 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 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.

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