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

> Discover the vital role of the marketplace.json file in Claude plugins. This manifest file enables automated discovery, integration, and CI validation for the knowledge-work-plugins ecosystem.

- Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins)
- Tags: api-reference
- Published: 2026-05-30

---

**The [`marketplace.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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:

```json
{
  "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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/marketplace.json) and commit the change. The [`scan-plugins.yml`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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:

```javascript
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`:

```bash
#!/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/marketplace.json) catalogs the plugin collection, the file [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) contains top-level metadata for the repository itself, such as the overall package name and version. Together with [`README.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/README.md) and the CI workflows, these files constitute the complete definition of the Claude Knowledge-Work plugin ecosystem.

## Summary

- **[`marketplace.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/marketplace.json)** at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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.