marketplace-structure

What this skill does

# Marketplace Structure

A plugin marketplace is a catalog of available plugins that enables centralized discovery, version management, and distribution. This skill covers creating and maintaining marketplaces for team or community plugin distribution.

## Overview

Marketplaces provide:

- **Centralized discovery** - Browse plugins from multiple sources in one place
- **Version management** - Track and update plugin versions automatically
- **Team distribution** - Share required plugins across an organization
- **Flexible sources** - Support for relative paths, GitHub repos, and git URLs

### When to Create a Marketplace vs. a Plugin

| Create a Plugin                     | Create a Marketplace                 |
| ----------------------------------- | ------------------------------------ |
| Single-purpose extension            | Collection of related plugins        |
| Used directly by end users          | Distributes multiple plugins         |
| One team or individual maintains it | Curates plugins from various sources |
| Installed via `/plugin install`     | Added via `/plugin marketplace add`  |

## Directory Structure

Place `marketplace.json` in the `.claude-plugin/` directory at the repository root:

```text
marketplace-repo/
├── .claude-plugin/
│   └── marketplace.json      # Required: Marketplace manifest
├── plugins/                  # Optional: Local plugin directories
│   ├── plugin-one/
│   │   └── .claude-plugin/
│   │       └── plugin.json
│   └── plugin-two/
│       └── .claude-plugin/
│           └── plugin.json
└── README.md                 # Recommended: Marketplace documentation
```

## Marketplace Schema

The `marketplace.json` manifest defines the marketplace and its available plugins.

### Required Fields

| Field     | Type   | Description                                    |
| --------- | ------ | ---------------------------------------------- |
| `name`    | string | Marketplace identifier (kebab-case, no spaces) |
| `owner`   | object | Marketplace maintainer information             |
| `plugins` | array  | List of available plugin entries               |

### Owner Object

```json
{
  "owner": {
    "name": "Team Name",
    "email": "[email protected]",
    "url": "https://github.com/team"
  }
}
```

### Optional Metadata

```json
{
  "metadata": {
    "description": "Brief marketplace description",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  }
}
```

The `pluginRoot` field sets the base path for relative plugin sources.

## Plugin Entry Format

Each plugin in the `plugins` array requires:

| Field    | Type             | Description                                               |
| -------- | ---------------- | --------------------------------------------------------- |
| `name`   | string           | Plugin identifier (kebab-case, unique within marketplace) |
| `source` | string or object | Where to fetch the plugin                                 |

### Optional Plugin Fields

Standard metadata fields:

- `description` - Brief plugin description
- `version` - Plugin version (semver)
- `author` - Author information object
- `homepage` - Documentation URL
- `repository` - Source code URL
- `license` - SPDX license identifier
- `keywords` - Tags for discovery
- `category` - Plugin category
- `tags` - Additional searchability tags

Component configuration fields:

- `commands` - Custom paths to command files or directories
- `agents` - Custom paths to agent files
- `hooks` - Hooks configuration or path to hooks file
- `mcpServers` - MCP server configurations

For complete field reference, see `references/schema-reference.md`.

## Plugin Sources

### Relative Paths

For plugins within the same repository:

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

### GitHub Repositories

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

### GitHub Repositories with Pinning

Pin to a specific ref or commit SHA for reproducible builds:

```json
{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v1.2.0",
    "sha": "abc123def456..."
  }
}
```

- `ref` — Branch, tag, or commit reference (e.g., `"v1.0"`, `"main"`)
- `sha` — Exact commit SHA for integrity verification

### Git URLs

For GitLab, Bitbucket, or self-hosted git:

```json
{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main"
  }
}
```

### Host Pattern

Match plugins by URL pattern:

```json
{
  "name": "internal-plugin",
  "source": {
    "hostPattern": "https://git.company.com/*"
  }
}
```

## Strict vs. Non-Strict Mode

The `strict` field controls whether plugins must have their own `plugin.json`:

| Mode                     | Behavior                                                              |
| ------------------------ | --------------------------------------------------------------------- |
| `strict: true` (default) | Plugin must include `plugin.json`; marketplace entry supplements it   |
| `strict: false`          | `plugin.json` optional; marketplace entry serves as complete manifest |

Use `strict: false` when:

- Curating external plugins without modifying their source
- Providing all metadata in the marketplace entry
- Plugin directories contain only commands/agents/skills without manifest

```json
{
  "name": "external-plugin",
  "source": {
    "source": "github",
    "repo": "external/plugin"
  },
  "description": "Complete metadata here",
  "version": "2.0.0",
  "strict": false
}
```

## Enterprise Features

### Managed Marketplace Restrictions

Organizations can restrict which marketplaces users can install from using managed settings:

```json
{
  "strictKnownMarketplaces": true
}
```

When enabled, users can only install plugins from officially approved marketplaces. Additional marketplaces can be added via `extraKnownMarketplaces` in managed settings.

### Private Repository Authentication

For marketplaces hosted in private repositories, set the appropriate environment variable:

- **GitHub**: `GITHUB_TOKEN`
- **GitLab**: `GITLAB_TOKEN`
- **Bitbucket**: `BITBUCKET_TOKEN`

See `references/distribution-patterns.md` for configuration details.

### Reserved Marketplace Names

Some marketplace names are reserved by Anthropic for official use. Choose distinctive names for custom marketplaces to avoid conflicts.

### URL-Based Marketplace Limitations

Marketplaces added via URL (rather than git source) have limited support for relative paths in plugin sources. Relative paths may not resolve correctly — prefer absolute source references or git-based marketplaces.

## Best Practices

### Organization

- **One theme per marketplace** - Group related plugins (e.g., "frontend-tools", "security-plugins")
- **Clear naming** - Use descriptive kebab-case names for both marketplace and plugins
- **Version all entries** - Include `version` for every plugin entry
- **Document each plugin** - Provide `description` for discoverability

### Versioning

- Use semantic versioning (X.Y.Z) for marketplace `metadata.version`
- Update marketplace version when adding, removing, or updating plugins
- Consider a CHANGELOG.md for tracking changes

### Distribution

- **GitHub hosting** - Simplest distribution via `/plugin marketplace add owner/repo`
- **Team settings** - Configure `extraKnownMarketplaces` in `.claude/settings.json`
- **Local testing** - Add with `/plugin marketplace add ./path` during development

For detailed distribution patterns, see `references/distribution-patterns.md`.

### Validation

Validate marketplace structure before publishing:

```bash
# Check JSON syntax
jq . .claude-plugin/marketplace.json

# Verify required fields
jq 'has("name") and has("owner") and has("plugins")' .claude-plugin/marketplace.json
```

Use the `plugin-validator` agent with marketplace support for comprehensive validation.

## Complete Example

```