[DOCS] Plugin marketplace docs missing @ ref separator and update behavior for pinned marketplaces

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/discover-plugins

Section/Topic

"Add from GitHub" section — ref separator syntax; "Update a marketplace" section — pinned ref behavior

Current Documentation

discover-plugins.md documents the # separator for specifying a branch or tag when adding a git-based marketplace:

"To add a specific branch or tag, append # followed by the ref:" ``shell /plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0 ``

The update command is documented as:

``shell /plugin marketplace update marketplace-name ``

With no mention of pinned ref behavior.

What's Wrong or Missing?

A. The @ ref separator is undocumented

Changelog v2.1.71 fixes that /plugin marketplace add owner/repo@ref incorrectly parsed @ — previously only # worked as a ref separator, causing undiagnosable errors with strictKnownMarketplaces. This fix confirms that @ is now a valid and supported separator for specifying a ref (branch, tag, or SHA) in marketplace add commands.

The current docs show only # as the ref separator (for full git URLs). The shorter owner/repo@ref form (for GitHub shorthand) is not documented at all. Users who naturally write owner/repo@v1.0.0 (following npm/pip conventions) would have no indication this syntax is valid.

B. marketplace update behavior with pinned refs is undocumented

When a marketplace is pinned to a specific branch or tag ref, running /plugin marketplace update previously failed with merge conflicts. The v2.1.71 fix corrects this. The documentation for /plugin marketplace update makes no mention of how the command behaves when the marketplace source is pinned to a ref — users do not know whether update fetches from the pinned ref, advances to HEAD, or requires special handling.

Suggested Improvement

In discover-plugins.md — ref separator section

Update the "Add from GitHub" section to document both separators:

To add a marketplace at a specific branch or tag:

# GitHub shorthand — use @ as the ref separator
/plugin marketplace add owner/repo@v1.0.0
/plugin marketplace add owner/repo@main

# Full git URL — use # as the ref separator
/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0

In discover-plugins.md — update section

Add a note about pinned marketplace behavior:

When a marketplace is pinned to a branch or tag ref (e.g., owner/repo@v1.0.0), /plugin marketplace update fetches the latest state of that ref rather than advancing to HEAD. To move to a different ref, re-add the marketplace with the new ref.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/discover-plugins | Ref separator syntax and update behavior |
| https://code.claude.com/docs/en/plugins-reference | Plugin/marketplace add command reference |

Total scope: 2 pages affected

Source: Changelog v2.1.71

Exact changelog entries:

"Fixed /plugin marketplace update failing with merge conflicts when the marketplace is pinned to a branch/tag ref" "Fixed /plugin marketplace add owner/repo@ref incorrectly parsing @ — previously only # worked as a ref separator, causing undiagnosable errors with strictKnownMarketplaces"