Define a marketplace/registry index format

[pabloubal]

Problem

The v1.0.0 spec defines the layout of a single plugin well, but provides no standard for a repository that hosts multiple plugins and wants to expose a machine-readable index of them (a marketplace). For instance: https://github.com/anthropics/claude-plugins-official

Use case: A monorepo contains plugins under plugins/*/. Clients need to discover, list, and install individual plugins from it. Today there is no portable format for this index, so each client invents its own (e.g. https://github.com/anthropics/claude-plugins-official/blob/main/.claude-plugin/marketplace.json).

Proposal

Proposed: a marketplace.json (or index.json) at the repo root:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://agent-plugins.org/schemas/1.0.0/marketplace.schema.json",
    "title": "Agent Plugins Marketplace",
    "description": "Machine-readable schema for marketplace.json in Agent Plugins 1.0.0. The Agent Plugins specification defines additional semantic and operational requirements.",
    "type": "object",
    "properties": {
      "$schema": {
        "const": "https://agent-plugins.org/schemas/1.0.0/marketplace.schema.json",
        "description": "Canonical identifier of the marketplace schema for the Agent Plugins version targeted by this document."
      },
      "name": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64,
        "description": "Human-readable marketplace name."
      },
      "description": {
        "type": "string"
      },
      "plugins": {
        "type": "array",
        "items": {
          "$ref": "#/$defs/pluginEntry"
        }
      }
    },
    "required": ["$schema", "name", "plugins"],
    "additionalProperties": false,
    "$defs": {
      "pluginEntry": {
        "title": "Plugin entry",
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "description": {
            "type": "string"
          },
          "source": {
            "$ref": "#/$defs/source"
          }
        },
        "required": ["name", "source"],
        "additionalProperties": false
      },
      "source": {
        "title": "Plugin source",
        "oneOf": [
          { "$ref": "#/$defs/localSource" },
          { "$ref": "#/$defs/externalSource" }
        ]
      },
      "localSource": {
        "title": "Local source",
        "description": "A plugin co-located in the same repository, resolved relative to the marketplace root.",
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "pattern": "^\\./"
          }
        },
        "required": ["path"],
        "additionalProperties": false
      },
      "externalSource": {
        "title": "External source",
        "description": "A plugin resolved from a remote git repository, optionally scoped to a subdirectory and ref.",
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "pattern": "^https://",
            "description": "Git repository URL."
          },
          "path": {
            "type": "string",
            "description": "Path to the plugin root within the repository. Defaults to the repository root when omitted."
          },
          "ref": {
            "type": "string",
            "description": "Git ref (tag, branch, or commit SHA). Defaults to the repository default branch when omitted."
          }
        },
        "required": ["url"],
        "additionalProperties": false
      }
    }
  }

Example

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/marketplace.schema.json",
  "name": "my-org-marketplace",
  "description": "This is a directory of all our plugins"
  "plugins": [
    {
      "name": "a-team",
      "description": "A-Team skills",
      "source": {
        "path": "./plugins/a-team"
      }
    },
    {
      "name": "external-awesome-plugin",
      "description": "An external plugin we use",
      "source": {
        "url": "https://github.com/external-org/skills.git",
        "path": "plugins/awesome",
        "ref": "main"
      }
    }
  ]
}

Some considerations

• Should source support remote (git, HTTPS) in addition to local paths?
• Should the index include version and author, or just point to each plugin root and let clients read plugin.json directly?

[rnett]

at the repo root

Why should the file be required to be at repo root? I could see situations where you want multiple distinct marketplaces in the same repo (e.g. different departments).

[pabloubal]

That's a good point, however IMHO having multiple marketplaces within the same repo I think it might add more problem than it solves.

If the goal is to host multiple marketplaces within the same company, you can have that with separate repos, which on top adds better governance, independent versioning, access control, etc.

IMHO hosting multiple marketplaces within the same repo creates a bigger complexity:

• clients will need to know which marketplace you want to install, so they will either need to scan all marketplace.json files and ask the user at the moment of installing or the user will need to specify the full path to the marketplace file.
• Governance becomes complicated (versioning, access, etc), and you might need per path permissions.

A single marketplace.json at the root allows a seamless installation experience for the clients (i.e. claude plugin marketplace add https://github.com/anthropics/claude-plugins-official), and multiple repos give you full governance.

If you still need a single repo, you can have that with a single marketplace. Each department can have a plugin within the marketplace:

• ./marketplace.json
• ./archtiecture-plugin
• ./engineering-plugin
• ./product-plugin
• etc

Reference: https://code.claude.com/docs/en/plugin-marketplaces