# Claude Plugin Manifest Structure: A Complete Guide to plugin.json

> Understand Claude plugin manifest structure with this guide to plugin.json. Learn about metadata versioning and schema configuration for the Claude Code ecosystem.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: documentation
- Published: 2026-09-10

---

**Claude plugin manifests are JSON configuration files ([`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)) located in the repository root or `.claude-plugin/` directory that define metadata, versioning, and user configuration schemas required by the Claude Code ecosystem.**

The `anthropics/claude-plugins-community` repository establishes the canonical schema for these manifests, balancing strict validation requirements with flexible support for skills-only plugins. Understanding the precise structure of **Claude plugin manifests** enables developers to publish discoverable, configurable tools that integrate seamlessly with Claude Code.

## Core Structure of plugin.json

Every Claude plugin requires a manifest file named [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json). According to the repository structure, this file resides either in the repository root or within the hidden `.claude-plugin/` directory. The manifest follows a JSON schema that captures essential metadata for plugin discovery and execution.

## Required and Optional Manifest Fields

The schema distinguishes between core metadata required for all plugins and optional configuration objects that enable user customization.

### Required Metadata Fields

The following fields constitute the minimum viable manifest:

- **`name`**: Human-readable identifier used in marketplace listings and plugin loading.
- **`description`**: Brief summary displayed in plugin discovery interfaces.
- **`version`**: Semantic version string (e.g., `1.12.1`).
- **`author`**: Object containing `name` and optional `email` of the creator.
- **`homepage`**: URL pointing to documentation or project website.
- **`repository`**: Source code location URL.
- **`license`**: SPDX-style identifier (e.g., `MIT`).
- **`keywords`**: Array of strings for categorization and searchability.

### Optional Configuration with userConfig

Plugins requiring end-user configuration specify a **`userConfig`** object. Each key in this object defines a configuration field with the following properties:

- **`title`**: Display name for the setting.
- **`description`**: Explanation of the configuration purpose.
- **`type`**: Data type specification (e.g., `string`).
- **`sensitive`**: Boolean flag indicating whether the value contains secrets like API keys.

A complete example from [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json) demonstrates this structure:

```json
{
  "name": "tres-finance-plugin",
  "description": "Financial data integration for Claude",
  "version": "1.12.1",
  "author": {
    "name": "Tres Finance Team",
    "email": "support@tres.finance"
  },
  "homepage": "https://tres.finance",
  "repository": "https://github.com/anthropics/claude-plugins-community",
  "license": "MIT",
  "keywords": ["finance", "accounting", "api"],
  "userConfig": {
    "API_KEY": {
      "title": "API Key",
      "description": "Secret key for Tres Finance API access",
      "type": "string",
      "sensitive": true
    }
  }
}

```

## Marketplace Aggregation with marketplace.json

When plugins publish to the community marketplace, a higher-level **[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** file aggregates multiple entries. Located at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), this file manages plugin registration through entries containing:

- **`name`**: Plugin identifier matching the directory name.
- **`source`**: Relative path to the plugin directory.
- **`strict`**: Boolean determining validation strictness.

The `strict` field controls manifest requirements:

```json
{
  "name": "tres-finance-plugin",
  "source": "./",
  "strict": false
}

```

When `strict` is `true`, the plugin must provide a complete [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json). When `false`, the system permits minimal or synthetic manifests.

## Manifest Synthesis for Skills-Only Plugins

For plugins marked with `"strict": false` that omit a [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file, the validation workflow automatically **synthesizes** a minimal manifest. This behavior is implemented in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh) via the `resolve_external_manifest` function.

The synthesis process generates a temporary manifest containing only the `name` field, written to [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) in a clone directory before validation:

```json
{
  "name": "my-skill-only-plugin"
}

```

This allows lightweight skills to participate in the ecosystem without maintaining full metadata files, while still passing validation checks.

## Real-World Examples from the Repository

The `anthropics/claude-plugins-community` repository provides concrete implementations demonstrating both comprehensive and minimal manifest patterns.

### Full Manifest Example

The Tres Finance plugin at [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json) illustrates a production-ready configuration with `userConfig` for sensitive credentials and complete metadata for marketplace discovery.

### Minimal Manifest Example

Conversely, the TestDino plugin at [`testdino/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/plugin.json) demonstrates a bare-bones configuration without `userConfig`, suitable for simple tools requiring no end-user configuration.

## Summary

- Claude plugin manifests use the filename [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and reside in the repository root or `.claude-plugin/` directory.
- Required fields include `name`, `description`, `version`, `author`, `homepage`, `repository`, `license`, and `keywords`.
- The optional `userConfig` object defines user-configurable settings with `title`, `description`, `type`, and `sensitive` properties.
- Marketplace aggregation uses [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) with a `strict` flag that determines whether full manifests are required.
- The `resolve_external_manifest` function in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh) synthesizes minimal manifests for skills-only plugins when `strict` is `false`.

## Frequently Asked Questions

### Where should the plugin.json file be located?

Claude expects the manifest file at the repository root or within a hidden `.claude-plugin/` directory. Both locations are valid, though the `.claude-plugin/` directory is preferred for cleaner repository organization.

### What is the purpose of the strict field in marketplace.json?

The `strict` boolean in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) controls validation requirements. When set to `true`, the plugin must provide a complete [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) with all metadata fields. When `false`, the validation system generates a synthetic manifest containing only the plugin name, accommodating lightweight skills without full configuration files.

### How does userConfig handle sensitive information like API keys?

The `userConfig` object includes a `sensitive` boolean flag for each configuration field. When set to `true`, Claude treats the value as a secret, ensuring appropriate handling and storage of credentials like API keys or authentication tokens.

### What happens if a plugin omits the plugin.json file entirely?

If a plugin lacks a manifest file but is registered in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) with `"strict": false`, the validation workflow automatically creates a synthetic manifest. The `resolve_external_manifest` function in the validation scripts generates this temporary file containing only the `name` field, allowing the plugin to pass validation without manual manifest creation.