Claude Plugin Manifest Required Fields: Complete JSON Schema Guide

A valid Claude plugin manifest requires five core fields in plugin.json: name, version, description, skills, and optionally author, though the author field is strongly recommended for published plugins.

Every Claude plugin distributed through the anthropics/claude-plugins-community repository must include a plugin.json manifest file located in the .claude-plugin directory. This JSON file defines the plugin's identity, capabilities, and entry points so the Claude CLI can validate, load, and execute the plugin correctly. Understanding the Claude plugin manifest required fields ensures your submission passes automated validation and installs without errors.

Core Required Fields for Every Claude Plugin Manifest

The anthropics/claude-plugins-community validation logic, implemented in .github/actions/validate-plugins/lib/common.sh, enforces strict requirements for the following fields. Missing any of these will cause validation failures during CI/CD checks.

name

The name field serves as the unique identifier for your plugin and defines the namespace for all slash commands. This string must be unique across the plugin ecosystem to prevent command collisions.

{
  "name": "eli5"
}

version

The version field follows semantic versioning (SemVer) standards to track plugin releases. The Claude CLI uses this value to manage updates and dependency resolution.

{
  "version": "1.0.0"
}

description

The description field provides a human-readable summary of the plugin's functionality. This text appears in marketplace listings and CLI help outputs, so it should clearly state what the plugin enables Claude to do.

{
  "description": "Explain concepts in simple terms"
}

skills

The skills field is an array of objects defining the capabilities your plugin exposes to Claude. Each skill object must include at least name (the skill identifier) and command (the slash command used to invoke it, namespaced with your plugin name).

{
  "skills": [
    {
      "name": "eli5",
      "command": "/eli5:explain"
    }
  ]
}

According to the source code in the ELI5 plugin example at eli5/.claude-plugin/plugin.json, skills can optionally include additional configuration parameters, but the name and command properties are mandatory for each entry in the array.

Recommended Fields for Publication

While the validation script technically allows manifests without these fields, the anthropics/claude-plugins-community maintainers strongly recommend including them for any plugin intended for public distribution.

author

The author field contains an object with contact information for plugin support and attribution. The object must include a name string and can optionally include email and url strings.

{
  "author": {
    "name": "Thariq Shihipar",
    "email": "thariq@example.com"
  }
}

The Tres Finance plugin manifest at tres-finance-plugin/.claude-plugin/plugin.json demonstrates this pattern in production, providing clear attribution for users seeking support.

Optional Fields for Advanced Functionality

These fields extend plugin capabilities beyond basic skill execution, enabling autonomous agents and lifecycle hooks.

agents

The agents array defines autonomous agent configurations that can operate independently within Claude. Each agent object requires name and command properties, similar to skills but with different execution semantics.

{
  "agents": [
    {
      "name": "question-responder",
      "command": "/eli5:agent"
    }
  ]
}

hooks

The hooks array specifies scripts that run at specific lifecycle points, such as before or after tool execution. Each hook object requires a type (typically "pre" or "post") and a path relative to the .claude-plugin directory.

{
  "hooks": [
    {
      "type": "pre",
      "path": "hooks/pre.sh"
    }
  ]
}

Additional optional metadata fields include license, homepage, keywords, and dependencies, though these do not affect core validation.

Validation and File Location

The manifest file must reside at .claude-plugin/plugin.json in your repository root. The validation logic in .github/actions/validate-plugins/lib/common.sh checks for required keys, validates JSON syntax, and ensures command namespacing compliance before allowing submission to the marketplace.

To validate your manifest locally before submission:

# Validate the manifest syntax and required fields

claude plugin validate .claude-plugin/plugin.json

# Install locally for testing (requires successful validation)

claude plugin install .

Complete Plugin Manifest Example

This production-ready example from the anthropics/claude-plugins-community repository demonstrates all required fields plus recommended optional fields:

{
  "name": "my-awesome-plugin",
  "version": "0.1.0",
  "description": "Adds cool new capabilities to Claude.",
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "skills": [
    {
      "name": "cool-skill",
      "command": "/my-awesome-plugin:cool-skill"
    }
  ],
  "agents": [
    {
      "name": "helper-agent",
      "command": "/my-awesome-plugin:helper-agent"
    }
  ],
  "hooks": [
    {
      "type": "pre",
      "path": "hooks/pre.sh"
    }
  ]
}

Summary

• Five fields are mandatory: Every plugin.json must include name, version, description, skills, and ideally author to pass validation in anthropics/claude-plugins-community.
• File location matters: The manifest must live at .claude-plugin/plugin.json relative to your repository root.
• Arrays require specific structures: Both skills and agents arrays contain objects that must specify name and command properties.
• Validation is automated: The script at .github/actions/validate-plugins/lib/common.sh enforces these requirements during CI/CD.

Frequently Asked Questions

What are the absolute minimum fields required for a Claude plugin manifest?

The absolute minimum required fields are name, version, description, and skills. While author is technically optional, the anthropics/claude-plugins-community validation scripts flag manifests missing this field as incomplete, and the repository maintainers strongly recommend including it for accountability and support purposes.

Where should the plugin.json file be located?

The manifest must reside at .claude-plugin/plugin.json in your repository root. This specific path allows the Claude CLI and the validation GitHub Action to locate and parse your plugin configuration automatically during installation and CI checks.

How do I validate my Claude plugin manifest locally?

Run claude plugin validate .claude-plugin/plugin.json from your repository root. This command checks JSON syntax, verifies that all required fields (name, version, description, skills) are present, and ensures that skill commands use proper namespacing conventions before you submit to the community repository.

Can I include optional metadata like license and homepage?

Yes, the manifest schema supports additional optional fields including license, homepage, keywords, and dependencies. While these fields are not enforced by the validation logic in .github/actions/validate-plugins/lib/common.sh, they improve discoverability and compliance for public distribution in the anthropics/claude-plugins-community marketplace.

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