# How to Structure Custom Plugins for Anthropic's AI: A Complete Developer Guide

> Learn how to structure custom plugins for Anthropic's AI with this developer guide. Explore directory layout, plugin.json manifest, and skills directory for seamless API integration.

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

---

**Anthropic's AI platform uses a claude-plugin model requiring a specific directory layout with a [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json) manifest, [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) configuration for MCP servers, and a `skills/` directory containing Markdown-based command definitions that define how Claude interacts with external APIs.**

The `anthropics/knowledge-work-plugins` repository provides the reference implementation for building custom plugins that extend Anthropic's Claude AI with external capabilities. Understanding the exact file structure and configuration format is essential for developers who want to structure custom plugins for Anthropic's AI correctly. This guide walks through the required components using examples from the official Zoom plugin and small-business templates.

## Required Directory Structure for Anthropic AI Plugins

Every custom plugin must follow a strict convention to be recognized by Claude's plugin system. The `partner-built/zoom-plugin` in the reference repository demonstrates the canonical layout that all plugins should replicate.

```

my-custom-plugin/
├── .claude-plugin/
│   └── plugin.json                ← manifest
├── .mcp.json                      ← MCP server definitions
├── skills/
│   ├── start/
│   │   └── SKILL.md               ← entry point with routing
│   └── [workflow]/
│       └── SKILL.md               ← business logic skills
├── CONNECTORS.md                  ← authentication setup guide
├── README.md                      ← installation & overview
└── LICENSE

```

### The Plugin Manifest Location

The [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json) file must live inside a hidden `.claude-plugin/` directory at the root. According to the source code in [`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), this JSON file declares the plugin's metadata including `name`, `version`, `description`, and `keywords` for marketplace discovery.

### MCP Configuration File

The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file sits at the repository root and defines Model-Context-Protocol servers. As shown in [`partner-built/zoom-plugin/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/.mcp.json), this configuration transforms remote APIs into first-class tools that Claude can invoke directly.

### Skills Directory Organization

