claude-code - 💡(How to fix) Fix [DOCS] Plugin update docs still describe npm-sourced plugins as `unknown` [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Version management for /plugin update, plus the npm-source version-resolution guidance referenced by plugin marketplace docs

Current Documentation

The docs currently say:

Claude Code uses the plugin's version as the cache key that determines whether an update is available. When you run /plugin update or auto-update fires, Claude Code computes the current version and skips the update if it matches what's already installed.

The version is resolved from the first of these that is set:

1. The version field in the plugin's plugin.json
2. The version field in the plugin's marketplace entry in marketplace.json
3. The git commit SHA of the plugin's source, for github, url, git-subdir, and relative-path sources in a git-hosted marketplace
4. unknown, for npm sources or local directories not inside a git repository

The marketplace docs also say:

Plugins distributed as npm packages are installed using npm install.

and later:

Plugin versions determine cache paths and update detection: if the resolved version matches what a user already has, /plugin update and auto-update skip the plugin.

Claude Code resolves a plugin's version from the first of these that is set:

1. version in the plugin's plugin.json
2. version in the plugin's marketplace entry
3. The git commit SHA of the plugin's source

What's Wrong or Missing?

As of v2.1.128, the changelog says Claude Code fixed /plugin update so it no longer misses newer versions of npm-sourced plugins.

The reference docs are still outdated for that behavior:

A. The current version-resolution docs still say npm sources resolve to unknown

That implies /plugin update cannot reliably compare installed vs newer npm releases, which contradicts the v2.1.128 fix.

B. The npm marketplace docs explain install syntax, but not npm update detection

plugin-marketplaces documents npm sources and supports version / semver ranges in the npm source object, but the version-resolution section never explains how npm-sourced plugins are checked during /plugin update or auto-update.

Readers are left without current guidance on whether npm plugins update correctly, what version metadata Claude Code uses, and how pinned vs ranged npm versions affect update checks.

Suggested Improvement

Update the plugin versioning docs to reflect the post-v2.1.128 behavior for npm sources.

Specifically:

1. Replace the unknown statement for npm sources in plugins-reference with the actual npm-specific version source Claude Code now uses for update detection.
2. In plugin-marketplaces, add a short npm-specific note explaining how /plugin update and auto-update determine whether a newer npm package version is available.
3. Clarify how exact npm pins vs semver ranges in the npm source object affect update behavior.
4. Cross-link the npm packages section and the version-management section so readers can find the update rules from either page.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Cross-reference:

The changelog for v2.1.128 says Fixed /plugin update never detecting new versions of npm-sourced plugins: https://code.claude.com/docs/en/changelog