# How to Submit a Plugin to the Claude Plugin Marketplace: A Step-by-Step Guide

> Submit your plugin to the Claude plugin marketplace with this step-by-step guide. Fork the community repo, add your plugin files, and open a PR for validation. Get started today!

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-08-27

---

**To submit a plugin to the Claude plugin marketplace, fork the `anthropics/claude-plugins-community` repository, create a new plugin directory with the required `.claude-plugin` configuration files, and open a Pull Request for automated CI validation.**

The Claude Plugin Marketplace is built directly from the open-source **claude-plugins-community** repository. When you submit a plugin to the Claude plugin marketplace via GitHub Pull Request, the automated validation pipeline checks your code against strict schema requirements before merging it into the main branch and publishing it live.

## Prerequisites and Repository Structure

Every plugin submission must follow a strict directory layout that the CI validation workflow ([`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml)) enforces. The repository treats each top-level folder as an independent plugin package.

### Required Files

Each plugin directory must contain:

- **[`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)** – Defines the plugin name, description, API specification, authentication method, and required permissions. Reference the template at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) in the repository root.
- **[`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)** – Supplies marketplace metadata including tags, categories, pricing, and icon paths. See the root template at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json).
- **`.claude-plugin/icon.svg`** (or PNG) – A 256×256 visual identifier displayed in the UI.
- **`skills/<skill-name>/SKILL.md`** – Human-readable documentation describing API endpoints and usage instructions.

### Validation Workflow Overview

When you open a Pull Request, the **validate-plugins** workflow runs four distinct phases:

1. **Change Detection** – [`00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/00-detect-changes.sh) identifies which plugin directories were added or modified.
2. **CLI Validation** – [`20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/20-validate-cli-marketplace.sh) lints [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) against the schema.
3. **Auxiliary File Checks** – [`41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/41-validate-aux-files.sh) verifies that required assets (icon, README, SKILL docs) exist.
4. **Invariant Enforcement** – [`11-validate-invariants.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/11-validate-invariants.sh) checks repository-wide rules such as unique plugin IDs and SHA hash integrity.

Only after all four scripts succeed will the CI mark your PR as ready for maintainer review.

## Step-by-Step Submission Process

Follow these exact steps to submit your plugin without CI rejections:

1. **Fork the repository** to your personal GitHub account from `anthropics/claude-plugins-community`.

2. **Create a new top-level directory** for your plugin (e.g., `my-awesome-plugin/`). The folder name becomes the plugin identifier.

3. **Add the `.claude-plugin` subdirectory** containing:
   - [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) – API specification and authentication details.
   - [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) – Tags, category, pricing, and icon path.
   - `icon.svg` – Preferred format is 256×256 SVG.

4. **Write skill documentation** by creating [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files under `skills/<skill-name>/`. Use Markdown to document request/response shapes and endpoint descriptions.

5. **Run local validation** (optional) by executing the same Bash scripts used in CI or using the `./mcp validate` wrapper to catch errors before pushing.

6. **Commit and push** your new plugin folder to your forked repository.

7. **Open a Pull Request** against the `main` branch of `anthropics/claude-plugins-community`.

8. **Wait for automated checks** – The GitHub Actions workflow triggers automatically on PR creation.

9. **Fix any validation errors** – If [`20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/20-validate-cli-marketplace.sh) or [`41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/41-validate-aux-files.sh) reports failures, commit fixes to your branch and push to re-run the workflow.

10. **Await maintainer merge** – Once CI passes, a repository maintainer will review and merge your PR. The plugin appears in the Claude Plugin Marketplace within minutes of merging.

## Plugin Configuration Files

Your [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) defines the technical interface between Claude and your service, while [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) controls how users discover your plugin in the UI.

### Creating plugin.json

Place this file at [`your-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/your-plugin/.claude-plugin/plugin.json):

