# How to Add a Custom Plugin to Knowledge-Work-Plugins: A Complete Guide

> Learn how to add a custom plugin to knowledge-work-plugins. Follow our complete guide to scaffold your directory with manifest, MCP, and skill files for seamless integration.

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

---

**To add a custom plugin to the knowledge-work-plugins repository, scaffold a directory containing a [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) manifest, an optional [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) for MCP server definitions, a `skills/` folder with individual [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files, and a root [`README.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/README.md), then validate the structure using the Claude CLI.**

The `anthropics/knowledge-work-plugins` repository hosts a curated collection of Claude plugins designed for knowledge work automation. Adding a custom plugin requires following a strict directory convention that the Claude runtime recognizes during plugin loading. This guide walks you through the mandatory files, configuration formats, and validation steps required to contribute a functional plugin to the repository.

## Required Plugin Components

Every plugin in the knowledge-work-plugins repository must contain specific files that define its metadata, capabilities, and documentation:

- **[`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json)** — The required manifest file containing at minimum a `name` field, plus metadata like `description`, `version`, and `license`. See the Zoom plugin example at [`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).
- **[`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json)** (Optional) — Declares Model Context Protocol (MCP) servers the plugin bundles, as shown in [`partner-built/zoom-plugin/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/.mcp.json).
- **`skills/`** — Directory containing subfolders, each with a [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file that defines AI-driven capabilities, behavior, and usage examples.
- **[`README.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/README.md)** — Human-readable installation instructions, environment variable requirements, and usage overview.
- **`<name>.plugin`** (Generated) — The compiled file Claude loads, created automatically during validation or installation.

## Step-by-Step Implementation Guide

### 1. Create the Plugin Directory Structure

Begin by creating a top-level folder for your plugin at the repository root. The directory name should match your plugin's identifier.

```bash
mkdir -p my-awesome-plugin/.claude-plugin
mkdir -p my-awesome-plugin/skills/example-skill
touch my-awesome-plugin/README.md

```

### 2. Define the Plugin Manifest

Create [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) with valid JSON containing mandatory metadata. The manifest must include a `name` field and follows the schema defined in [`cowork-plugin-management/skills/create-cowork-plugin/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/cowork-plugin-management/skills/create-cowork-plugin/SKILL.md).

```json
{
  "name": "my-awesome-plugin",
  "description": "Provides AI-assisted workflows for knowledge work",
  "version": "0.1.0",
  "license": "MIT",
  "keywords": ["awesome", "plugin", "claude"]
}

```

The `name` field must be unique within the repository. The implementation guidelines in the creation skill documentation specify that this file is the canonical source for plugin metadata.

### 3. Configure Optional MCP Servers

If your plugin requires external service integration, add a [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file at the plugin root. This file declares HTTP or STDIO-based MCP servers that Claude discovers at load time. The manifest does not reference these servers directly.

```json
{
  "mcpServers": {
    "my-mcp": {
      "type": "http",
      "url": "https://my-mcp.example.com/streamable",
      "headers": {
        "Authorization": "Bearer ${MY_MCP_TOKEN}"
      }
    }
  }
}

```

Reference the Zoom plugin's [`partner-built/zoom-plugin/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/.mcp.json) for a production example of MCP server definitions.

### 4. Implement Skills with SKILL.md Files

Each capability resides in the `skills/` directory as a subfolder containing a [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file. These files define the AI behavior, usage examples, and reference materials that the Claude runtime parses to generate the tool surface.

Create [`skills/example-skill/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/skills/example-skill/SKILL.md) following the standard format:

```markdown
name: example-skill
description: Demonstrates a minimal skill implementation
usage: |
  You can ask the plugin to "echo <text>" and it will return the same text.

```

The [`cowork-plugin-management/skills/create-cowork-plugin/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/cowork-plugin-management/skills/create-cowork-plugin/SKILL.md) file contains the complete specification for skill formatting and directory layout conventions.

### 5. Document and Validate

Write a comprehensive [`README.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/README.md) including installation commands (`claude plugins add my-awesome-plugin@knowledge-work-plugins`) and required environment variables.

Validate your plugin structure using the Claude CLI:

```bash
claude plugin validate my-awesome-plugin/.claude-plugin/plugin.json

```

This command checks for manifest validity, proper JSON syntax, and required folder structure. If the CLI is unavailable, manually verify that [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json), optional [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json), the `skills/` directory, and [`README.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/README.md) exist.

Finally, commit your changes and open a pull request:

```bash
git add my-awesome-plugin
git commit -m "Add my-awesome-plugin"

```

## Complete Scaffolding Example

The following bash script creates a minimal valid plugin structure from scratch:

```bash

# 1. Scaffold directories

mkdir -p my-awesome-plugin/.claude-plugin
mkdir -p my-awesome-plugin/skills/example-skill
touch my-awesome-plugin/README.md

# 2. Write the manifest

cat > my-awesome-plugin/.claude-plugin/plugin.json <<'EOF'
{
  "name": "my-awesome-plugin",
  "description": "Provides awesome AI-assisted workflows",
  "version": "0.1.0",
  "license": "MIT",
  "keywords": ["awesome", "plugin", "claude"]
}
EOF

# 3. Add optional MCP configuration

cat > my-awesome-plugin/.mcp.json <<'EOF'
{
  "mcpServers": {
    "my-mcp": {
      "type": "http",
      "url": "https://my-mcp.example.com/streamable",
      "headers": {
        "Authorization": "Bearer ${MY_MCP_TOKEN}"
      }
    }
  }
}
EOF

# 4. Create a skill definition

cat > my-awesome-plugin/skills/example-skill/SKILL.md <<'EOF'
name: example-skill
description: Demonstrates a minimal skill
usage: |
  You can ask the plugin to "echo <text>" and it will return the same text.
EOF

# 5. Add documentation

cat > my-awesome-plugin/README.md <<'EOF'

# My Awesome Plugin

A tiny example plugin showing how to add a custom plugin to the knowledge-work-plugins repo.

## Installation

```bash
claude plugins add my-awesome-plugin@knowledge-work-plugins

```

## Environment

Set `MY_MCP_TOKEN` if you use the bundled MCP server.
EOF

# 6. Validate locally

claude plugin validate my-awesome-plugin/.claude-plugin/plugin.json

```

## Summary

- **Every plugin requires** a [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) manifest with at minimum a `name` field, placed at [`partner-built/your-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/your-plugin/.claude-plugin/plugin.json).
- **MCP servers are optional** but must be declared in [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) if used, not in the main manifest.
- **Skills define AI behavior** through [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files inside the `skills/` directory, parsed by the Claude runtime at load time.
- **Validation is mandatory** via `claude plugin validate` or manual verification before submitting a pull request.
- **Do not edit** the root-level [`.claude-plugin/marketplace.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/marketplace.json); it catalogs external plugins only.

## Frequently Asked Questions

### What is the minimum file structure required for a valid plugin?

The absolute minimum requires a [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) file containing valid JSON with at least a `name` field, and a [`README.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/README.md) file at the plugin root. However, functional plugins typically include a `skills/` directory with at least one [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file to provide actual capabilities to Claude.

### Do I need to update the marketplace.json file when adding a custom plugin?

No. The root-level [`.claude-plugin/marketplace.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/marketplace.json) is reserved for cataloging external plugins. Internal plugins added directly to the `knowledge-work-plugins` repository are discovered through their individual directories and do not require entries in the marketplace file.

### How does Claude discover MCP servers bundled with a plugin?

Claude discovers MCP servers by reading the [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file located at the plugin root during the loading process. The plugin manifest does not contain MCP references; instead, the runtime automatically checks for [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) and initializes any servers defined within it according to the specification used in [`partner-built/zoom-plugin/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/.mcp.json).

### Can I test my plugin locally before submitting a pull request?

Yes. Install the Claude CLI and run `claude plugin validate /path/to/your/.claude-plugin/plugin.json` to verify JSON syntax, required fields, and directory structure. You can also test installation locally using `claude plugins add /absolute/path/to/your/plugin-directory` before committing to the repository.