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

Deploying a Claude plugin requires a mandatory .claude-plugin/plugin.json manifest, a 512×512px icon.svg, a root-level 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.

The Core Manifest (plugin.json)

The .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, 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, these fields define how the Claude runtime interacts with your service.

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

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

Skill Documentation (SKILL.md)

For plugins offering multiple capabilities, include 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.

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. 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 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 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 and a license file are required for documentation and legal compliance at the repository root.
• .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 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, .claude-plugin/icon.svg, a root-level 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 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, 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.

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