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

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) enforces. The repository treats each top-level folder as an independent plugin package.

Required Files

Each plugin directory must contain:

• .claude-plugin/plugin.json – Defines the plugin name, description, API specification, authentication method, and required permissions. Reference the template at .claude-plugin/plugin.json in the repository root.
• .claude-plugin/marketplace.json – Supplies marketplace metadata including tags, categories, pricing, and icon paths. See the root template at .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 identifies which plugin directories were added or modified.
2. CLI Validation – 20-validate-cli-marketplace.sh lints plugin.json and marketplace.json against the schema.
3. Auxiliary File Checks – 41-validate-aux-files.sh verifies that required assets (icon, README, SKILL docs) exist.
4. Invariant Enforcement – 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 – API specification and authentication details.
   • marketplace.json – Tags, category, pricing, and icon path.
   • icon.svg – Preferred format is 256×256 SVG.

4. Write skill documentation by creating 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 or 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 defines the technical interface between Claude and your service, while marketplace.json controls how users discover your plugin in the UI.

Creating plugin.json

Place this file at your-plugin/.claude-plugin/plugin.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 at your-plugin/.claude-plugin/marketplace.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 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 – Determines the scope of validation by detecting new or modified plugin directories.
• 20-validate-cli-marketplace.sh – Performs JSON schema validation against the templates in the root .claude-plugin/ directory.
• 41-validate-aux-files.sh – Confirms that auxiliary files like icon.svg and SKILL.md documentation are present and correctly named.
• 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, .claude-plugin/marketplace.json, and an icon file.
• The CI pipeline runs 00-detect-changes.sh, 20-validate-cli-marketplace.sh, 41-validate-aux-files.sh, and 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, marketplace.json, and an icon file, plus SKILL.md documentation under skills/<skill-name>/. The validation script 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 and 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 or missing auxiliary files detected by 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. Only after all checks pass can a maintainer merge your submission.

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