[BUG] JSON schema specified in the marketplace.json doesn't exist

Any updates on this @ashwin-ant ?

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

It's still occurring.

Can you look into this @ashwin-ant ?

any updates ?

on my side Claude Code v2.0.76 with Opus 4.5 outputs

marketplace.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://anthropic.com/claude-code/marketplace.schema.json",
  "title": "Claude Code Plugin Marketplace",
  "description": "Schema for Claude Code plugin marketplace configuration",
  "type": "object",
  "required": ["$schema", "name", "description", "owner", "plugins"],
  "properties": {
    "$schema": {
      "type": "string",
      "description": "JSON Schema reference URL"
    },
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "Unique marketplace identifier (lowercase, alphanumeric with hyphens)"
    },
    "description": {
      "type": "string",
      "minLength": 10,
      "maxLength": 500,
      "description": "Human-readable marketplace description"
    },
    "owner": {
      "$ref": "#/definitions/Owner"
    },
    "plugins": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Plugin"
      },
      "minItems": 1,
      "description": "List of plugins available in this marketplace"
    }
  },
  "definitions": {
    "Owner": {
      "type": "object",
      "required": ["name", "email"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Owner name (person or organization)"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Contact email address"
        }
      }
    },
    "Author": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Author name"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Author email (optional)"
        }
      }
    },
    "Plugin": {
      "type": "object",
      "required": ["name", "description", "version", "source"],
      "properties": {
        "name": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9-]*$",
          "description": "Unique plugin identifier"
        },
        "description": {
          "type": "string",
          "minLength": 10,
          "maxLength": 500,
          "description": "Human-readable plugin description"
        },
        "version": {
          "type": "string",
          "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
          "description": "Semantic version (e.g., 1.0.0, 0.1.0-beta)"
        },
        "source": {
          "type": "string",
          "description": "Relative path to plugin directory"
        },
        "author": {
          "$ref": "#/definitions/Author"
        },
        "category": {
          "type": "string",
          "enum": ["development", "productivity", "utilities"],
          "description": "Plugin category for discovery"
        },
        "homepage": {
          "type": "string",
          "format": "uri",
          "description": "Project homepage URL"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9-]*$"
          },
          "description": "Searchable keywords"
        },
        "lspServers": {
          "type": "object",
          "description": "Inline LSP server configuration",
          "additionalProperties": {
            "$ref": "#/definitions/LSPServer"
          }
        }
      }
    },
    "LSPServer": {
      "type": "object",
      "required": ["command", "extensionToLanguage"],
      "properties": {
        "command": {
          "type": "string",
          "description": "Command to start the LSP server"
        },
        "args": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Command line arguments"
        },
        "extensionToLanguage": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "File extension to language ID mapping"
        },
        "startupTimeout": {
          "type": "integer",
          "minimum": 1000,
          "maximum": 300000,
          "description": "Server startup timeout in milliseconds"
        }
      }
    }
  }
}

plugin.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://anthropic.com/claude-code/plugin.schema.json",
  "title": "Claude Code Plugin",
  "description": "Schema for Claude Code plugin metadata",
  "type": "object",
  "required": ["name", "description", "version"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "Unique plugin identifier (lowercase, alphanumeric with hyphens)"
    },
    "description": {
      "type": "string",
      "minLength": 10,
      "maxLength": 500,
      "description": "Human-readable plugin description"
    },
    "version": {
      "type": "string",
      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
      "description": "Semantic version (e.g., 1.0.0, 0.1.0-beta)"
    },
    "author": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Author name"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Author email"
        }
      },
      "required": ["name"]
    },
    "homepage": {
      "type": "string",
      "format": "uri",
      "description": "Project homepage URL"
    },
    "repository": {
      "type": "string",
      "format": "uri",
      "description": "Source code repository URL"
    },
    "license": {
      "type": "string",
      "description": "SPDX license identifier (e.g., MIT, Apache-2.0)"
    },
    "keywords": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Search keywords"
    },
    "lspServers": {
      "type": "string",
      "description": "Relative path to .lsp.json configuration"
    },
    "claudeCodeVersion": {
      "type": "string",
      "pattern": "^>=?\\s*(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$",
      "description": "Minimum required Claude Code version (e.g., >=2.0.74)"
    }
  }
}