```json
{
  "name": "My Awesome Plugin",
  "description": "Provides awesome data retrieval for Claude.",
  "api": {
    "base_url": "https://api.myawesome.com/v1",
    "auth": {
      "type": "api_key",
      "header_name": "X-API-Key"
    },
    "endpoints": [
      {
        "name": "get_awesome_data",
        "method": "GET",
        "path": "/awesome",
        "parameters": [
          { "name": "query", "type": "string", "required": true }
        ],
        "response_schema": {
          "type": "object",
          "properties": {
            "result": { "type": "string" }
          },
          "required": ["result"]
        }
      }
    ]
  },
  "version": "0.1.0"
}

```

### Configuring marketplace.json

Place this alongside [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) at [`your-plugin/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/your-plugin/.claude-plugin/marketplace.json):

```json
{
  "tags": ["data", "search"],
  "category": "Utility",
  "price_usd": 0,
  "icon_path": "icon.svg",
  "author": "Your Name",
  "homepage": "https://github.com/yourname/my-awesome-plugin"
}

```

## Understanding the CI Validation Pipeline

The validation logic in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) ensures that only properly structured plugins reach the marketplace. The pipeline uses modular Bash scripts located in `.github/actions/validate-plugins/scripts/`:

- **[`00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/00-detect-changes.sh)** – Determines the scope of validation by detecting new or modified plugin directories.
- **[`20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/20-validate-cli-marketplace.sh)** – Performs JSON schema validation against the templates in the root `.claude-plugin/` directory.
- **[`41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/41-validate-aux-files.sh)** – Confirms that auxiliary files like `icon.svg` and [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) documentation are present and correctly named.
- **[`11-validate-invariants.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/11-validate-invariants.sh)** – Enforces global constraints such as unique plugin identifiers and valid SHA hashes.

If any script exits with a non-zero status, the PR check fails and must be corrected before maintainers can merge.

## Summary

- Submit a plugin to the Claude plugin marketplace by opening a PR to `anthropics/claude-plugins-community` with a new directory containing [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json), [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), and an icon file.
- The CI pipeline runs [`00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/00-detect-changes.sh), [`20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/20-validate-cli-marketplace.sh), [`41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/41-validate-aux-files.sh), and [`11-validate-invariants.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/11-validate-invariants.sh) to enforce schema compliance and file completeness.
- Once validation passes and maintainers merge your PR, the plugin automatically publishes to the marketplace within minutes.
- Study the `quickdesign/` example directory in the repository for a complete, working implementation of the required file structure.

## Frequently Asked Questions

### What file structure is required for a Claude plugin marketplace submission?

You must create a top-level directory containing a `.claude-plugin/` subdirectory with [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json), [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json), and an icon file, plus [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) documentation under `skills/<skill-name>/`. The validation script [`41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/41-validate-aux-files.sh) checks for these exact paths during CI.

### How long does it take for my plugin to appear in the marketplace after submission?

Once your Pull Request passes all CI checks (including [`20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/20-validate-cli-marketplace.sh) and [`11-validate-invariants.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/11-validate-invariants.sh)) and a maintainer merges it, the plugin appears in the Claude Plugin Marketplace within a few minutes. The marketplace generation pipeline reads the committed files immediately after merge.

### Can I test my plugin locally before submitting a Pull Request?

Yes, you can run the same validation scripts locally that execute in CI. Execute the Bash scripts in `.github/actions/validate-plugins/scripts/` directly, or use the `./mcp validate` wrapper command if available in your fork. This catches JSON schema errors and missing file issues before opening your PR.

### What happens if the CI validation fails on my Pull Request?

If any validation step fails—such as JSON linting in [`20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/20-validate-cli-marketplace.sh) or missing auxiliary files detected by [`41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/41-validate-aux-files.sh)—the PR will show a failing check status. You must push fixes to your branch, which automatically re-triggers the workflow in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml). Only after all checks pass can a maintainer merge your submission.