What Is the Claude Plugin Manifest (plugin.json)? Purpose and Configuration Guide

The plugin.json file serves as the authoritative manifest that tells Claude how to discover, validate, and execute community plugins by defining metadata, entry points, configuration schemas, and security constraints.

In the anthropics/claude-plugins-community repository, every plugin relies on this central configuration file to integrate with Claude Cowork and Claude Code. The plugin manifest acts as the formal contract between developers and the Claude runtime, enabling automated validation through the claude plugin validate command while ensuring safe, typed execution of plugin capabilities.

Core Purpose of the Plugin Manifest

The plugin.json file provides the structural definition required for the Claude runtime to load and interact with community plugins. It encapsulates six critical aspects of plugin operation that govern everything from marketplace display to secure execution.

Plugin Identity and Metadata

The manifest establishes discoverability through identification fields including name, description, version, author, and license. These properties enable the marketplace and CLI tools to list, search, and categorize plugins accurately. Presentation assets such as icon, readme, and changelog references improve visual integration and documentation visibility within the Claude interface.

Entry Points and Executable Components

Claude discovers runnable code through directory path declarations that map to specific capability types:

• skills – Reusable, composable capabilities (e.g., product-audit) that Claude invokes during conversations
• agents – Specialized autonomous configurations with specific system prompts
• commands – CLI command implementations
• hooks – Lifecycle callbacks such as stop-hook

Configuration Schema and Security

The userConfig field accepts a JSON Schema definition that generates typed UI elements for end-user customization. This allows safe configuration of API keys and defaults without exposing secrets in version control. Additionally, the optional mcpServers object declares external Model Context Protocol dependencies, enabling the runtime to enforce the W011 security model for external service interactions.

Manifest Location and Resolution

Claude searches for the manifest using a specific resolution hierarchy within the plugin root directory. The primary location is:

<plugin-root>/.claude-plugin/plugin.json

If this hidden directory is absent, the runtime falls back to:

<plugin-root>/plugin.json

According to the resolution logic implemented in .github/actions/validate-plugins/lib/common.sh, the validation pipeline checks the .claude-plugin/ subdirectory first before examining the repository root, ensuring consistent discovery across different plugin structures.

Strict Mode and Manifest Synthesis

The strict boolean field (defaulting to true) determines whether the manifest file must exist physically on disk or can be generated dynamically.

Skills-Only Plugin Exceptions

When strict is set to false, the manifest becomes optional for skills-only plugins. In this scenario, the validation logic in .github/actions/validate-plugins/lib/common.sh synthesizes a minimal manifest on-the-fly, allowing the runtime to load skills safely without requiring developers to maintain a separate JSON file. The synthesized manifest includes only the essential fields: name, description, version, skills, and the strict: false declaration.

Validation and CI Integration

The repository enforces manifest integrity through automated validation scripts triggered on every pull request. The GitHub Action defined in .github/actions/validate-plugins/scripts/30-validate-cli-external.sh executes the claude plugin validate command against each discovered plugin.json file. This CI pipeline ensures that all entries referenced in .claude-plugin/marketplace.json maintain structural validity and semantic correctness before deployment to the marketplace.

Plugin Manifest Examples

Examining real implementations in the repository illustrates the spectrum from minimal configurations to production-grade definitions with external dependencies.

Minimal Skills-Only Configuration

For plugins containing only skills with no external service dependencies, the manifest can be minimal or omitted entirely when using strict: false:

{
  "name": "example-skills",
  "description": "A set of reusable Claude skills.",
  "version": "0.1.0",
  "skills": ["example-skill"],
  "strict": false
}

Full-Featured Production Manifest

The tres-finance-plugin demonstrates a complete configuration including user settings, agents, and MCP server declarations:

{
  "name": "tres-finance-plugin",
  "description": "Finance-focused tools for Claude.",
  "version": "1.2.3",
  "author": "Anthropic",
  "license": "MIT",
  "skills": [
    "tres-wallets-upload",
    "tres-upload-tx-header-validation"
  ],
  "agents": ["senior-product-reviewer"],
  "hooks": ["stop-hook"],
  "userConfig": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "apiKey": { 
        "type": "string", 
        "title": "API Key", 
        "airtableSecret": true 
      }
    },
    "required": ["apiKey"]
  },
  "mcpServers": {
    "finance-api": {
      "url": "https://api.finance.example.com",
      "auth": { "type": "apiKey", "header": "X-API-Key" }
    }
  },
  "icon": "icon.svg"
}

The actual implementation can be examined at tres-finance-plugin/.claude-plugin/plugin.json in the repository.

Summary

• The plugin.json file is the authoritative plugin manifest required for Claude to load and execute community plugins from the anthropics/claude-plugins-community repository.
• Claude searches for manifests in .claude-plugin/plugin.json first, falling back to plugin.json in the repository root.
• The strict mode flag controls whether the manifest is mandatory or can be synthesized for skills-only plugins lacking external dependencies.
• Entry points (skills, agents, hooks, commands) tell Claude which executable components the plugin contributes to conversations.
• User configuration schemas enable typed, secure customization through the userConfig JSON Schema field, with sensitive fields marked via airtableSecret.
• The MCP servers declaration enables secure integration with external services under the W011 security model.
• Validation occurs through the claude plugin validate command executed by .github/actions/validate-plugins/scripts/30-validate-cli-external.sh in the CI pipeline.

Frequently Asked Questions

What happens if I don't include a plugin.json file in my plugin?

If you omit the manifest file and set "strict": false in your configuration, the Claude runtime synthesizes a minimal manifest automatically during the loading process. However, if strict remains true (the default), the plugin fails to load entirely, and the CI validation script in .github/actions/validate-plugins/scripts/30-validate-cli-external.sh will reject your submission during the pull request process.

Where should I place the plugin.json file in my repository?

Place the file at <plugin-root>/.claude-plugin/plugin.json for primary resolution. If this hidden directory structure is absent, Claude will search for <plugin-root>/plugin.json as a fallback. The resolution logic in .github/actions/validate-plugins/lib/common.sh implements this hierarchical search pattern to accommodate different plugin organization preferences.

How do I define user-configurable settings for my plugin?

Define a userConfig object containing a valid JSON Schema draft-07 specification in your plugin.json. This schema automatically generates the configuration UI in Claude's interface, allowing users to input API keys, endpoint URLs, or other parameters securely without hardcoding them. Mark sensitive string fields with "airtableSecret": true to ensure the runtime handles them with appropriate encryption and access controls.

What is the difference between skills and agents in the manifest?

The skills array defines reusable, composable capabilities (such as product-audit) that Claude invokes as tools during conversations to accomplish specific tasks. The agents array defines specialized autonomous configurations with distinct system prompts and tool access that can operate independently or be invoked by the user. Both are declared as string identifiers in the manifest that map to corresponding subdirectories within the plugin structure.

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