I'm a bit of a skill junkie and have been trying to use the plugin-dev: stuff and my own skill building tree to help stay organized/follow best practices building plugins - I know this is fast moving target... I've come to the conclusion that trying to do a "local" folder will cause nothing but pain/wasted effort because of how skills/plugins get cached - I've had much better success publishing my skills to git and syncing across computers using the "marketplace" paradigm. This however is way less documented atm (understandable cause iirc this is like totally new). It also seems like Claude Desktop is lagging a bit here - "Capabilities" only takes standalone skills and there is some tensions maintaining skills that can be used in claude code and Claude Desktop. So I've kind of taken a the approach of periodically using an agent to crawl/infer some things about the evolving json schema and it found this issue which seems relevant to my interests. So for anyone that finds this as well - until "real" schema gets published and things better documented I had muh boy write this up to help people out...

This information might be totally out of date next week (spoilers it was). Welcome to the bleeding edge ya'll!

---

The Marketplace & Plugin Schema Saga

A chronicle of discoveries about Claude Code plugin distribution, schemas, and the official patterns that emerged from investigating Anthropic's own implementations.

Last Updated: 2026-01-13 (synced with official docs at code.claude.com)

The Schema Mystery

What the Docs Say

Every official marketplace.json file references a schema:

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  ...
}

What Actually Exists

Nothing. The URL returns 404.

$ curl -sI https://anthropic.com/claude-code/marketplace.schema.json
HTTP/2 302 → https://www.anthropic.com/claude-code/marketplace.schema.json → 404

This is a known bug: GitHub Issue #9686 (opened October 2025, still open as of January 2026).

Our Solution

We maintain local schemas inferred from actual usage:

• schemas/marketplace.schema.json
• schemas/plugin.schema.json

Run /sync-schemas to re-analyze official sources and update local schemas.

---

Distribution Paths

Claude Code plugins can be distributed via two completely different mechanisms.

Path 1: Marketplace (Claude Code CLI)

For Claude Code (the CLI tool), plugins are distributed via marketplaces:

marketplace-repo/
├── .claude-plugin/
│   └── marketplace.json    # Lists all plugins
└── plugins/
    ├── plugin-a/
    └── plugin-b/

Installation: Users add the marketplace, then install individual plugins via /plugin install <name>@<marketplace>.

Key file: marketplace.json in .claude-plugin/ directory, containing plugin entries with source paths.

Path 2: .skill Files (Claude Desktop)

Claude Desktop (the macOS/Windows app) doesn't support marketplaces. Instead, skills are loaded individually via .skill files:

• .skill file = zip archive containing a skill directory
• Loaded in Claude Desktop → Preferences → Skills
• Each skill is standalone (no plugin grouping concept)

Key difference: Desktop loads individual skills; CLI loads plugins (which contain multiple skills).

---

Official Marketplace Structure

Analyzed from ~/.claude/plugins/marketplaces/claude-plugins-official/:

Root Level

claude-plugins-official/
├── .claude-plugin/
│   └── marketplace.json      # The source of truth for plugin discovery
├── plugins/                  # Anthropic-maintained plugins
│   ├── plugin-dev/
│   ├── feature-dev/
│   ├── agent-sdk-dev/
│   └── ...
└── external_plugins/         # Community/partner plugins
    ├── github/
    ├── stripe/
    └── ...

marketplace.json Structure

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "claude-plugins-official",
  "description": "Directory of popular Claude Code extensions...",
  "owner": {
    "name": "Anthropic",
    "email": "support@anthropic.com"
  },
  "metadata": {
    "description": "Brief marketplace description",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "plugin-dev",
      "description": "Comprehensive toolkit for developing Claude Code plugins...",
      "author": { "name": "Anthropic", "email": "support@anthropic.com" },
      "source": "./plugins/plugin-dev",
      "category": "development",
      "homepage": "https://github.com/..."
    }
  ]
}

Root-Level Keys

| Key | Required | Description |
|-----|----------|-------------|
| $schema | No | Schema URL (returns 404) |
| name | Yes | Marketplace identifier (kebab-case) |
| owner | Yes | Owner object with name (required), email (optional) |
| plugins | Yes | Array of plugin entries |
| metadata.description | No | Brief marketplace description |
| metadata.version | No | Marketplace version |
| metadata.pluginRoot | No | Base directory prepended to relative source paths |

Reserved Marketplace Names

The following names are reserved for official Anthropic use:

• claude-code-marketplace
• claude-code-plugins
• claude-plugins-official
• anthropic-marketplace
• anthropic-plugins
• agent-skills
• life-sciences

