How to Configure the .claude-plugin/plugin.json File for Claude Plugins

To configure a Claude plugin, create a .claude-plugin/plugin.json manifest file with at minimum a name field, optionally adding version, description, author, and license metadata.

The .claude-plugin/plugin.json file serves as the manifest that tells Claude how to treat a directory as a plugin within the anthropics/knowledge-work-plugins ecosystem. This JSON configuration file must reside in a hidden .claude-plugin folder at the repository root and defines the plugin's identity, version, and authorship information before Claude validates and loads it.

Required Fields in plugin.json Configuration

The manifest must include specific fields to pass validation. According to cowork-plugin-management/skills/create-cowork-plugin/SKILL.md at line 58, only the name field is strictly required, though production plugins typically include additional metadata for completeness.

name

The name field provides the unique identifier for your plugin and determines the .plugin filename used by the system.

{
  "name": "zoom-plugin"
}

Source: partner-built/zoom-plugin/.claude-plugin/plugin.json, line 2.

version

A semantic-version string that tracks plugin releases. While optional for basic validation, versioning is essential for distributed plugins.

{
  "version": "1.1.0"
}

Source: partner-built/zoom-plugin/.claude-plugin/plugin.json, line 4.

description

A short, human-readable summary explaining what the plugin does. This appears in plugin listings and helps users understand functionality at a glance.

{
  "description": "Claude plugin for planning, building, and debugging Zoom integrations across REST APIs, SDKs, webhooks, bots, and MCP workflows"
}

Source: partner-built/zoom-plugin/.claude-plugin/plugin.json, line 3.

author

An object containing at least a name field that identifies the creator or maintainer. You can optionally include an email field for contact purposes.

{
  "author": {
    "name": "Anthropic",
    "email": "[email protected]"
  }
}

Source: partner-built/zoom-plugin/.claude-plugin/plugin.json, line 18.

Optional Configuration Fields

license

An SPDX license identifier specifying how the plugin code may be used, modified, or distributed.

{
  "license": "MIT"
}

Source: partner-built/zoom-plugin/.claude-plugin/plugin.json, line 7.

icons, homepage, and repository

Additional optional fields include icons for SVG/PNG asset paths, homepage for documentation URLs, repository for source code links, and bugs for issue tracking endpoints. These enhance the plugin's presentation in the Claude UI but are not validated as strictly as core fields.

Step-by-Step plugin.json Configuration

Follow these steps to properly configure your plugin manifest:

1. Create the hidden directory at your repository root:

   mkdir -p .claude-plugin

2. Create the manifest file at .claude-plugin/plugin.json with your configuration values.

3. Validate the configuration using the CLI if available:

   claude plugin validate .claude-plugin/plugin.json

   Note: If the CLI is unavailable (for example, when working inside Cowork), manually ensure the file contains valid JSON with at least a name field—see SKILL.md lines 237-239 for validation guidelines.

4. Commit the manifest with your plugin code. The GitHub workflow at .github/workflows/check-mcp-urls.yml (line 23) scans for this file to identify valid plugins during CI/CD processes.

Minimal vs. Full-Featured Configuration

Minimal Valid Manifest

The smallest possible plugin.json that passes validation requires only the name field:

{
  "name": "my-plugin"
}

Source: Create-Cowork-Plugin skill documentation, SKILL.md line 58.

Production-Ready Example

The Zoom plugin illustrates a complete configuration with all recommended fields:

{
  "name": "zoom-plugin",
  "version": "1.1.0",
  "description": "Claude plugin for planning, building, and debugging Zoom integrations across REST APIs, SDKs, webhooks, bots, and MCP workflows",
  "author": {
    "name": "Anthropic",
    "email": "[email protected]"
  },
  "license": "MIT"
}

Sources: Referenced from partner-built/zoom-plugin/.claude-plugin/plugin.json lines 2, 3, 4, 7, and 18.

Troubleshooting Common Configuration Errors

Symptom	Likely Cause	Solution
Validation reports "missing name"	The name field is absent or the file path is incorrect	Ensure the file exists at exactly .claude-plugin/plugin.json and contains "name": "your-plugin"
Plugin fails to load in Claude UI	Invalid JSON syntax (trailing commas, unquoted keys)	Run the file through a JSON linter or use the CLI validator to catch syntax errors
CI/CD workflow ignores the plugin	Missing manifest in expected location	Verify .github/workflows/check-mcp-urls.yml can detect your manifest at line 23 of the workflow configuration

Reference Implementations

Study these existing manifests for configuration patterns:

• Zoom Plugin: partner-built/zoom-plugin/.claude-plugin/plugin.json - Full-featured partner implementation
• Slack Plugin: partner-built/slack/.claude-plugin/plugin.json - Another partner-built example
• Small Business Plugin: small-business/.claude-plugin/plugin.json - Core repository implementation
• Documentation: cowork-plugin-management/skills/create-cowork-plugin/SKILL.md - Official configuration guidelines starting at line 56

Summary

• Place a .claude-plugin directory at the root of your plugin repository to establish the manifest location.
• Include at minimum a name field in plugin.json; add version, description, author, and license for production-ready plugins.
• Validate your JSON syntax using the Claude CLI or manual verification before committing.
• The GitHub workflow at .github/workflows/check-mcp-urls.yml uses this file to identify and process plugins automatically.

Frequently Asked Questions

What is the minimum required configuration for plugin.json?

The absolute minimum requires only the name field: {"name": "my-plugin"}. However, according to the SKILL.md documentation at line 58, while this passes validation, you should include version, description, and author for any plugin intended for distribution.

Where should the plugin.json file be located?

The file must reside at .claude-plugin/plugin.json relative to your repository root. The .claude-plugin folder is hidden (starts with a dot) and must contain exactly one plugin.json manifest file. The GitHub Actions workflow at .github/workflows/check-mcp-urls.yml specifically scans for this path at line 23.

How do I validate my plugin.json configuration?

Use the command claude plugin validate .claude-plugin/plugin.json if you have the Claude CLI installed. If working within the Cowork system without CLI access, manually verify that your file contains valid JSON with at least the name field defined, as noted in SKILL.md lines 237-239.

What license identifiers should I use in plugin.json?

Use SPDX license identifiers such as "MIT", "Apache-2.0", or "GPL-3.0". The Zoom plugin example at partner-built/zoom-plugin/.claude-plugin/plugin.json line 7 demonstrates using "MIT". Ensure the identifier matches your actual repository license file.

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