# What Information Is Included in the `.claude-plugin/marketplace.json` File?

> Discover what the marketplace.json file includes for Claude Code skills. Learn about schema validation, metadata, contact info, and plugin descriptors for your collection.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: api-reference
- Published: 2026-09-12

---

**The [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) file serves as the central manifest that describes a Claude Code skill collection, containing schema validation, package metadata, owner contact information, and a detailed array of plugin descriptors including names, versions, source paths, and categories.**

In the `humanlayer/skills` repository, the **[`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json)** file acts as the single source of truth for the Claude Code marketplace. This JSON manifest validates against Anthropic's official schema and defines everything required to publish, version, and discover the collection of skills contained in the repository.

## Structure of the [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) File

The manifest is located at [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) and validates against the schema at `https://anthropic.com/claude-code/marketplace.schema.json`. It organizes information into five top-level sections.

### Schema and Package Identity

The **`$schema`** field provides the URL for JSON schema validation, while the **`name`** field identifies the marketplace package itself. For the HumanLayer collection, this value is `"skills"`.

### Owner Information

The **`owner`** object contains contact details for the publishing organization. It includes a `name` (e.g., `"humanlayer"`) and an `email` address (e.g., `"support@humanlayer.dev"`).

### Metadata Section

The **`metadata`** object provides general package information including a `description` of the collection and a semantic `version` string. The HumanLayer manifest describes this as `"Claude Code skills from HumanLayer"` with version `"1.0.0"`.

### Plugins Array

The **`plugins`** array contains individual descriptors for each skill. Every plugin entry includes:

- **`name`**: The unique identifier used in the marketplace
- **`description`**: A human-readable summary of functionality
- **`version`**: Semantic version of the individual plugin
- **`author`**: Name and contact information for the plugin creator
- **`source`**: Relative path to the plugin folder within the repository
- **`category`**: Broad functional classification (e.g., *productivity*)
- **`keywords`**: Discovery tags for search and filtering

## Plugins Defined in the HumanLayer Manifest

The current manifest defines five distinct Claude Code skills:

**improve-claude-md**
Rewrites a [`CLAUDE.md`](https://github.com/humanlayer/skills/blob/main/CLAUDE.md) file using `<important if>` blocks to improve instruction adherence. Source: `./plugins/improve-claude-md`

**narrow-react-prop-types**
Narrows React component prop types to match live code paths. Source: `./plugins/narrow-react-prop-types`

**build-iterated-agentic-loop**
Constructs a repo-local skill with an iterated coding-agent workflow, prompt, and memory file. Source: `./plugins/build-iterated-agentic-loop`

**design-control-loop**
Interviews users to design agentic control loops (sensor, controller, actuator under disturbances) and generates runnable components plus scheduled workflows. Source: `./plugins/design-control-loop`

**show-me**
Explains current topics with concise diagrams, code-shape sketches, and focused HTML artifacts. Source: `./plugins/show-me`

## How to Read and Use the Manifest

Downstream tools can consume the [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) file to dynamically discover and load plugins.

### Reading with Node.js

Use the built-in `fs/promises` module to parse the manifest:

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

async function loadMarketplace() {
  const file = path.resolve('.claude-plugin', 'marketplace.json');
  const raw = await readFile(file, 'utf8');
  const manifest = JSON.parse(raw);
  console.log('Marketplace name:', manifest.name);
  console.log('Available plugins:');
  manifest.plugins.forEach(p => console.log(`- ${p.name} (${p.version}): ${p.description}`));
}
loadMarketplace();

```

### Extracting Data with jq

For quick terminal inspection, use `jq` to extract plugin names:

```bash
jq -r '.plugins[].name' .claude-plugin/marketplace.json

```

This outputs:

```

improve-claude-md
narrow-react-prop-types
build-iterated-agentic-loop
design-control-loop
show-me

```

### Dynamic Loading in Python

Load a specific plugin dynamically using the `source` path:

```python
import json, importlib.util, pathlib

with open('.claude-plugin/marketplace.json') as f:
    manifest = json.load(f)

def load_plugin(name):
    for p in manifest['plugins']:
        if p['name'] == name:
            src = pathlib.Path(p['source'])
            spec = importlib.util.spec_from_file_location(name, src / '__init__.py')
            mod = importlib.util.module_from_spec(spec)
            spec.loader.exec_module(mod)
            return mod
    raise ValueError(f'Plugin {name} not found')

show_me = load_plugin('show-me')
show_me.run()

```

## Relationship to Other Configuration Files

The [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) file operates alongside several other configuration files in the repository structure:

- **[`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json)**: The central manifest describing the entire skill collection and its metadata according to the Anthropic schema.
- **[`.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/plugin.json)**: Individual plugin metadata files located within each plugin directory (e.g., [`plugins/improve-claude-md/.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/.claude-plugin/plugin.json)).
- **`plugins/**/SKILL.md`**: Human-readable documentation specific to each skill's functionality.
- **`plugins/**/README.md`**: Additional usage instructions for individual plugins when present.

## Summary

- The [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) file is the **mandatory manifest** for Claude Code skill collections published to the marketplace.
- It validates against the Anthropic schema at `https://anthropic.com/claude-code/marketplace.schema.json`.
- The file contains **package identity** (`name`), **ownership** (`owner`), **versioning** (`metadata`), and a complete **plugin registry** (`plugins` array).
- Each plugin descriptor specifies the `source` path, `category`, `keywords`, and `version` required for discovery and loading.
- The `humanlayer/skills` repository uses this file to expose five distinct skills for enhancing Claude Code workflows.

## Frequently Asked Questions

### What is the purpose of the `$schema` field in marketplace.json?

The `$schema` field provides the URL to the JSON Schema that validates the structure of the manifest. This ensures the file conforms to Anthropic's official Claude Code marketplace specification before publication.

### How does the `source` field in a plugin descriptor work?

The `source` field contains a relative path from the repository root to the plugin folder. This allows automated tools to locate the plugin's code, documentation, and entry points (such as [`__init__.py`](https://github.com/humanlayer/skills/blob/main/__init__.py) or executable scripts) dynamically.

### Can a marketplace.json file contain multiple categories for a single plugin?

The `category` field in each plugin descriptor accepts a single broad functional classification string. While a plugin can only have one primary category, the `keywords` array allows for multiple discovery tags to improve searchability across different contexts.

### Where does the [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) file need to be located?

The file must reside in the `.claude-plugin/` directory at the repository root. This specific path is required by the Claude Code marketplace indexing system to identify and process the skill collection manifest.