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

> Learn the purpose and configuration of the Claude plugin manifest (plugin.json). Discover how Claude uses this file to validate and execute community plugins effectively.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: api-reference
- Published: 2026-08-24

---

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

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

```

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

```text
<plugin-root>/plugin.json

```

According to the resolution logic 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), 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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/30-validate-cli-external.sh) executes the `claude plugin validate` command against each discovered [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file. This CI pipeline ensures that all entries referenced in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`:

```json
{
  "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:

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json) in the repository.

## Summary

- The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) first, falling back to [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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.