# What Is the `ai_plugin.json` File in Claude Plugins? A Complete Manifest Guide

> Understand the ai_plugin.json file, the manifest that guides Claude plugins. Learn how it validates, registers, and executes your plugin's API endpoints and configurations.

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

---

**The [`ai_plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/ai_plugin.json) file (physically implemented as [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) inside the `.claude-plugin` directory) is the mandatory manifest that tells Claude's runtime how to validate, register, and execute a plugin, including its API endpoints, user configuration schema, and security requirements.**

The [`ai_plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/ai_plugin.json) manifest serves as the backbone of every Claude plugin in the `anthropics/claude-plugins-community` ecosystem. This JSON configuration file—located at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) within each plugin folder—declares everything from the plugin's identity to its security-sensitive user settings. Understanding this manifest structure is essential for developers building custom integrations that Claude can discover and load safely.

## Core Purpose of the ai_plugin.json Manifest

When Claude encounters a plugin directory, it searches for the manifest file to begin the initialization sequence. The manifest acts as a contract between the plugin developer and Claude's runtime, specifying exactly what the plugin provides and what it requires from the user.

According to the source code structure in `anthropics/claude-plugins-community`, the manifest enables three critical runtime functions:

- **Validation**: Claude parses the JSON to verify required fields are present and checks that no secrets are hardcoded in the manifest
- **Registration**: The runtime registers the plugin's commands so Claude can invoke them during its "thinking" phase or when a user explicitly calls the plugin
- **Configuration Management**: Claude exposes declared user settings in the UI, securely prompting for missing values marked as sensitive

## Manifest File Location and Naming

While the specification is often referred to conceptually as [`ai_plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/ai_plugin.json), the actual file must be named [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and reside inside a `.claude-plugin` directory at your plugin root. For example, the community's `tres-finance-plugin` stores its manifest at:

```text
tres-finance-plugin/.claude-plugin/plugin.json

```

This path follows the standard plugin structure where the dot-prefixed directory contains metadata while the parent directory holds the plugin's business logic and skill definitions.

## Required Manifest Fields

The manifest must contain specific metadata fields that Claude uses for identification and display purposes:

- **`name`**: The unique identifier shown in the Claude UI and used in CLI commands like `claude plugin install`
- **`description`**: Human-readable text explaining what the plugin does and when to use it
- **`version`**: A semantic version string (e.g., "1.2.0") that enables update tracking and dependency management
- **`author`**, **`homepage`**, **`repository`**: Attribution and troubleshooting metadata that helps users understand plugin provenance
- **`license`**: Legal usage information governing how the plugin can be distributed and modified
- **`keywords`**: An array of tags that help users discover the plugin in the marketplace search

## Functional Configuration Fields

Beyond basic metadata, the manifest declares how the plugin interfaces with external systems and what it needs from users:

### API Endpoint Definitions

The **`api`** field describes the HTTP endpoints the plugin exposes, including request/response schemas and authentication methods. This allows Claude to understand what capabilities it can invoke and how to format calls to the plugin's backend.

### User Configuration Schema

The **`userConfig`** object declares required user-supplied settings such as API keys, endpoints, or preferences. Each configuration key can include:

- **`title`**: The display label shown in the Claude UI
- **`description`**: Help text explaining what the value is for
- **`type`**: The data type (string, boolean, number, etc.)
- **`sensitive`**: A boolean flag that, when set to `true`, ensures Claude prompts the user securely and stores the value in an encrypted credential store

For example, the `tres-finance-plugin` declares a sensitive API key like this:

```json
{
  "userConfig": {
    "DEBANK_API_KEY": {
      "title": "DeBank API Key",
      "description": "Your DeBank Pro API key for balance validation",
      "type": "string",
      "sensitive": true
    }
  }
}

```

When a user first runs this plugin, Claude automatically prompts for the `DEBANK_API_KEY` value without exposing it in logs or UI displays.

### Visual Assets

The optional **`icon`** field specifies a path to an SVG or PNG file displayed next to the plugin name in the Claude interface, providing visual identification in the marketplace and installed plugins list.

## Validating and Parsing Manifests

You can programmatically inspect plugin manifests using standard JSON parsing. This is useful for build scripts, CI/CD pipelines, or custom plugin managers:

```python
import json
import pathlib

manifest_path = pathlib.Path(
    "tres-finance-plugin/.claude-plugin/plugin.json"
)

with manifest_path.open(encoding='utf-8') as f:
    manifest = json.load(f)

print(f"Plugin: {manifest['name']} v{manifest['version']}")
print(f"Description: {manifest['description']}")
print("Endpoints:", manifest.get("api", {}).keys())

```

This script reads the manifest from the canonical location and extracts the plugin identity and available endpoints.

## CLI Installation and Marketplace Integration

Claude's CLI uses the manifest during the installation workflow. To add the community marketplace and install a plugin with its manifest:

```bash

# Add the community marketplace to Claude's plugin registry

claude plugin marketplace add anthropics/claude-plugins-community

# Install a specific plugin; Claude fetches and validates its manifest

claude plugin install tres-finance-plugin@claude-community

```

During installation, Claude downloads the plugin directory, validates the [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) against its schema invariants, and registers the commands outlined in the manifest.

## Related Files in the Plugin Ecosystem

The manifest works alongside several other standard files in a complete Claude plugin:

- **[`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)**: Lists all community plugins available for discovery, containing references to their manifest locations
- **[`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)**: Individual skill documentation files that explain how to use specific capabilities declared in the manifest's API section
- **[`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md)**: Repository root documentation providing overview information that supplements the manifest description

These files together create a complete, discoverable, and secure plugin package that Claude can load and execute safely.

## Summary

- The **[`ai_plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/ai_plugin.json)** specification is implemented as **[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** inside the **`.claude-plugin`** directory at the plugin root.
- It declares **metadata** (name, version, author), **API endpoints**, and **user configuration requirements** including sensitive credentials.
- Claude uses the manifest to **validate** the plugin structure, **register** available commands, and **prompt** users securely for required configuration.
- Real-world examples in `anthropics/claude-plugins-community` demonstrate the structure at paths like [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json).
- The manifest enables both **CLI management** and **runtime execution** of plugins within the Claude ecosystem.

## Frequently Asked Questions

### What is the difference between [`ai_plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/ai_plugin.json) and [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)?

These refer to the same file using different naming conventions. While the specification is often discussed conceptually as [`ai_plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/ai_plugin.json) (or [`aiplugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/aiplugin.json)), the actual file must be named [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and placed inside a `.claude-plugin` directory. Claude's runtime specifically looks for [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) when loading a plugin.

### How do I declare sensitive API keys that require secure storage?

Use the `userConfig` field in your manifest to declare configuration keys with `"sensitive": true`. When Claude encounters this flag during plugin loading, it automatically prompts the user for the value through a secure input dialog and stores the credential in an encrypted vault rather than plain text, ensuring the value never appears in logs or UI traces.

### What happens if my manifest is missing required fields?

Claude's runtime performs strict validation against internal invariants when loading a plugin. If required fields like `name`, `description`, or `version` are missing, or if the JSON structure is malformed, the validation step fails and the plugin is rejected during the registration phase. The CLI or UI will display an error indicating which specific invariants failed, preventing the plugin from being installed or executed until the manifest is corrected.