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

The .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 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 File

The manifest is located at .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 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 file to dynamically discover and load plugins.

Reading with Node.js

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

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:

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:

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 file operates alongside several other configuration files in the repository structure:

• .claude-plugin/marketplace.json: The central manifest describing the entire skill collection and its metadata according to the Anthropic schema.
• .claude-plugin/plugin.json: Individual plugin metadata files located within each plugin directory (e.g., 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 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 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 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.

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