From c5f1c75def3ceb74e93a5d4a646b106dfe172b1f Mon Sep 17 00:00:00 2001
From: lzw-git-all <19607802@qq.com>
Date: Sat, 25 Apr 2026 13:33:17 +0800
Subject: [PATCH] docs(plugins): add marketplace update vs plugin update
 distinction and auto-update mechanism (#84)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Background:
- Users were confused about the difference between `marketplace update`
  (refreshes catalog) and `plugin update` (updates installed plugins)
- Auto-update mechanism was not documented, causing confusion about
  why official marketplaces auto-refresh while third-party ones don't

Changes:
1. Add "Managing Marketplaces" section in Plugin Marketplace chapter
   - Marketplace CLI commands with Important note clarifying the distinction
2. Add `plugin update` command to Plugin CLI Commands list
3. Add "Auto-Update" section after Installation Methods
   - Comparison table: official vs third-party default behavior
   - Environment variables: DISABLE_AUTOUPDATER, FORCE_AUTOUPDATE_PLUGINS

Structure rationale:
- Marketplace commands belong to Plugin Marketplace chapter (concept + commands together)
- Auto-Update follows Installation Methods (logical flow: install → maintain)
- Plugin CLI Commands stays focused on plugin management only

Sources:
- https://code.claude.com/docs/en/discover-plugins (auto-update documentation)
- https://code.claude.com/docs/en/plugin-marketplaces (marketplace commands)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
---
 07-plugins/README.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/07-plugins/README.md b/07-plugins/README.md
index 4540b90..c73bad3 100644
--- a/07-plugins/README.md
+++ b/07-plugins/README.md
@@ -576,6 +576,18 @@ GitHub and git sources support optional `ref` (branch/tag) and `sha` (commit has
 
 **Official marketplace submission**: Submit plugins to the Anthropic-curated marketplace for broader distribution via [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit) or [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit).
 
+### Managing Marketplaces
+
+```bash
+# Marketplace CLI commands
+claude plugin marketplace add <source>       # Add marketplace (GitHub, URL, local)
+claude plugin marketplace update [name]      # Refresh catalog index
+claude plugin marketplace remove <name>      # Remove marketplace
+claude plugin marketplace list               # List configured marketplaces
+```
+
+> **Important**: `marketplace update` only refreshes the plugin catalog (what's available to install). It does NOT update installed plugins. Use `plugin update <name>` to update specific installed plugins.
+
 ### Strict mode
 
 Control how marketplace definitions interact with local `plugin.json` files:
@@ -642,6 +654,7 @@ All plugin operations are available as CLI commands:
 ```bash
 claude plugin install <name>@<marketplace>   # Install from a marketplace
 claude plugin uninstall <name>               # Remove a plugin
+claude plugin update <name>                  # Update installed plugin to latest version
 claude plugin list                           # List installed plugins
 claude plugin enable <name>                  # Enable a disabled plugin
 claude plugin disable <name>                 # Disable a plugin
@@ -678,6 +691,36 @@ claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b
 /plugin install github:username/repo
 ```
 
+## Auto-Update
+
+Claude Code can automatically update marketplaces and their installed plugins at startup.
+
+| Marketplace Type | Auto-Update Default | How to Toggle |
+|------------------|---------------------|---------------|
+| Official (`claude-plugins-official`) | ✅ Enabled | `/plugin` → Marketplaces → Select |
+| Third-party / Local | ❌ Disabled | Same UI path |
+
+When auto-update runs, Claude Code:
+1. Refreshes marketplace catalog
+2. Updates installed plugins to latest versions
+3. Shows notification prompting `/reload-plugins`
+
+### Environment Variables
+
+| Variable | Effect |
+|----------|--------|
+| `DISABLE_AUTOUPDATER=1` | Disable all auto-updates (Claude Code + plugins) |
+| `DISABLE_AUTOUPDATER=1` + `FORCE_AUTOUPDATE_PLUGINS=1` | Keep plugin updates, disable Claude Code updates |
+
+```bash
+# Disable all auto-updates
+export DISABLE_AUTOUPDATER=1
+
+# Keep plugin auto-updates only
+export DISABLE_AUTOUPDATER=1
+export FORCE_AUTOUPDATE_PLUGINS=1
+```
+
 ## When to Create a Plugin
 
 ```mermaid