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

To add a custom plugin to the knowledge-work-plugins repository, scaffold a directory containing a .claude-plugin/plugin.json manifest, an optional .mcp.json for MCP server definitions, a skills/ folder with individual SKILL.md files, and a root 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 — 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.
• .mcp.json (Optional) — Declares Model Context Protocol (MCP) servers the plugin bundles, as shown in partner-built/zoom-plugin/.mcp.json.
• skills/ — Directory containing subfolders, each with a SKILL.md file that defines AI-driven capabilities, behavior, and usage examples.
• 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.

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 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.

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

{
  "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 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 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 following the standard format:

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 file contains the complete specification for skill formatting and directory layout conventions.

5. Document and Validate

Write a comprehensive 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:

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, optional .mcp.json, the skills/ directory, and README.md exist.

Finally, commit your changes and open a pull request:

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:

# 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

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.

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