claude-code - 💡(How to fix) Fix claude plugin update reports 'at latest' but cache stays stale vs refreshed marketplace (path-based plugins)

Summary

claude plugin update <plugin> reports "already at the latest version" for path-based marketplace plugins even when the cached plugin files are stale relative to the (refreshed) marketplace source. The local marketplace is up-to-date; the cache is not; update does nothing but says success. The only workaround is uninstall + install.

Environment

• Claude Code: native 2.1.150 (commit 28d4819e0f0a)
• OS: Linux x64 (Ubuntu 24.04.4)
• Marketplace: claude-plugins-official (GitHub: anthropics/claude-plugins-official)
• Affected plugins: skill-creator@claude-plugins-official, mcp-server-dev@claude-plugins-official (both have source: "./plugins/<name>" in marketplace.json — path-based, no per-plugin SHA pin)

Reproduction

1. Install a path-based plugin from the marketplace at time T0:

   claude plugin install skill-creator@claude-plugins-official

   Cache lands at ~/.claude/plugins/cache/claude-plugins-official/skill-creator/unknown/ with version: unknown in installed_plugins.json.

2. Some time later (T1), the marketplace's plugin source files are updated upstream. Verify by checking GitHub: there are commits modifying plugins/skill-creator/skills/skill-creator/SKILL.md etc.

3. Refresh the marketplace locally:

   claude plugin marketplace update claude-plugins-official

   .gcs-sha advances to the new HEAD. The marketplace cache at ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/skill-creator/ now contains the new files.

4. Run plugin update:

   claude plugin update skill-creator@claude-plugins-official

   Output: ✔ skill-creator is already at the latest version (unknown).

5. But the cache is actually stale. Diff the plugin cache against the marketplace source for the same plugin:

   diff -rq \
     ~/.claude/plugins/cache/claude-plugins-official/skill-creator/unknown/skills/skill-creator/ \
     ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/skill-creator/skills/skill-creator/

   Returns multiple differing files (e.g., SKILL.md, scripts/improve_description.py, scripts/run_loop.py).

6. lastUpdated in installed_plugins.json does NOT advance after the (no-op) update.

Expected

claude plugin update for a path-based plugin should detect that the marketplace's source files differ from the cached files (by content hash, mtime, or by re-syncing whenever marketplace sha advances) and re-sync the cache.

Actual

claude plugin update reports success without doing anything. The version comparison appears to skip the check entirely when version: unknown (i.e., no semver in marketplace.json).

Hypothesis

The update logic for marketplace plugins compares version strings. For plugins whose marketplace entry has no version: field (path-based plugins under the same repo), version is "unknown" both before and after update — comparison says "no change" without ever consulting actual file content or marketplace sha.

Workaround

claude plugin uninstall <plugin>@<marketplace>
claude plugin install <plugin>@<marketplace>

This clears the cache and re-installs fresh from the (refreshed) marketplace. Confirmed working:

$ diff -rq cache marketplace
# (after workaround) — no differences for .md/.py/.sh files

Suggested fix

For path-based plugins under a marketplace (source: ./plugins/<name>):

1. Store the marketplace .gcs-sha (or marketplace commit sha) at install time
2. On plugin update, if the current .gcs-sha ≠ stored, re-sync the cache from marketplace files
3. Or: when version == "unknown" in marketplace.json, fall back to file-content hash comparison

Alternatively, add --force flag to claude plugin update to bypass the "no change" check.

Impact

Currently low severity (no functional break — workaround exists and is documented above), but invisible drift: users running plugin update get a false confirmation and miss new guidance in updated SKILL.md files. Two cases I caught locally:

• skill-creator/SKILL.md added a new "Updating an existing skill" guidance section (preserve original name, copy to /tmp before editing) and dropped "extended thinking" wording
• mcp-server-dev/build-mcp-server/SKILL.md added a new "Load Claude-specific context first" instruction (fetch https://claude.com/docs/llms-full.txt) and a new "Phase 6 — Test in Claude and publish" section with review-criteria and submission links