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

The ai_plugin.json file (physically implemented as 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 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 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, the actual file must be named 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:

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:

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

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:

# 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 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: Lists all community plugins available for discovery, containing references to their manifest locations
• SKILL.md: Individual skill documentation files that explain how to use specific capabilities declared in the manifest's API section
• 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 specification is implemented as 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.
• 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 and plugin.json?

These refer to the same file using different naming conventions. While the specification is often discussed conceptually as ai_plugin.json (or aiplugin.json), the actual file must be named plugin.json and placed inside a .claude-plugin directory. Claude's runtime specifically looks for .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.

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