What Are the Required Fields in plugin.json for Claude Plugins?

Only the name field is required in plugin.json; all other metadata fields are optional.

The plugin.json manifest file serves as the entry point for Claude Code plugins in the anthropics/claude-plugins-official ecosystem. While the manifest supports extensive metadata for discovery and functionality, the validation logic enforces a minimal requirement set that allows developers to get started with just a single identifier.

The Single Required Field: name

According to the manifest reference in plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md, the name property is the only mandatory field in the plugin manifest.

Format and Validation Rules

The name field must adhere to strict formatting requirements:

• Type: Non-empty string
• Case: Kebab-case (lowercase letters, numbers, and hyphens only)
• Examples: "my-plugin", "ci-cd-automation", "data-processor-v2"

Claude Code uses this identifier for conflict detection, plugin discovery, and optional command namespacing when multiple plugins register similar functionality.

Optional Fields Overview

All remaining fields in plugin.json are optional and may be omitted entirely:

• version: String following semantic versioning (e.g., "0.1.0")
• description: Human-readable summary of plugin functionality
• author: String or object identifying the creator
• homepage: URL string pointing to documentation
• repository: URL string or object linking to source code
• license: SPDX license identifier (e.g., "MIT")
• keywords: Array of strings for categorization and search
• commands: String path or array defining command locations
• agents: String path or array defining agent definitions
• hooks: String path or object pointing to hook configurations
• mcpServers: String path or object defining MCP server settings

File Location Requirements

The manifest must reside at a specific path within your plugin directory. Claude Code expects to find plugin.json at:

.claude-plugin/plugin.json

This location is hardcoded in the plugin discovery system. Placing the file anywhere else or using a different filename will result in the runtime failing to recognize the plugin.

Minimal Valid plugin.json Example

The simplest functional manifest contains only the required name field:

{
  "name": "my-awesome-plugin"
}

This minimal configuration is sufficient for Claude Code to load and initialize the plugin, provided the file is correctly placed at .claude-plugin/plugin.json in the repository root.

Why name Is Mandatory

The runtime enforces the name field for several critical operations:

1. Unique Identification: Prevents namespace collisions when multiple plugins are installed
2. Conflict Detection: Enables the system to identify duplicate or incompatible plugin registrations
3. Discovery Mechanism: Powers the plugin registry and search functionality within Claude Code

As implemented in anthropics/claude-plugins-official, the validation logic explicitly checks for the presence and format of name during the loading phase, rejecting any manifest that lacks this property or provides it in an invalid format.

Summary

• Only the name field is required in plugin.json for Claude plugins
• The name must be a kebab-case string (lowercase with hyphens)
• All other fields—including version, description, commands, and mcpServers—are optional
• The manifest must be located at .claude-plugin/plugin.json in the plugin root
• A minimal valid manifest requires just {"name": "your-plugin-name"}

Frequently Asked Questions

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

Claude Code will reject the manifest during the loading phase. The runtime validation logic explicitly requires the name property to uniquely identify the plugin, detect conflicts, and enable discovery. Without it, the plugin will not be recognized or loaded.

Can I use camelCase or snake_case for the plugin name?

No. The name field must use kebab-case (lowercase letters, numbers, and hyphens only). The manifest reference at plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md specifies this format strictly, and validation will fail if you use camelCase (e.g., "myPlugin") or snake_case (e.g., "my_plugin").

Where must the plugin.json file be located?

The file must be placed at .claude-plugin/plugin.json relative to the repository root. This path is required by the plugin discovery system in anthropics/claude-plugins-official. Using a different filename or directory structure will prevent Claude Code from detecting the plugin.

Is the version field required for publishing plugins?

No. While providing a version string (preferably following semantic versioning like "1.0.0") is strongly recommended for tracking releases, it is not strictly required for the plugin to function. Only the name field is mandatory for the plugin to load successfully.

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