How to Configure a Claude Plugin Manifest: Complete Guide for the pm-skills Repository

A Claude plugin manifest is a JSON configuration file stored in .claude-plugin/plugin.json that defines the plugin's identity, version, author metadata, and keywords, while a marketplace manifest aggregates multiple plugins for distribution.

Configuring a Claude plugin manifest is the essential first step to distribute custom skills for Claude Code. In the phuryn/pm-skills repository, each plugin follows a strict schema defined in its own .claude-plugin/plugin.json file, while a top-level marketplace manifest coordinates the entire collection for easy installation.

Single-Plugin Manifest Structure

Each individual plugin requires its own manifest file to define its metadata and discovery properties. According to the source code in phuryn/pm-skills, this file must reside at .claude-plugin/plugin.json within the plugin's root folder.

Core Metadata Fields

The manifest requires specific fields that define the plugin's identity:

• name: The unique identifier used in CLI commands (e.g., "pm-toolkit")
• version: Semantic version string (e.g., "2.0.0")
• description: Human-readable summary displayed in the plugin browser
• author: Object containing name, email, and optional url
• keywords: Array of search tags for discovery (e.g., ["product-management", "resume"])
• homepage: Documentation URL
• license: SPDX license identifier (e.g., "MIT")

Example: pm-toolkit Plugin Manifest

The pm-toolkit plugin demonstrates the complete schema as implemented in pm-toolkit/.claude-plugin/plugin.json:

{
  "name": "pm-toolkit",
  "version": "2.0.0",
  "description": "PM utility skills: resume review, NDA drafting, privacy policy generation, and grammar/flow checking. Essential tools for product managers beyond core product work.",
  "author": {
    "name": "Paweł Huryn",
    "email": "[email protected]",
    "url": "https://www.productcompass.pm"
  },
  "keywords": [
    "product-management",
    "resume",
    "legal",
    "nda",
    "privacy-policy",
    "copywriting"
  ],
  "homepage": "https://www.productcompass.pm",
  "license": "MIT"
}

Marketplace Manifest Configuration

To distribute multiple plugins as a collection, you must configure a marketplace manifest at the repository root. This file, .claude-plugin/marketplace.json, aggregates all plugins so users can install the entire suite with a single command.

Required Marketplace Fields

The marketplace manifest extends the single-plugin schema with these additional fields:

• $schema: URL pointing to https://anthropic.com/claude-code/marketplace.schema.json
• name: Marketplace identifier (e.g., "pm-skills")
• owner: Author object with the same structure as single-plugin authors
• plugins: Array of plugin descriptors, each containing name, description, source (relative path), and category

Example: pm-skills Marketplace Manifest

The top-level configuration references individual plugins using relative paths. Here is the structure from .claude-plugin/marketplace.json:

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "pm-skills",
  "version": "2.0.0",
  "description": "Structured AI workflows for better product decisions",
  "owner": {
    "name": "Paweł Huryn",
    "email": "[email protected]",
    "url": "https://www.productcompass.pm"
  },
  "plugins": [
    {
      "name": "pm-toolkit",
      "description": "PM utility skills: resume review, NDA drafting, privacy policy generation, and grammar/flow checking.",
      "source": "./pm-toolkit",
      "category": "product-management"
    },
    {
      "name": "pm-ai-shipping",
      "description": "AI-assisted shipping skills for product managers.",
      "source": "./pm-ai-shipping",
      "category": "product-management"
    }
  ]
}

After committing this file, users can install the entire marketplace by running:

claude plugin marketplace add phuryn/pm-skills

Step-by-Step: Adding a New Plugin

To configure a new plugin manifest and register it in the marketplace:

1. Create the plugin directory (e.g., pm-new-feature/)
2. Initialize the manifest at pm-new-feature/.claude-plugin/plugin.json with all required fields
3. Add content to skills/ and optional commands/ directories as markdown files
4. Register in marketplace by appending an entry to the plugins array in .claude-plugin/marketplace.json:

{
  "name": "pm-new-feature",
  "description": "New-feature utilities for product managers.",
  "source": "./pm-new-feature",
  "category": "product-management"
}

Validation and Installation

Claude validates manifests against the JSON schema at install time. Common configuration errors include missing required fields (name, version, description), invalid SPDX license identifiers, or incorrect directory structure.

To validate a manifest manually:

SCHEMA_URL="https://anthropic.com/claude-code/marketplace.schema.json"
curl -s $SCHEMA_URL | \
  jq -e 'input | . == (input | .)' \
  --argjson manifest "$(cat .claude-plugin/marketplace.json)" \
  > /dev/null && echo "Manifest is valid"

To install and test:

# Install entire marketplace

claude plugin marketplace add phuryn/pm-skills

# Install specific plugin

claude plugin install pm-toolkit@pm-skills

Summary

• Single-plugin manifests live in .claude-plugin/plugin.json and define metadata, authorship, and keywords
• Marketplace manifests aggregate plugins via the plugins array in .claude-plugin/marketplace.json
• Required fields include name, version, description, author, and license for plugins; $schema, name, and plugins for marketplaces
• Relative paths in the source field connect marketplace entries to plugin directories
• Validation occurs automatically during claude plugin install against the Anthropic schema

Frequently Asked Questions

What is the difference between a plugin manifest and a marketplace manifest?

A plugin manifest (plugin.json) describes a single plugin's metadata and capabilities, while a marketplace manifest (marketplace.json) aggregates multiple plugins into a distributable collection. The marketplace file uses the plugins array to reference individual plugin directories via relative paths like "./pm-toolkit".

Where must the plugin.json file be located within a plugin directory?

Claude expects the manifest at .claude-plugin/plugin.json relative to the plugin's root folder. For example, in the phuryn/pm-skills repository, the pm-toolkit plugin manifest is located at pm-toolkit/.claude-plugin/plugin.json, and the pm-ai-shipping manifest is at pm-ai-shipping/.claude-plugin/plugin.json.

How do I validate a Claude plugin manifest before publishing?

Claude validates manifests against the schema at install time. You can manually verify using jq to compare against the remote schema at https://anthropic.com/claude-code/marketplace.schema.json. Common validation failures include missing required fields, invalid SPDX license identifiers, or malformed JSON syntax.

Can I install individual plugins from a marketplace without installing the entire collection?

Yes. After adding the marketplace with claude plugin marketplace add phuryn/pm-skills, you can install specific plugins using the claude plugin install <name>@<marketplace> syntax, such as claude plugin install pm-toolkit@pm-skills.

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