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

> Learn how to configure the .claude-plugin/plugin.json file for Claude plugins. Add name, version, description, author, and license for optimal setup.

- Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins)
- Tags: how-to-guide
- Published: 2026-05-30

---

**To configure a Claude plugin, create a [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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.

```json
{
  "name": "zoom-plugin"
}

```

*Source:* [`partner-built/zoom-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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.

```json
{
  "version": "1.1.0"
}

```

*Source:* [`partner-built/zoom-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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.

```json
{
  "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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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.

```json
{
  "author": {
    "name": "Anthropic",
    "email": "team@anthropic.com"
  }
}

```

*Source:* [`partner-built/zoom-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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.

```json
{
  "license": "MIT"
}

```

*Source:* [`partner-built/zoom-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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:

   ```bash
   mkdir -p .claude-plugin
   ```

2. **Create the manifest file** at [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) with your configuration values.

3. **Validate the configuration** using the CLI if available:

   ```bash
   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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json) that passes validation requires only the `name` field:

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

```

*Source:* Create-Cowork-Plugin skill documentation, [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) line 58.

### Production-Ready Example

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

```json
{
  "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": "team@anthropic.com"
  },
  "license": "MIT"
}

```

*Sources:* Referenced from [`partner-built/zoom-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/.claude-plugin/plugin.json) - Full-featured partner implementation
- **Slack Plugin**: [`partner-built/slack/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/slack/.claude-plugin/plugin.json) - Another partner-built example
- **Small Business Plugin**: [`small-business/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/.claude-plugin/plugin.json) - Core repository implementation
- **Documentation**: [`cowork-plugin-management/skills/create-cowork-plugin/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json) manifest file. The GitHub Actions workflow at [`.github/workflows/check-mcp-urls.yml`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/.claude-plugin/plugin.json) line 7 demonstrates using `"MIT"`. Ensure the identifier matches your actual repository license file.