Names that impersonate official marketplaces (like official-claude-plugins) are also blocked.

Plugin Entry Keys

| Key | Required | Description |
|-----|----------|-------------|
| name | Yes | Plugin identifier (kebab-case) |
| source | Yes | Relative path or URL object |
| description | No | Human-readable description |
| author | No | Author object with name, email |
| category | No | One of: development, productivity, testing, database, deployment, design, monitoring, security, learning |
| homepage | No | Documentation URL |
| version | No | Semver string |
| tags | No | Array of strings |
| strict | No | Boolean (default: true) - see below |
| keywords | No | Tags for discovery |
| license | No | SPDX identifier |
| repository | No | Source code URL |
| commands | No | Custom command paths |
| agents | No | Custom agent paths |
| skills | No | Custom skill paths |
| hooks | No | Hook config or path |
| mcpServers | No | MCP config or path |
| lspServers | No | LSP config or path |
| outputStyles | No | Output style paths |

Source Field Variants

Simple path:

"source": "./plugins/plugin-dev"

GitHub object:

"source": {
  "source": "github",
  "repo": "owner/plugin-repo"
}

URL object (for external repos):

"source": {
  "source": "url",
  "url": "https://github.com/org/repo.git"
}

---

The strict Field (RESOLVED)

When Does a Plugin Need plugin.json?

Answer: It depends on the strict field.

| strict Value | Behavior |
|----------------|----------|
| true (default) | Plugin source MUST contain .claude-plugin/plugin.json. Marketplace entry fields are MERGED with plugin.json |
| false | Plugin does NOT need its own plugin.json. Marketplace entry defines everything |

Examples

strict: true (default) - Plugin has its own manifest:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin",
  "description": "Overwrites plugin.json description"
}

The plugin at ./plugins/my-plugin/.claude-plugin/plugin.json must exist.

strict: false - Marketplace defines everything:

{
  "name": "simple-plugin",
  "source": "./plugins/simple-plugin",
  "description": "No plugin.json needed",
  "strict": false,
  "commands": ["./plugins/simple-plugin/commands/"]
}

In Official Marketplace

| Plugin | Has plugin.json? | strict value |
|--------|-----------------|--------------|
| plugin-dev | NO | false (implied) |
| agent-sdk-dev | YES | true (default) |
| feature-dev | YES | true (default) |
| LSP plugins | NO | false (explicit) |
| github (external) | YES | true (default) |

Our Approach

We include plugin.json for maximum flexibility (standalone distribution, local development).

---

Plugin Components

Commands

Location: commands/ directory in plugin root

Format: Markdown files with frontmatter

Commands are namespaced: plugin-name:command-name

Agents

Location: agents/ directory in plugin root

Format: Markdown files describing agent capabilities

Skills

Location: skills/ directory in plugin root

Format: Directories containing SKILL.md files with frontmatter

Hooks

Location: hooks/hooks.json in plugin root, or inline in plugin.json

Hook Events (as of 2026-01):

| Event | Trigger |
|-------|---------|
| PreToolUse | Before tool execution |
| PostToolUse | After successful tool execution |
| PostToolUseFailure | After failed tool execution |
| PermissionRequest | When permission dialog shown |
| UserPromptSubmit | When user submits prompt |
| Notification | When Claude sends notification |
| Stop | When Claude attempts to stop |
| SubagentStart | When subagent starts |
| SubagentStop | When subagent stops |
| SessionStart | At session beginning |
| SessionEnd | At session end |
| PreCompact | Before context compaction |

Hook Types:

| Type | Description |
|------|-------------|
| command | Execute shell command/script |
| prompt | Evaluate prompt with LLM |
| agent | Run agentic verifier with tools |

MCP Servers

Location: .mcp.json in plugin root, or inline in plugin.json

LSP Servers

Location: .lsp.json in plugin root, or inline in plugin.json

LSP plugins provide code intelligence (go to definition, find references, diagnostics).

Output Styles

Location: outputStyles/ directory or custom path

Customize Claude's response formatting.

---

Plugin Caching

Important: Plugins are COPIED to a cache directory, not used in-place.

Implications:

• Paths like ../shared-utils won't work (files not copied)
• Symlinks ARE followed during copying
• Use ${CLAUDE_PLUGIN_ROOT} for all paths in hooks/MCP configs

---

Categories

Official categories:

