> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Marketplaces & Plugins

**Plugins** and **marketplaces** are the distribution mechanism for skills. While individual skills and rules can be discovered in AI Explorer on their own, plugins and marketplaces let you group, version, and distribute collections of skills as installable packages.

## Key concepts

* A **marketplace** is a Git repository that hosts one or more plugins
* A **plugin** wraps one or more skills into a single installable package
* A **skill** is a directory containing a `SKILL.md` file (see [Skills](./skills))

```mermaid theme={"theme":{"light":"github-light","dark":"dracula"}}
graph TD
    M[Marketplace] -->|contains| P1[Plugin A]
    M -->|contains| P2[Plugin B]
    P1 -->|bundles| S1[Skill 1]
    P1 -->|bundles| S2[Skill 2]
    P2 -->|bundles| S3[Skill 3]
```

You don't need a plugin or marketplace for your skill to appear in AI Explorer as a standalone `SKILL.md` in any scanned repository is enough for discovery. But wrapping skills in a plugin and publishing through a marketplace makes distribution and installation easier.

## How discovery works

AI Explorer automatically scans configured GitHub organizations for these files:

| File               | Location                          | Entity type |
| ------------------ | --------------------------------- | ----------- |
| `SKILL.md`         | Any directory                     | Skill       |
| `plugin.json`      | `.claude-plugin/plugin.json`      | Plugin      |
| `marketplace.json` | `.claude-plugin/marketplace.json` | Marketplace |

## Creating a plugin

A plugin is defined by a `plugin.json` file at `.claude-plugin/plugin.json` in your repository:

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "name": "my-team-essentials",
  "version": "1.0.0",
  "description": "Essential skills for the backend team",
  "author": { "name": "backend-team" },
  "skills": ["skills/database-migrations", "skills/api-endpoint-creator"]
}
```

### Plugin fields

| Field         | Required | Description                                        |
| ------------- | -------- | -------------------------------------------------- |
| `name`        | Yes      | Plugin name                                        |
| `description` | No       | Short description                                  |
| `version`     | No       | Semantic version                                   |
| `author`      | No       | Author info (`{ "name": "..." }`)                  |
| `skills`      | No       | Paths to skill directories containing a `SKILL.md` |

If `skills` is omitted, the plugin automatically discovers `SKILL.md` files under `skills/` relative to the plugin root.

## Creating a marketplace

A marketplace is defined by a `marketplace.json` file at `.claude-plugin/marketplace.json` in your repository:

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "name": "backend-marketplace",
  "description": "Backend team's curated plugins",
  "version": "1.0.0",
  "owner": { "name": "backend-team" },
  "plugins": [
    {
      "name": "my-team-essentials",
      "source": "./plugins/my-team-essentials",
      "description": "Essential skills for the backend team"
    },
    {
      "name": "data-pipeline-tools",
      "source": "./plugins/data-pipeline-tools"
    }
  ]
}
```

### Marketplace fields

| Field         | Required | Description                                           |
| ------------- | -------- | ----------------------------------------------------- |
| `name`        | Yes      | Marketplace name                                      |
| `description` | No       | Short description                                     |
| `version`     | No       | Semantic version                                      |
| `owner`       | No       | Owner info (`{ "name": "...", "email": "..." }`)      |
| `plugins`     | No       | List of plugin entries (see below)                    |
| `metadata`    | No       | Fallback `description` and `version` if not set above |

### Plugin entry fields

Each entry in the `plugins` array describes a plugin to include in the marketplace:

| Field         | Required | Description                                                               |
| ------------- | -------- | ------------------------------------------------------------------------- |
| `name`        | Yes      | Plugin name                                                               |
| `source`      | Yes      | Relative path (e.g. `./plugins/my-plugin`) or a source object (see below) |
| `description` | No       | Short description                                                         |
| `version`     | No       | Semantic version                                                          |
| `skills`      | No       | Paths to skill directories within the plugin                              |

### Plugin sources

The `source` field supports two forms:

**Relative path** — references a plugin directory within the same repository:

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}
```

If a `.claude-plugin/plugin.json` exists at that path, the marketplace links to it. Otherwise, AI Explorer creates a plugin entity from the marketplace entry itself.

**GitHub repository** — references a plugin in a different repository:

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "name": "external-plugin",
  "source": { "source": "github", "repo": "my-org/external-plugin-repo" }
}
```

## Installing from a marketplace

Once a marketplace is added to AI Explorer, its plugins appear in the **Plugins** tab. From a plugin's detail page, the install card shows the commands to add the marketplace and install the plugin.

## Browsing

In the Portal UI, navigate to **AI Explorer**:

* The **Skills** tab shows all discoverable skills, including those within plugins
* The **Plugins** tab shows all plugins, grouped by marketplace
* Each plugin detail page lists its skills and provides install instructions