# Claude Plugin Schema Specifications: A Complete Developer Guide

> Explore Claude plugin schema specifications for developers. Learn about manifest requirements, input schemas, authentication, and more to build powerful AI integrations.

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

---

**Claude plugins require a JSON manifest with `schema_version`, `name`, and a `tools` array containing `input_schema` definitions, while supporting optional authentication, runtime, and metadata fields.**

The Claude plugin architecture in the `anthropics/claude-plugins-community` repository standardizes how external tools integrate with Claude Code through structured JSON manifests. Each plugin must provide a validated manifest that declares its capabilities, arguments, and security requirements. Understanding the Claude plugin schema specifications ensures seamless tool discovery and prevents validation errors during plugin loading.

## Core Manifest Structure

The manifest conforms to a strict JSON schema where every field serves a specific purpose in the plugin lifecycle.

### Required Fields

Every Claude plugin manifest must include these top-level keys:

- **`schema_version`** – An integer declaring the manifest format version. The current specification requires version `1`.
- **`name`** – A human-readable string identifier for the plugin (e.g., `tres-finance`).
- **`tools`** – An array of objects, each defining a callable tool with its validation schemas.

### Optional Metadata Fields

Developers can provide additional context through optional fields:

- **`description`** – A short paragraph explaining the plugin's purpose and functionality.
- **`author`** – The individual or organization responsible for the plugin.
- **`license`** – An SPDX license identifier (e.g., `MIT`, `Apache-2.0`).
- **`contact`** – Support email or URL for plugin users.
- **`runtime`** – Execution environment details such as Docker images or command-line entry points.
- **`metadata`** – Free-form key-value pairs for custom plugin data.

## Tool Definitions and JSON Schema Validation

The `tools` array is the operational core of the schema, with each tool requiring strict input validation to ensure Claude passes correctly typed arguments.

### Input Schema Requirements

Every tool object must contain:

- **`name`** – The command identifier used in Claude prompts (e.g., `tres-report-create`).
- **`description`** – A clear explanation of the tool's functionality.
- **`input_schema`** – A valid JSON Schema (Draft 07 or later) that validates arguments passed from Claude to the tool. This schema defines required parameters, types, and constraints.

### Optional Output Schemas

Tools may optionally declare an **`output_schema`** field containing JSON Schema validation for the data returned to Claude. When provided, Claude validates the plugin's response before presenting results to users, ensuring type safety and consistent formatting.

## Authentication Specifications

The schema supports secure credential handling through an optional **`authentication`** object:

- **`type`** – The authentication mechanism (currently supporting `apiKey`).
- **`env`** – The environment variable name where users must store their secrets (e.g., `TRES_API_KEY`).

Claude prompts users to provide these secrets only when the plugin is first invoked, preventing hard-coded credentials in plugin definitions stored in version control.

## Repository Structure and Key Files

In the `anthropics/claude-plugins-community` repository, schema-compliant plugins organize files according to the following structure:

- **`tres-finance-plugin/.claude-plugin/`** – The directory containing plugin definitions for individual plugins.
- **[`.claude-plugin/manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/manifest.json)** – The root manifest file that Claude validates during plugin discovery.
- **`.claude-plugin/tools/<tool>.json`** – Individual tool definitions containing `input_schema` and optional `output_schema` objects.
- **[`opencode.json`](https://github.com/anthropics/claude-plugins-community/blob/main/opencode.json)** – Repository-level configuration that references plugin manifest schemas.
- **[`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md)** – Documentation providing overview and authoring guidelines for the plugin collection.

## Practical Implementation Example

Below is a complete, schema-compliant manifest demonstrating all field specifications:

```json
{
  "schema_version": 1,
  "name": "tres-finance",
  "description": "Financial-report generation and analysis tools for Claude.",
  "author": "Anthropic",
  "license": "MIT",
  "tools": [
    {
      "name": "tres-report-create",
      "description": "Create a new financial report from raw transaction data.",
      "input_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "title": { "type": "string", "description": "Report title" },
          "transactions": {
            "type": "array",
            "items": { 
              "type": "object", 
              "properties": { 
                "date": { "type": "string", "format": "date" }, 
                "amount": { "type": "number" } 
              } 
            }
          }
        },
        "required": ["title", "transactions"]
      },
      "output_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "report_id": { "type": "string" },
          "summary": { "type": "string" }
        },
        "required": ["report_id"]
      }
    }
  ],
  "authentication": {
    "type": "apiKey",
    "env": "TRES_API_KEY"
  }
}

```

When Claude loads this manifest from [`tres-finance-plugin/.claude-plugin/manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/manifest.json), it validates the structure against the schema, registers the `tres-report-create` tool, and prompts for the `TRES_API_KEY` environment variable on first use.

## Summary

- **Claude plugin schemas** require a JSON manifest with `schema_version` set to `1`, a unique `name`, and a `tools` array containing at least one tool definition with a valid `input_schema`.
- Each **tool** must specify an `input_schema` using JSON Schema Draft 07+ to validate incoming arguments from Claude; `output_schema` is optional but recommended for response validation.
- **Authentication** is handled through environment variables declared in the manifest via the `authentication` object, keeping secrets out of source control.
- Plugin files reside in `.claude-plugin/` directories, with [`manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main/manifest.json) serving as the entry point and individual tool schemas stored in `tools/<tool>.json` files.

## Frequently Asked Questions

### What is the current schema_version for Claude plugins?

The Claude plugin schema currently requires `schema_version` set to integer `1`. This version identifier in [`manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main/manifest.json) declares the manifest format that Claude Code expects during plugin discovery and validation.

### Is the output_schema field mandatory for tool definitions?

No, **`output_schema`** is optional. While **`input_schema`** is required to validate arguments Claude sends to the tool, `output_schema` only validates the data returned from the tool. Omitting it allows the plugin to return unstructured data, though defining it ensures type-safe responses.

### How do I securely handle API keys in Claude plugin manifests?

Use the **`authentication`** object with `type: "apiKey"` and specify the environment variable name in the `env` field (e.g., `"env": "TRES_API_KEY"`). Claude prompts users to set this variable before first invocation, ensuring credentials never appear in manifest files or committed source code.

### Where should I place the manifest.json file in my plugin directory?

Place **[`manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main/manifest.json)** inside the `.claude-plugin/` directory at the root of your plugin folder (e.g., [`tres-finance-plugin/.claude-plugin/manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/manifest.json)). This location follows the convention established in the `anthropics/claude-plugins-community` repository and enables Claude to automatically discover and load your plugin.