# Documentation Standards for Claude Plugin Marketplace Listings: A Complete Guide

> Master Claude plugin marketplace documentation standards. Ensure discoverability with validated plugin JSON manifest, clear descriptions, keywords, categories, and tags.

- Repository: [Anthropic/claude-plugins-official](https://github.com/anthropics/claude-plugins-official)
- Tags: best-practices
- Published: 2026-03-13

---

**Claude plugin marketplace listings require a validated [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json) manifest with a kebab-case name, 50-200 character description, and 5-10 keywords, plus a separate [`marketplace.json`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json)

The foundation of every marketplace listing is the [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json) manifest defined in [`plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/marketplace.json) Entry

Beyond the core manifest, public distribution requires a marketplace-specific entry documented in [`plugins/plugin-dev/commands/create-plugin.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/commands/create-plugin.md). This entry controls categorization and tagging within the Discover UI.

Create a [`marketplace.json`](https://github.com/anthropics/claude-plugins-official/blob/main/marketplace.json) file in your plugin root (or submit to the global marketplace registry) with these fields:

```json
{
  "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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/marketplace.json) entry is required for public distribution through the Claude plugin marketplace.

## Summary

- **Validate [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/marketplace.json) entry** with a matching description, primary category, and relevant tags for the Discover UI.
- **Follow cross-platform standards** from [`marketplace-considerations.md`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/commands/create-plugin.md).

### What file is required for marketplace publication?

While the [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json) manifest in `.claude-plugin/` is mandatory for any plugin to function, public marketplace distribution requires an additional [`marketplace.json`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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.