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

Claude plugin manifests are JSON configuration files (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. 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 demonstrates this structure:

{
  "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 file aggregates multiple entries. Located at .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:

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

When strict is true, the plugin must provide a complete 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 file, the validation workflow automatically synthesizes a minimal manifest. This behavior is implemented in .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 in a clone directory before validation:

{
  "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 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 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 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 with a strict flag that determines whether full manifests are required.
• The resolve_external_manifest function in .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 controls validation requirements. When set to true, the plugin must provide a complete 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 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.

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