# What Is the Purpose of the .claude-plugin/marketplace.json File and How Does It Differ from plugin.json?

> Understand the purpose of .claude-plugin/marketplace.json and its key differences from plugin.json for Claude plugin development and publishing.

- Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer)
- Tags: deep-dive
- Published: 2026-09-12

---

**The [`.claude-plugin/marketplace.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/marketplace.json) file provides publishing-specific metadata for the Claude Marketplace, while [`plugin.json`](https://github.com/blader/humanizer/blob/main/plugin.json) serves as the runtime manifest that Claude Code uses to load and execute the skill.**

The **blader/humanizer** repository demonstrates the dual-manifest architecture required for modern Claude Code skills. Understanding the purpose of the [`.claude-plugin/marketplace.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/marketplace.json) file and how it differs from [`plugin.json`](https://github.com/blader/humanizer/blob/main/plugin.json) is essential for developers packaging skills for distribution through the Claude Marketplace.

## Understanding plugin.json (The Runtime Manifest)

The [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) file acts as the core descriptor that **Claude Code** reads when installing or loading a skill. This manifest tells the runtime engine where to find the skill definition and how to execute it.

According to the source code in `blader/humanizer`, this file contains:

- **$schema**: Points to the Claude Code plugin schema URL
- **name**, **description**, **version**: Basic identification fields
- **author**, **homepage**, **repository**, **license**: Attribution and source information
- **keywords**: Array of searchable terms like `["writing","editing","humanize"]`
- **skills**: Array pointing to the skill folder (typically `["./"]`)

When Claude Code installs the Humanizer skill, it parses this manifest to locate the [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) file and resolve dependencies.

```json
// .claude-plugin/plugin.json
{
  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
  "name": "humanizer",
  "description": "Rewrite AI‑sounding text so it reads naturally without changing what it says.",
  "version": "3.0.0",
  "author": { "name": "blader", "url": "https://github.com/blader" },
  "homepage": "https://github.com/blader/humanizer",
  "repository": "https://github.com/blader/humanizer",
  "license": "MIT",
  "keywords": ["writing","editing","humanize","prose","style"],
  "skills": ["./"]
}

```

## Understanding marketplace.json (The Publishing Manifest)

The [`.claude-plugin/marketplace.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/marketplace.json) file exists solely for the **Claude Marketplace** ingestion service. Unlike the runtime manifest, Claude Code never reads this file during normal skill execution.

This publishing descriptor includes:

- **displayName** and **shortDescription**: Human-readable marketing copy
- **categories**: Classification buckets like `["Writing", "Productivity"]`
- **tags**: Discoverability keywords for search indexing
- **price**: Monetization setting (e.g., "free")
- **previewImage**: URL to visual assets for the listing page
- **manifestVersion**: Optional field specifying the marketplace schema version

When the author submits Humanizer to the marketplace, the service generates the listing page using these fields rather than the technical metadata from [`plugin.json`](https://github.com/blader/humanizer/blob/main/plugin.json).

```json
// .claude-plugin/marketplace.json
{
  "displayName": "Humanizer",
  "shortDescription": "Make AI‑generated prose sound natural.",
  "categories": ["Writing", "Productivity"],
  "tags": ["humanize", "style", "editing"],
  "price": "free",
  "previewImage": "https://github.com/blader/humanizer/raw/main/assets/preview.png"
}

```

## Key Differences Between plugin.json and marketplace.json

The distinction between these manifests is architectural: one serves the runtime, the other serves the store.

**plugin.json** serves as the technical contract for Claude Code. It contains the `$schema` reference, execution instructions via the `skills` array, and machine-readable metadata required to load the Humanizer skill from the `./` directory during runtime.

**marketplace.json** serves as the marketing contract for the Claude Marketplace. It provides human-readable fields like `displayName` and `shortDescription`, along with categorization tags that drive search discoverability in the store.

The files coexist without conflict because each consumer looks exclusively for its own manifest. Claude Code never parses [`marketplace.json`](https://github.com/blader/humanizer/blob/main/marketplace.json), and the marketplace ingestion service ignores [`plugin.json`](https://github.com/blader/humanizer/blob/main/plugin.json) beyond basic validation checks.

## File Organization in the blader/humanizer Repository

Both manifest files reside in the hidden `.claude-plugin` directory at the repository root. This location follows the Claude Code convention for skill packaging, keeping implementation details organized while remaining discoverable by both the runtime engine and marketplace tools.

The actual skill logic resides in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), which the manifests reference indirectly—[`plugin.json`](https://github.com/blader/humanizer/blob/main/plugin.json) points to it via the `skills` array, while [`marketplace.json`](https://github.com/blader/humanizer/blob/main/marketplace.json) describes its utility to potential users.

The repository includes [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) to ensure both JSON manifests stay synchronized with the skill version. This validation script prevents submission errors by checking that metadata fields remain consistent between the runtime and publishing descriptors.

## Summary

- **[`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json)** is the runtime manifest Claude Code uses to load, validate, and execute the Humanizer skill.
- **[`.claude-plugin/marketplace.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/marketplace.json)** is the publishing manifest the Claude Marketplace consumes to generate listing pages and enable search discoverability.
- **Claude Code** ignores [`marketplace.json`](https://github.com/blader/humanizer/blob/main/marketplace.json) during execution, while the **Marketplace service** ignores [`plugin.json`](https://github.com/blader/humanizer/blob/main/plugin.json) during ingestion.
- The repository uses [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) to ensure both manifests remain synchronized.
- Both files reside in the hidden `.claude-plugin` directory but serve completely different architectural purposes.

## Frequently Asked Questions

### Does Claude Code read marketplace.json during skill execution?

No. Claude Code only parses [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) when loading the skill. The [`marketplace.json`](https://github.com/blader/humanizer/blob/main/marketplace.json) file is consumed exclusively by the marketplace ingestion service and remains inert during runtime execution.

### Can I publish a Claude Code skill without a marketplace.json file?

Yes, for private or local distribution. However, submitting to the Claude Marketplace requires [`marketplace.json`](https://github.com/blader/humanizer/blob/main/marketplace.json) to provide the display name, categories, and tags necessary for generating the public listing page.

### What happens if the versions in plugin.json and marketplace.json disagree?

The validation script [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) in the repository prevents this by checking manifest synchronization before submission. Discrepancies would cause marketplace rejection or runtime confusion about skill capabilities.

### Why does the Humanizer repository store both files in a hidden directory?

The `.claude-plugin` directory follows the Claude Code convention for skill packaging. Prefixing with a dot hides implementation details from end users while keeping metadata discoverable by both the runtime engine and marketplace ingestion tools.