# How to Deploy a Claude Plugin: Required Files, Structure, and Validation Pipeline

> Deploy a Claude plugin with a manifest file, icon, README, and license. Learn the validation pipeline for successful integration into the community repository.

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

---

**Deploying a Claude plugin requires a mandatory [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) manifest, a 512×512px `icon.svg`, a root-level [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md), an open-source license, and passage through the `validate-plugins` GitHub Actions workflow before merging into the `anthropics/claude-plugins-community` repository.**

Deploying a Claude plugin to the community marketplace demands strict adherence to a specific directory layout and metadata schema. The `anthropics/claude-plugins-community` repository serves as the central hub where all plugins follow a standardized structure validated by continuous integration. Understanding these deployment requirements ensures your plugin passes automated checks and becomes discoverable to Claude users.

## Mandatory Files for Deploying a Claude Plugin

Every plugin submission must include specific files in precise locations. The repository enforces these requirements through automated validation in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml).

### The Core Manifest (plugin.json)

The [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) file serves as the primary entry point that tells Claude how to load and invoke your plugin. Located at [`plugin-directory/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin-directory/.claude-plugin/plugin.json), this JSON file must include the `name`, `description`, `version`, `author`, `api` configuration, and `entrypoint` fields. As implemented in [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json), these fields define how the Claude runtime interacts with your service.

```json
{
  "name": "my-plugin",
  "description": "A short description of what the plugin does.",
  "version": "0.1.0",
  "author": "Your Name <you@example.com>",
  "api": {
    "type": "openapi",
    "url": "https://my-plugin.example.com/openapi.json"
  },
  "entrypoint": "src/index.js"
}

```

### Visual Identity (icon.svg)

A 512×512 pixel **SVG icon** is required for marketplace listings. The file must reside at `.claude-plugin/icon.svg`. As seen in the `quickdesign` plugin example at `quickdesign/.claude-plugin/icon.svg`, this graphic represents your plugin in the Claude UI and must be a valid SVG document with precise dimensions.

```svg
<svg width="512" height="512" xmlns="http://www.w3.org/2000/svg">
  <rect width="512" height="512" fill="#4A90E2"/>
  <text x="256" y="310" font-size="200" text-anchor="middle" fill="#FFF">🛠️</text>
</svg>

```

### Documentation and Legal Requirements

Your plugin directory must contain a top-level [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md) explaining functionality, configuration steps, and usage limits. Additionally, an open-source license file (e.g., MIT) must be present in the repository root to grant usage rights, as seen in the main `LICENSE` file governing the entire `anthropics/claude-plugins-community` repository.

## Optional Files That Enhance Discoverability

While not blocking deployment, these files improve user experience and marketplace visibility.

### Marketplace Metadata (marketplace.json)

The [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) file controls how your plugin appears in the Claude Marketplace. It supports `categories`, `tags`, `pricing` (free or paid), and `visibility` settings. The `quickdesign` plugin demonstrates this configuration at [`quickdesign/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/marketplace.json).

```json
{
  "categories": ["productivity", "finance"],
  "tags": ["budget", "expenses"],
  "pricing": "free",
  "visibility": "public"
}

```

### Skill Documentation (SKILL.md)

For plugins offering multiple capabilities, include [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files in skill-specific subdirectories. These Markdown files help Claude generate accurate responses when using your plugin's features, as implemented in [`tres-finance-plugin/skills/tres-wallets-upload/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md).

## The Validation Pipeline and CI Requirements

Before deploying a Claude plugin, all submissions must pass the `validate-plugins` GitHub Actions workflow defined in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml). This CI job checks that manifests conform to the required schema, validates that mandatory fields exist, and ensures the plugin can be packaged successfully.

### The Pull Request Workflow

The deployment process follows these specific steps:

1. Create a dedicated plugin directory (e.g., `my-plugin/`).
2. Add mandatory manifests and assets including [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and `icon.svg`.
3. Commit changes and open a pull request against the `main` branch.
4. GitHub CI automatically runs the validation workflow.
5. Once CI passes, maintainers merge the PR, making the plugin discoverable in Claude's plugin catalog.

If any required files are missing or malformed, the CI validation fails immediately, blocking deployment until issues are resolved.

## Summary

- **[`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)** is the mandatory manifest defining plugin metadata, API configuration, and entry points.
- **`.claude-plugin/icon.svg`** must be a 512×512px SVG located in the `.claude-plugin` directory for UI representation.
- **[`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md)** and a **license file** are required for documentation and legal compliance at the repository root.
- **[`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)** is optional but necessary for marketplace visibility, categorization, and pricing configuration.
- The **`validate-plugins`** CI workflow in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) enforces schema compliance and blocks merging if validation fails.

## Frequently Asked Questions

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

At minimum, you must provide [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json), `.claude-plugin/icon.svg`, a root-level [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md), and an open-source license file. These files must follow the directory structure demonstrated in the `tres-finance-plugin` and `quickdesign` examples within the `anthropics/claude-plugins-community` repository.

### Is the marketplace.json file required to deploy a Claude plugin?

No, [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) is optional for basic deployment but required if you want your plugin listed in the Claude Marketplace with categories, tags, and pricing information. Without it, your plugin may not appear in public discovery surfaces even if technically functional.

### How does the CI validation process work for Claude plugins?

The repository runs a `validate-plugins` GitHub Actions workflow automatically on every pull request. This validation checks schema compliance for [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json), verifies required fields are present, validates the SVG icon dimensions, and ensures the plugin package can be built. Failed checks block merging into the `main` branch until resolved.

### What image format and size are required for the plugin icon?

Claude plugins require a **512×512 pixel SVG file** located at `.claude-plugin/icon.svg`. The vector format ensures crisp display across all UI densities, and the specific dimensions maintain consistency with other marketplace listings in the Claude interface.