What Is the Role of the marketplace.json File in Claude Knowledge Work Plugins?

The marketplace.json file serves as the central manifest that catalogs all Claude MCP plugins, enabling automated discovery, integration, and CI validation across the knowledge-work-plugins ecosystem.

The marketplace.json file in the anthropics/knowledge-work-plugins repository functions as the backbone of the Claude plugin architecture. Located at .claude-plugin/marketplace.json, this JSON manifest decouples plugin metadata from implementation details, allowing the Claude agent runtime to enumerate available capabilities without loading actual plugin code.

Core Architectural Functions

The manifest fulfills five critical roles within the MCP (Multi-Channel Plugin) ecosystem.

Plugin Catalog

The file maintains the definitive registry of every plugin published by the repository. Each entry in the plugins array specifies a unique name, human-readable displayName, concise description, and source location—either a local path like ./example-plugin or an external Git URL.

Discovery Interface for Claude Agents

When Claude Code or Claude Cowork queries available extensions, the runtime parses marketplace.json to construct the UI list and resolve plugin locations. This discovery mechanism operates entirely from the lightweight metadata, ensuring fast loading and presentation to users.

External Plugin Registration

Third-party plugins hosted in separate repositories integrate seamlessly through the "source": "url" or "git-subdir" properties. The current manifest exposes external integrations including Vanta, Zoom, and Apollo alongside first-party plugins, creating a unified marketplace regardless of code location.

Version-Agnostic Integration

Because marketplace.json contains only metadata pointers rather than implementation logic, plugin authors can evolve their code—adding new skills, updating documentation, or refactoring internals—without modifying the manifest. This separation maintains backward compatibility while allowing rapid iteration.

Automation and CI Validation

The GitHub workflow .github/workflows/scan-plugins.yml reads the manifest to validate plugin structure, generate documentation, and publish updates to the Claude Plugin Store. This automation ensures that every plugin listed in the catalog meets structural requirements before deployment.

Technical Structure and Schema

The manifest follows a predictable schema optimized for both human editing and machine parsing.

Required Fields

Every plugin object within the plugins array must define:

• name: Unique identifier using kebab-case
• displayName: Human-readable title for UI rendering
• source: Path string or object referencing the plugin directory/URL
• description: Brief summary of plugin functionality

Practical Implementation Examples

Adding a New First-Party Plugin

To register a new plugin within the repository, append an object to the plugins array:

{
  "name": "example-plugin",
  "displayName": "Example Plugin",
  "source": "./example-plugin",
  "description": "A demonstration plugin that shows how to extend the marketplace."
}

Place this object inside .claude-plugin/marketplace.json and commit the change. The scan-plugins.yml workflow automatically picks up the addition on the next CI run.

Loading the Manifest Programmatically

Node.js applications can consume the catalog to build dynamic plugin menus:

import { readFile } from 'fs/promises';
import path from 'path';

async function loadMarketplace() {
  const file = path.join(__dirname, '.claude-plugin', 'marketplace.json');
  const raw = await readFile(file, 'utf-8');
  return JSON.parse(raw);
}

// List all available plugin display names
loadMarketplace().then(m => {
  console.log('Available plugins:');
  m.plugins.forEach(p => console.log(`- ${p.displayName}`));
});

Validating Structure in CI Pipelines

Ensure every plugin entry defines a source location using jq:

#!/usr/bin/env bash
set -euo pipefail

MANIFEST=".claude-plugin/marketplace.json"

# Verify every plugin entry has a source field

jq -e '.plugins[] | has("source")' "$MANIFEST" >/dev/null
echo "All plugins define a source – manifest validation passed."

Integration with Repository Metadata

While marketplace.json catalogs the plugin collection, the file .claude-plugin/plugin.json contains top-level metadata for the repository itself, such as the overall package name and version. Together with README.md and the CI workflows, these files constitute the complete definition of the Claude Knowledge-Work plugin ecosystem.

Summary

• marketplace.json at .claude-plugin/marketplace.json acts as the single source of truth for all Claude MCP plugins in the repository.
• The manifest supports both local plugins and external repositories (Vanta, Zoom, Apollo) through flexible source configurations.
• Claude agents rely on this file for runtime discovery and UI generation without loading actual plugin code.
• The .github/workflows/scan-plugins.yml workflow validates the manifest automatically to ensure structural integrity.
• Decoupling metadata from implementation allows plugins to evolve independently while maintaining stable integration points.

Frequently Asked Questions

Where is the marketplace.json file located?

The file resides at .claude-plugin/marketplace.json in the repository root. This location follows the Claude plugin specification, placing manifest files within the hidden .claude-plugin directory to separate plugin metadata from source code.

Can marketplace.json reference plugins hosted outside this repository?

Yes. The source field accepts either local paths (e.g., ./my-plugin) or external references using "source": "url" with optional "git-subdir" specifications. This enables the marketplace to include third-party plugins like Vanta, Zoom, and Apollo alongside native offerings.

What happens if the marketplace.json file is malformed?

The scan-plugins.yml GitHub workflow validates the JSON structure on every push. If required fields like name, displayName, or source are missing or malformed, the CI pipeline fails and blocks publication to the Claude Plugin Store, preventing broken plugins from reaching users.

How does Claude use this file at runtime?

When a user queries available plugins, Claude Code or Claude Cowork loads marketplace.json to enumerate the plugins array. The runtime uses the metadata to render display names and descriptions in the UI, then resolves the source location to load actual plugin logic only when the user selects a specific capability.

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