• development - Dev tools, language servers, SDKs
• productivity - Workflow tools, integrations
• testing - Test frameworks, automation
• database - Database integrations
• deployment - CI/CD, hosting platforms
• design - Design tool integrations
• monitoring - Error tracking, observability
• security - Security tools
• learning - Educational content, learning modes

---

Installation Scopes

| Scope | Settings File | Use Case |
|-------|---------------|----------|
| user | ~/.claude/settings.json | Personal, all projects (default) |
| project | .claude/settings.json | Team, shared via git |
| local | .claude/settings.local.json | Personal, project-specific, gitignored |
| managed | managed-settings.json | Admin-controlled, read-only |

---

CLI Commands

# Marketplace management
claude plugin marketplace add owner/repo
claude plugin marketplace add https://gitlab.com/org/repo.git
claude plugin marketplace add ./local-path
claude plugin marketplace list
claude plugin marketplace update marketplace-name
claude plugin marketplace remove marketplace-name

# Plugin management
claude plugin install plugin-name@marketplace-name
claude plugin install plugin-name@marketplace-name --scope project
claude plugin uninstall plugin-name@marketplace-name
claude plugin enable plugin-name@marketplace-name
claude plugin disable plugin-name@marketplace-name
claude plugin update plugin-name@marketplace-name

# Validation
claude plugin validate .

---

Reference Sources

Documentation (Most Current)

• Plugins - Creating plugins
• Plugins Reference - Full technical spec
• Plugin Marketplaces - Distribution
• Discover Plugins - Installation

Local (After Installing Official Marketplace)

# Marketplace structure
ls ~/.claude/plugins/marketplaces/claude-plugins-official/

# marketplace.json
cat ~/.claude/plugins/marketplaces/claude-plugins-official/.claude-plugin/marketplace.json

# Individual plugins
ls ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/

GitHub

• anthropics/claude-code - Main Claude Code repo
• anthropics/claude-plugins-official - Official plugins

Known Issues

• #9686: JSON schema URL doesn't exist

---

Key Takeaways

1. Schema URLs are broken - Maintain local schemas, sync from observed patterns
2. Two distribution paths - Marketplace (CLI) vs .skill files (Desktop)
3. strict field controls plugin.json requirement - false = marketplace defines everything
4. marketplace.json is the source of truth for plugin discovery
5. Plugins are cached - Use ${CLAUDE_PLUGIN_ROOT}, symlinks work
6. Reserved names exist - Don't use official-sounding marketplace names
7. New hook events - PostToolUseFailure, SubagentStart
8. New hook type - agent for agentic verification

---

Changelog

• 2026-01-13: Major update - synced with official docs, added strict field explanation, new hook events, reserved names, caching behavior
• 2026-01-08: Initial documentation based on analysis of claude-plugins-official

Is the marketplace schema actually available anywhere? This is a bit silly...

@bcherny please help us 😢

Seems like the issue is still there...

this is still happening.

a 404 error occurs when accessing the listed schema from the official docs.

I'm trying to create a marketplace and claude has no idea what's it's doing lol. It doesn't seem to be trained on this functionality.

@nikhilsitaram install this official plugin-dev plugin: https://github.com/anthropics/claude-plugins-official/tree/main/plugins/plugin-dev

The URL https://anthropic.com/claude-code/marketplace.schema.json still returns a 404 error :(

It’s been 172 days since the issue was created; another 10 days and we can celebrate half a year :/

This link appears in the official repository :(
https://github.com/anthropics/claude-code/blob/b543a256248ce5ff98804b8dfef4cd6247423d98/.claude-plugin/marketplace.json#L2

Good lord, guys. How has something this simple been going on and ignored for this long?

Fixed across five PRs:

• anthropics/claude-cli-internal#31464 — claude plugin validate now accepts $schema/version/description (also fixes #42412)
• anthropics/claude-cli-internal#31465 — added scripts/generate-plugin-schemas.ts to generate the JSON Schemas from the Zod definitions
• anthropics/claude-cli-internal#31506 — generator emits draft-07 for SchemaStore compatibility
• SchemaStore/schemastore#5603 — schemas hosted at schemastore.org with fileMatch for .claude-plugin/{plugin,marketplace}.json
• #52239 — this repo's .claude-plugin/marketplace.json now points at the working schemastore URL

The schemas are live:

• https://json.schemastore.org/claude-code-marketplace.json
• https://json.schemastore.org/claude-code-plugin-manifest.json

— 🤖 Claude (for @dhollman)

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.