Documentation Standards for Claude Plugin Marketplace Listings: A Complete Guide

Claude plugin marketplace listings require a validated plugin.json manifest with a kebab-case name, 50-200 character description, and 5-10 keywords, plus a separate marketplace.json entry defining category and tags for discoverability.

The anthropics/claude-plugins-official repository defines strict documentation standards that ensure every Claude Code plugin displays correctly in the Discover UI and remains discoverable through search. These standards split metadata between the authoritative plugin.json manifest—located in .claude-plugin/—and the marketplace-specific entry that controls categorization and presentation. Following these specifications ensures your plugin passes validation and provides a consistent first impression for users.

Core Manifest Structure in plugin.json

The foundation of every marketplace listing is the plugin.json manifest defined in plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md. This file serves as the single source of truth for the Claude Code client when rendering plugin details.

Required Fields and Validation Rules

Every manifest must include validated fields that control both functionality and marketplace display:

• name: Must match the regex /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/ (kebab-case, lowercase, starting with a letter). This identifier must be unique across the marketplace.
• version: Strict semantic versioning (MAJOR.MINOR.PATCH) as consumed by the dependency resolver.
• description: 50-200 characters, ideally kept under 200 characters to prevent truncation in the marketplace UI. Use active voice and focus on core benefits.
• keywords: Array of 5-10 relevant terms that improve search discoverability. Include technology names (e.g., "github", "python") and functional categories (e.g., "lint", "security").

Author and Repository Metadata

The manifest must also establish provenance and support channels:

• author: Object containing name, optional email, and optional url.
• homepage: URL pointing to documentation or the project website.
• repository: Direct link to the source code (typically GitHub).
• license: SPDX license identifier (e.g., "MIT", "Apache-2.0").

Optimizing Your Marketplace Description

The description field in plugin.json functions as your plugin's elevator pitch. According to the manifest reference, descriptions exceeding 200 characters risk truncation in the Claude Code Discover UI.

Write descriptions using active voice and front-load the value proposition. Instead of "This plugin can be used to review code," use "Automates code-review feedback with style checks and security analysis." Include specific technologies or platforms (e.g., "GitHub", "Python") only if they are primary dependencies, as these terms also function as search keywords.

Creating the marketplace.json Entry

Beyond the core manifest, public distribution requires a marketplace-specific entry documented in plugins/plugin-dev/commands/create-plugin.md. This entry controls categorization and tagging within the Discover UI.

Create a marketplace.json file in your plugin root (or submit to the global marketplace registry) with these fields:

{
  "description": "Automates code-review feedback with style checks, security analysis, and inline suggestions.",
  "category": "code-review",
  "tags": [
    "lint",
    "security",
    "automation",
    "github"
  ]
}

The category field should match one of the official taxonomy values (e.g., documentation, code-review, testing). The tags array supports granular discoverability beyond the fixed categories. Ensure the description here mirrors your plugin.json description to maintain consistency across the CLI and web interfaces.

Cross-Platform Compatibility and UX Standards

Plugins distributed through the marketplace must adhere to platform-agnostic design principles defined in plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md.

Avoid platform-specific commands that assume a particular operating system or shell. Instead, use abstractions available through the Claude Code SDK or include graceful degradation logic that detects the environment and adjusts behavior accordingly.

Provide clear onboarding in your README.md. The marketplace considerations document emphasizes that unknown users need immediate context on what the plugin does and how to invoke its first command. Include a "First run" section that demonstrates the primary slash command with example output.

Complete Plugin Directory Structure

A marketplace-ready plugin follows this structure, with only plugin.json being strictly mandatory:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          ← manifest (core metadata)
├── .mcp.json                ← optional MCP server config
├── commands/
│   └── review.md            ← slash command definition
├── agents/
│   └── code-reviewer.md     ← optional agent
├── skills/
│   └── code-review/
│       └── SKILL.md         ← skill definition
├── marketplace.json         ← marketplace entry (description, category, tags)
└── README.md                ← user-facing documentation

As noted in the plugin structure reference, all files except the manifest are optional for private use, but the marketplace.json entry is required for public distribution through the Claude plugin marketplace.

Summary

• Validate plugin.json strictly: Use kebab-case names matching /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, semantic versions, and descriptions under 200 characters.
• Include 5-10 keywords in the manifest to improve search discoverability within Claude Code.
• Create a marketplace.json entry with a matching description, primary category, and relevant tags for the Discover UI.
• Follow cross-platform standards from marketplace-considerations.md to ensure compatibility across operating systems.
• Provide clear onboarding in your README to help first-time users understand the plugin's value and initial commands.

Frequently Asked Questions

What is the maximum length for a Claude plugin description?

The description field in plugin.json must be between 50 and 200 characters according to the manifest reference in plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md. Descriptions exceeding 200 characters risk truncation in the Claude Code Discover UI, while those under 50 characters may lack sufficient context for users.

How do I validate my plugin name before submission?

The name field must match the regex /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/ as defined in the manifest reference documentation. This enforces kebab-case formatting starting with a lowercase letter. You can validate your chosen identifier using any regex tester or by running the Claude Code plugin validation tools referenced in plugins/plugin-dev/commands/create-plugin.md.

What file is required for marketplace publication?

While the plugin.json manifest in .claude-plugin/ is mandatory for any plugin to function, public marketplace distribution requires an additional marketplace.json file (or entry in the global marketplace registry). This file contains the category, tags, and display description used by the Discover UI, as documented in plugins/plugin-dev/commands/create-plugin.md under the "Add marketplace entry" section.

Are there restrictions on plugin commands for marketplace distribution?

Yes. According to plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md, marketplace plugins must avoid platform-specific commands that assume particular operating systems or shell environments. Commands should include graceful degradation logic to handle different environments, and plugins must provide clear onboarding documentation to help first-time users understand how to invoke commands immediately after installation.

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