anthropics / anthropics/claude-code

[DOCS] plugin-marketplaces.md doesn't document the extraKnownMarketplaces source schema (git/hostPattern/file types missing, "url"/"github" mean something different there)

Open Beginner friendly
#89,140 0 comments 0 reactions 0 assignees View on GitHub
area:plugins documentation enhancement
Dominant language
Python
Stars
145k
Forks
23.1k
PR merge metrics
PR metrics pending

Description

### Documentation Type

Missing documentation (feature not documented)

### Documentation Location

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

### Section/Topic

Marketplace sources vs plugin sources / the `extraKnownMarketplaces` setting

### Current Documentation

The page's source-types table and surrounding prose only describe the schema for a *plugin entry's* `source` field inside `marketplace.json`:

> "The git-based source types below are `github`, `url`, and `git-subdir`."
>
> `url` | string | Required. Full git repository URL (`https://` or `git@`)

This table is presented right next to the page's own "Marketplace source vs plugin source" callout, which links `extraKnownMarketplaces` directly beside it — making it read as if this table is also the reference for `extraKnownMarketplaces` in settings.json.

### What's Wrong or Missing?

`extraKnownMarketplaces` actually uses a different, undocumented schema from the one on this page. Pulled directly from the current published schema (`https://www.schemastore.org/claude-code-settings.json`), the real `extraKnownMarketplaces` source union is:

- `url` — direct HTTP(S) URL to a `marketplace.json` file (`format: uri`, no git involved)
- `git` — full git-clone of a repo (`git@`/SSH and `https://` remotes both work here)
- `github` — `owner/repo` shorthand (different field shape than the plugin-entry `github` type)
- `hostPattern` — trust a git host pattern
- `npm` — package containing `marketplace.json`
- `file` — local path to `marketplace.json`

None of `git`, `hostPattern`, or `file` appear anywhere on the docs page. Worse, `url` and `github` *do* appear, but with different meaning and shape than the plugin-entry version of those same names — `url` here is a plain file fetch, not a git-based source at all, despite sitting directly under a section titled "the git-based source types."

This tripped me up in practice: I had `"source": "git"` with a `git@host:path.git` SSH URL in `extraKnownMarketplaces`, which works correctly, but it looked wrong against this page since `"git"` isn't listed as a valid type anywhere. Meanwhile `"url"` looked like it should accept the same SSH syntax per its description here — but `url` under `extraKnownMarketplaces` can't clone a repo at all, it only fetches a static file over HTTP(S).

### Suggested Improvement

Add a clearly-separated section (or its own page) documenting the `extraKnownMarketplaces` source schema on its own terms, distinct from the plugin-entry source table — ideally with its own table:

| Source | Fields | Notes |
|---|---|---|
| `url` | `url` (must be a URI) | Fetches `marketplace.json` directly over HTTP(S); not a git clone |
| `git` | `url`, `ref?`, `path?`, `skipLfs?` | Clones a full git repo; `url` accepts `https://` or `git@` SSH remotes |
| `github` | `repo`, `ref?`, `path?`, `skipLfs?` | GitHub `owner/repo` shorthand |
| `hostPattern` | `hostPattern` | Trusts a git host pattern for repos in source specs |
| `npm` | `package` | NPM package containing `marketplace.json` |
| `file` | `path` | Local file path to `marketplace.json` |

And note explicitly that this schema is not the same as the plugin-entry `source` schema documented above it, even though some type names overlap.

### Impact

Medium - Makes feature difficult to understand

### Additional Context

Related: #77315 (same `extraKnownMarketplaces` → `git` source schema area, different specific defect — a stale `.git$` suffix pattern requirement, confirmed by a maintainer as a stale-schema issue rather than a doc issue). Not a duplicate, just adjacent.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the plugin-marketplaces documentation page and compare its plugin-entry source table with the extraKnownMarketplaces schema at schemastore.org/claude-code-settings.json. Add a clearly separated table for the six extraKnownMarketplaces source types, including their fields and differing meanings. Done means the page documents git, hostPattern, and file and explicitly distinguishes overlapping url and github types.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
84/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.