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

> Discover the essential fields for your plugin.json file with our guide. Learn exactly what Claude requires for successful plugin integration and development.

- Repository: [Anthropic/claude-plugins-official](https://github.com/anthropics/claude-plugins-official)
- Tags: api-reference
- Published: 2026-03-13

---

**Only the `name` field is required in [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json); all other metadata fields are optional.**

The [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json) at:

```text
.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:

```json
{
  "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`](https://github.com/anthropics/claude-plugins-official/blob/main/.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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/.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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/.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.