Claude Plugin Schema Specifications: A Complete Developer Guide

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 – 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 – Repository-level configuration that references plugin manifest schemas.
• 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:

{
  "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, 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 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 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 inside the .claude-plugin/ directory at the root of your plugin folder (e.g., 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.

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