The `skills/` directory contains subdirectories, each holding exactly one [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file. The entry point is typically [`skills/start/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/skills/start/SKILL.md), which handles initial routing to other specialized workflow skills located in sibling folders.

## Creating the Plugin Manifest

The manifest requires specific fields for Anthropic's plugin marketplace. Valid entries include `name` (unique identifier), `version` (semantic versioning), `description` (marketplace summary), `homepage` (documentation URL), `repository` (source location), `license` (SPDX identifier), and `keywords` (discovery tags).

Example from the reference implementation:

```json
{
  "name": "my-custom-plugin",
  "version": "0.1.0",
  "description": "A sample plugin that demonstrates the required structure for Anthropic Claude.",
  "homepage": "https://github.com/yourorg/my-custom-plugin",
  "repository": "https://github.com/yourorg/my-custom-plugin",
  "license": "MIT",
  "keywords": ["example", "anthropic", "claude-plugin"]
}

```

Keep the manifest minimal and valid. Optional fields like `author.url` should only be included if they add necessary clarity for users browsing the marketplace.

## Configuring MCP Servers

The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file contains a JSON array of server objects. Each entry specifies the server `name`, base `url`, authentication model, and environment variable placeholders that Claude will read at runtime.

Authentication uses the `envVar` field within the `auth` object to tell Claude which environment variable contains the token. For example, in [`partner-built/zoom-plugin/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/.mcp.json), the configuration references `ZOOM_MCP_ACCESS_TOKEN` for OAuth bearer tokens.

```json
[
  {
    "name": "example-mcp",
    "url": "https://example.com/mcp",
    "auth": {
      "type": "bearer",
      "envVar": "EXAMPLE_MCP_TOKEN"
    },
    "description": "Example MCP server exposing a simple CRUD API"
  }
]

```

Claude prompts users to set these environment variables if they are missing when the plugin loads.

## Writing Skill Files with Routing

Each [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file follows a YAML frontmatter format specifying `name` and `description` fields. The Markdown content includes functional descriptions, implementation steps, and optional routing tables that enable Claude to delegate requests to specialized skills.

For instance, the `start` skill in [`partner-built/zoom-plugin/skills/start/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/skills/start/SKILL.md) analyzes user intent and redirects to appropriate workflow skills using relative paths.

```yaml
---
name: start
description: Entry point for the plugin – routes user requests to the correct workflow.
---

# Start

## What This Skill Does

- Analyzes the user's intent.
- Routes to a more specific skill based on the intent.

## Routing Table

| If the user wants to… | Route to |
|-----------------------|----------|
| Create a resource     | [create-resource/SKILL.md](../create-resource/SKILL.md) |
| List resources        | [list-resource/SKILL.md](../list-resource/SKILL.md) |

```

The `skills/` tree can be arbitrarily deep, but each folder should contain exactly one [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file following the standard header format.

## Documenting Connectors and Setup

The [`CONNECTORS.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/CONNECTORS.md) file explains authentication requirements for external services. This documentation should list each required environment variable and provide shell commands for setup.

For example, when integrating with Zoom as shown in [`partner-built/zoom-plugin/CONNECTORS.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/CONNECTORS.md):

```markdown

## Zoom MCP

Export the token before using the plugin:

```bash
export ZOOM_MCP_ACCESS_TOKEN="your_zoom_user_oauth_access_token"

```

```

## Installing Your Custom Plugin

Once the directory structure is complete, install the plugin using the Claude CLI. The system automatically validates the [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json) manifest and loads MCP configurations from [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json).

1. Clone your repository locally or navigate to the plugin directory.
2. Run `claude plugins add path/to/my-custom-plugin` or install directly from GitHub using `claude plugins install my-custom-plugin@github.com/username/repo`.
3. Set required environment variables as documented in [`CONNECTORS.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/CONNECTORS.md).

Claude will immediately load the skills and make them available as slash commands based on the routing logic defined in your [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files.

## Summary

- **Directory structure matters**: Place [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json) in `.claude-plugin/`, [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) at root, and individual skills in `skills/[name]/SKILL.md` following the reference layout in `anthropics/knowledge-work-plugins`.
- **Manifest requirements**: Include `name`, `version`, `description`, and `keywords` in valid JSON format read from [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json).
- **MCP configuration**: Define external APIs as servers in [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) with proper `auth` type and `envVar` specifications for secure token handling.
- **Skills define behavior**: Each skill is a self-contained Markdown file with YAML frontmatter and optional routing tables that map user intents to specific workflow files.
- **Documentation is mandatory**: Include [`CONNECTORS.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/CONNECTORS.md) for authentication setup and [`README.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/README.md) for installation instructions to ensure users can configure required environment variables.

## Frequently Asked Questions

### What file format does the Anthropic AI plugin manifest use?

The plugin manifest uses standard JSON format stored in [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) at the repository root. It must include required fields such as `name`, `version`, `description`, and `license` (SPDX identifier), along with optional fields like `homepage` and `repository` URLs that help users find documentation and source code.

### Where should I store MCP server configurations in my custom plugin?

Store MCP server configurations in a file named [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) at the repository root, not inside the `.claude-plugin` directory. This file contains a JSON array of server objects that define how Claude connects to external APIs using authentication tokens specified via the `envVar` field within each server's `auth` configuration.

### How does routing work between different skills in an Anthropic AI plugin?

Routing works through Markdown tables inside [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files that map user intents to relative paths of other skill files. The entry point skill (typically [`skills/start/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/skills/start/SKILL.md)) analyzes the request and uses these routing tables to delegate to specific workflow skills located in sibling directories, enabling complex multi-step interactions.

### Can I use environment variables for authentication in Anthropic AI plugins?

Yes, the [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) configuration supports the `envVar` field within the `auth` object, which tells Claude which environment variable contains the authentication token. Users must export these variables before using the plugin, as documented in your [`CONNECTORS.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/CONNECTORS.md) file, and Claude will prompt for them if they are missing during plugin initialization.