← Back to daily report

discover-plugins.md

Changed on 2026-09-24 21:07:51 EST

Unified Diff

--- a/discover-plugins.md
+++ b/discover-plugins.md
@@ -2,588 +2,379 @@
 > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
 > Use this file to discover all available pages before exploring further.
 
-# Discover and install prebuilt plugins through marketplaces
-
-> Find and install plugins from marketplaces to extend Claude Code with new skills, agents, and capabilities.
-
-Plugins extend Claude Code with skills, agents, hooks, and MCP servers. Plugin marketplaces are catalogs that help you discover and install these extensions without building them yourself.
-
-You can also enable plugins on claude.ai, for yourself or through your organization. Claude Code syncs those into your sessions without a marketplace install, as [Plugins synced from claude.ai](/docs/en/plugins-reference#synced-plugins) describes.
-
-Looking to create and distribute your own marketplace? See [Create and distribute a plugin marketplace](/docs/en/plugin-marketplaces).
-
-## How marketplaces work
-
-A marketplace is a catalog of plugins that someone else has created and shared. Using a marketplace is a two-step process:
-
-<Steps>
-  <Step title="Add the marketplace">
-    This registers the catalog with Claude Code so you can browse what's available. No plugins are installed yet.
-  </Step>
-
-  <Step title="Install individual plugins">
-    Browse the catalog and install the plugins you want.
-  </Step>
-</Steps>
-
-## Official Anthropic marketplace
-
-Claude Code adds the official Anthropic marketplace (`claude-plugins-official`) automatically the first time you start it interactively. If Claude Code can't add it, for example because your network blocks the download or a [marketplace policy](/docs/en/plugin-marketplaces#managed-marketplace-restrictions) blocked an earlier attempt, add it yourself with `/plugin marketplace add anthropics/claude-plugins-official`.
-
-To browse what's available, run `/plugin` and go to the **Discover** tab, or view the catalog at [claude.com/plugins](https://claude.com/plugins).
-
-To install a plugin from the official marketplace, use `/plugin install <name>@claude-plugins-official`. For example, to install the GitHub integration:
-
-```shell theme={null}
-/plugin install github@claude-plugins-official
+# Install and manage plugins
+
+> Install Claude Code plugins from a marketplace on any surface you use, choose an install scope, and update or remove them later.
+
+Installing a plugin adds its skills, agents, hooks, and MCP servers to Claude Code on your machine.
+
+This page is for anyone using plugins on their own machine or account, whether in the terminal, the desktop app, an IDE, or a cloud session: it covers installing, choosing a scope, adding marketplaces, and keeping plugins updated.
+
+<Note>
+  These cases are covered on other pages:
+
+  * **You use claude.ai chat or Cowork, not Claude Code**: see [Plugins on claude.ai and in Cowork](https://claude.com/docs/plugins/overview)
+  * **Claude Code printed an error**: find it in [Troubleshoot plugins](/docs/en/plugins/troubleshooting)
+</Note>
+
+Start with [Install a plugin](#install-a-plugin). If someone sent you an install command whose `@` name isn't `claude-plugins-official`, [add that marketplace](#add-a-marketplace) first.
+
+## Install a plugin
+
+As an example, this section installs [`commit-commands`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/commit-commands) from [Anthropic's official marketplace](/docs/en/plugins/anthropic-marketplaces), which adds commands for committing, pushing, and opening pull requests.
+
+The same steps install any other plugin: substitute its name and its marketplace's name wherever `commit-commands` and `claude-plugins-official` appear. If that plugin comes from a different marketplace, [add the marketplace](#add-a-marketplace) first.
+
+Pick the tab for where you run Claude Code.
+
+<Tabs>
+  <Tab title="Terminal">
+    Start Claude Code with `claude` in your project, then:
+
+    <Steps>
+      <Step title="Open the plugin's details with the install command">
+        Run `/plugin install` with the plugin's name and marketplace. In a session, this command doesn't install right away: it opens the `/plugin` panel on that plugin's details so you can review it and choose a scope first.
+
+        ```text theme={null}
+        /plugin install commit-commands@claude-plugins-official
+        ```
+
+        To browse instead, run `/plugin` with no plugin name: the panel opens on the **Discover** tab, which lists plugins from every marketplace you've added, and you can type to search, then press **Enter** on a plugin to open its details.
+      </Step>
+
+      <Step title="Review what the plugin adds">
+        The details pane shows the plugin's description. It can also show:
+
+        * **Will install**: the commands, agents, skills, hooks, and MCP and LSP servers the plugin adds.
+        * **Last updated**: shown for a plugin in Anthropic's official marketplace.
+        * **Context cost**: for a plugin in Anthropic's official marketplace, two token estimates. **Every turn** is what the plugin adds to each message you send, and **When invoked** is what its skills and agents add once Claude loads them. The estimates appear when you open the plugin by naming its marketplace, as the step 1 command does, or from the **Marketplaces** tab. The details pane you reach from the **Discover** list doesn't show them.
+
+        Plugins from a local or custom marketplace can show `Components will be discovered at installation` instead.
+
+        A plugin can run hooks and MCP servers, so read the pane before you install. See [Plugin security and trust](/docs/en/plugins/security).
+      </Step>
+
+      <Step title="Choose a scope">
+        Select one of the three install options:
+
+        * **Install for you (user scope)**: you get the plugin in every project on this machine
+        * **Install for all collaborators on this repository (project scope)**: it's enabled for everyone who works in this repository
+        * **Install for you, in this repo only (local scope)**: you get it in this repository only
+
+        [Choose an install scope](#choose-an-install-scope) says which settings file each one writes to and which applies when the same plugin is set at more than one.
+
+        After you select a scope, Claude Code installs the plugin along with any dependencies it declares, then prints an install summary.
+      </Step>
+
+      <Step title="Read the install summary">
+        The last sentence of the summary tells you whether the plugin is usable in this session yet:
+
+        * **Active now**: `Plugin is now active.` No reload is needed.
+        * **Reload needed**: `Run /reload-plugins to activate.` The panel closes and Claude Code runs that reload for you. If the reload would [invalidate the prompt cache](/docs/en/prompt-caching#enabling-or-disabling-a-plugin), it warns and leaves the plugin pending instead. Run `/reload-plugins --force` to activate it anyway, which costs one uncached request.
+        * **Load failed**: `The plugin couldn't be loaded`. Open the **Errors** tab in `/plugin` for the reason, then see [After install: plugin not working](/docs/en/plugins/troubleshooting#plugin-installed-but-not-working).
+      </Step>
+
+      <Step title="Confirm the plugin works">
+        Type `/` and look for the plugin's skills under its name, in the form `/<plugin>:<skill>`. For `commit-commands`, `/commit-commands:commit` appears. Two other places list the plugin too:
+
+        * Open the **Installed** tab in `/plugin`, which lists the plugin with its scope.
+        * In your shell, run `claude plugin list`, which prints the same list with `Version`, `Scope`, and `Status` lines.
+
+        If `/commit-commands:commit` doesn't appear, see [After install: plugin not working](/docs/en/plugins/troubleshooting#plugin-installed-but-not-working).
+      </Step>
+    </Steps>
+
+    Installing from any other marketplace requires one extra step first: [add the marketplace](#add-a-marketplace). Claude Code adds Anthropic's official marketplace for you the first time you start an interactive terminal session, which is why the example skips that step. If you found a plugin on [claude.com/marketplace](https://claude.com/marketplace), its **Claude Code** button copies the install command in its [shell form](#install-from-your-shell), `claude plugin install <name>@claude-plugins-official`.
+  </Tab>
+
+  <Tab title="Desktop app">
+    In a local or SSH session in the desktop app's **Code** tab:
+
+    <Steps>
+      <Step title="Open the plugin browser">
+        Click the **+** button next to the prompt box and select **Plugins**, then **Add plugin**. The plugin browser opens with the plugins from your marketplaces.
+      </Step>
+
+      <Step title="Select the plugin">
+        Find `commit-commands` and select it.
+      </Step>
+
+      <Step title="Choose a scope">
+        Choose a [scope](#choose-an-install-scope): your user account, this project, or local-only.
+      </Step>
+    </Steps>
+
+    To enable, disable, or uninstall later, use **+ > Plugins > Manage plugins**. The plugin browser isn't available in the desktop app's cloud sessions. See [Install plugins in the desktop app](/docs/en/desktop#install-plugins).
+  </Tab>
+
+  <Tab title="VS Code">
+    In the Claude Code panel in VS Code:
+
+    <Steps>
+      <Step title="Open Manage plugins">
+        Type `/plugins` in the prompt box to open **Manage plugins**.
+      </Step>
+
+      <Step title="Install the plugin">
+        On the **Plugins** tab, search for `commit-commands` and click **Install**. If the tab lists no plugins, add `anthropics/claude-plugins-official` on the **Marketplaces** tab first.
+      </Step>
+
+      <Step title="Choose a scope">
+        Choose a [scope](#choose-an-install-scope): **Install for you**, **Install for this project**, or **Install locally**.
+      </Step>
+    </Steps>
+
+    Your changes apply to open sessions without a restart. See [Manage plugins in VS Code](/docs/en/vs-code#manage-plugins).
+  </Tab>
+
+  <Tab title="Cloud session">
+    A [cloud session](/docs/en/cloud-environments), including [the browser at claude.ai/code](/docs/en/claude-code-on-the-web), has no plugin browser and doesn't load the plugins you installed on your own machine or the ones your repository's `.claude/settings.json` turns on. For plugins your organization distributes through managed settings, see [Manage plugins for your organization](/docs/en/plugins/org).
+
+    See [which parts of your setup are also available in a cloud session](/docs/en/cloud-environments#what-carries-over-from-your-setup) for the rest of your setup.
+  </Tab>
+</Tabs>
+
+### Choose an install scope
+
+A plugin's install scope decides who gets the plugin and which settings file records it as enabled:
+
+* **User scope**: the plugin is enabled for you in every project on this machine. The entry goes in `enabledPlugins` in `~/.claude/settings.json`.
+* **Project scope**: the plugin is enabled for everyone who works in this repository. The entry goes in `.claude/settings.json`, which you commit.
+* **Local scope**: the plugin is enabled for you in this repository only. The entry goes in `.claude/settings.local.json`.
+
+Some plugins are set by their author to start turned off, through the [`defaultEnabled`](/docs/en/plugins/manifest-reference#defaultenabled) field. Such a plugin is installed but stays off until you turn it on with `claude plugin enable <name>` in your shell, or from the **Installed** tab of `/plugin` in a session.
+
+When the same plugin is set at several scopes, the local setting overrides the project setting, and the project setting overrides the user setting. See [Find where a plugin is enabled](/docs/en/plugins/loading#find-where-a-plugin-is-enabled) for the full rule.
+
+The terminal, the desktop app's local sessions, and the VS Code extension on one computer read the same settings files, so a plugin you install at user scope in any of them is available in the other two.
+
+<h3 id="other-places-you-run-claude-code">
+  JetBrains, non-interactive runs, and the Agent SDK
+</h3>
+
+Some places you run Claude Code have no plugin browser of their own:
+
+* **JetBrains IDEs**: the JetBrains plugin runs Claude Code in the IDE's terminal, so use the **Terminal** tab's steps there.
+* **`claude -p` and other non-interactive runs**: `/plugin` doesn't run, and Claude replies `/plugin isn't available in this environment.` Plugins you already installed do load. Install and manage them from your shell with [`claude plugin` commands](#install-from-your-shell).
+* **Agent SDK**: load plugins through the SDK's plugin option. See [Load plugins in the Agent SDK](/docs/en/agent-sdk/plugins).
+
+If Claude Code reports that a plugin enabled in the repository's `.claude/settings.json` isn't installed, see [Enabled in project settings but not installed](/docs/en/plugins/loading#enabled-in-project-settings-but-not-installed).
+
+<Tip>
+  If you're a plugin author testing a copy of your plugin on disk, start Claude Code from your shell with `--plugin-dir` to load it for one session instead of installing it. See [Flags that load a plugin for one session](/docs/en/plugins/cli-reference#flags-that-load-a-plugin-for-one-session).
+</Tip>
+
+<h3 id="plugins-from-your-claude-ai-account">
+  Plugins from your claude.ai account
+</h3>
+
+Your claude.ai account is a separate source of plugins, alongside the marketplaces you install from:
+
+* **What arrives**: every plugin you turn on for your claude.ai account, and every plugin your organization turns on for its members. In a terminal session they sync in the background each time you start Claude Code while signed in with that account; in Cowork sessions they download when the session starts.
+* **Where you see them**: in `/plugin` and `claude plugin list` under the ID `<name>@synced`. You can turn one off at your own scope unless your organization requires it.
+* **What doesn't go the other way**: plugins you install with `/plugin` or `claude plugin install` stay on this machine and aren't added to your claude.ai account.
+
+For sync timing, sign-in requirements, and turning sync off, see [Plugins synced from claude.ai](/docs/en/plugins/loading#synced-plugins).
+
+### Install from your shell
+
+Run `claude plugin install` in your shell to install a plugin without starting a Claude Code session, for example from a setup script.
+
+* **Scope**: user scope by default. Pass `--scope project` or `--scope local` to change it.
+* **When the plugins load**: plugins it installs load the next time you start Claude Code, or when you run `/reload-plugins` in a session that's already open.
+* **The marketplace must be added first**: on a machine where no one has opened an interactive Claude Code session yet, the official marketplace isn't registered, so a script that installs from it runs `claude plugin marketplace add anthropics/claude-plugins-official` before the install.
+
+```bash theme={null}
+claude plugin install formatter@your-org --scope project
 ```
 
-`/plugin` opens an interactive panel in the terminal CLI. If Claude replies that `/plugin` isn't available in this environment, install the plugin another way:
-
-* **Claude desktop app**: use the [plugin browser](/docs/en/desktop#install-plugins).
-* **VS Code extension**: install from the [**Manage plugins** dialog](/docs/en/vs-code#manage-plugins).
-* **Cloud sessions**: enable the plugin for your claude.ai account so Claude Code loads it as a [synced plugin](/docs/en/plugins-reference#synced-plugins).
-
-If the install fails, match the message Claude Code reports:
-
-* `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.
-* The plugin is [not found in the marketplace](#install-plugins): check the plugin name.
-
-<Note>
-  The official marketplace is curated by Anthropic, and inclusion is at Anthropic's discretion. The in-app submission forms add plugins to the [community marketplace](#community-marketplace), not the official one. To distribute plugins independently, [create your own marketplace](/docs/en/plugin-marketplaces) and share it with users.
-</Note>
-
-The official marketplace includes several categories of plugins:
-
-### Code intelligence
-
-Code intelligence plugins enable Claude Code's built-in LSP tool, giving Claude the ability to jump to definitions, find references, and see type errors immediately after edits. These plugins configure [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) connections, the same technology that powers VS Code's code intelligence. In [cloud sessions](/docs/en/claude-code-on-the-web), Claude Code doesn't start plugin language servers, so Claude doesn't get the LSP tool there.
-
-Install the language server binary from the table below before using these plugins; the plugin doesn't install it for you. If you already have a language server installed, Claude may prompt you to install the corresponding plugin when you open a project.
-
-| Language   | Plugin              | Binary required              |
-| :--------- | :------------------ | :--------------------------- |
-| C/C++      | `clangd-lsp`        | `clangd`                     |
-| C#         | `csharp-lsp`        | `csharp-ls`                  |
-| Go         | `gopls-lsp`         | `gopls`                      |
-| Java       | `jdtls-lsp`         | `jdtls`                      |
-| Kotlin     | `kotlin-lsp`        | `kotlin-language-server`     |
-| Lua        | `lua-lsp`           | `lua-language-server`        |
-| PHP        | `php-lsp`           | `intelephense`               |
-| Python     | `pyright-lsp`       | `pyright-langserver`         |
-| Rust       | `rust-analyzer-lsp` | `rust-analyzer`              |
-| Swift      | `swift-lsp`         | `sourcekit-lsp`              |
-| TypeScript | `typescript-lsp`    | `typescript-language-server` |
-
-You can also [create your own LSP plugin](/docs/en/plugins-reference#lsp-servers) for other languages.
-
-<Note>
-  If you see `Executable not found in $PATH` in the `/plugin` Errors tab after installing a plugin, install the binary the [code intelligence](#code-intelligence) table lists for that plugin.
-</Note>
-
-#### What Claude gains from code intelligence plugins
-
-Once a code intelligence plugin is installed and its language server binary is available, Claude gains two capabilities:
-
-* **Automatic diagnostics**: after every file edit Claude makes, the language server reports errors and warnings back, so Claude sees type errors, missing imports, and syntax issues without running a compiler or linter. If Claude introduces an error, it notices and fixes it in the same turn.
-* **Code navigation**: Claude can use the language server to jump to definitions, find references, get type info on hover, list symbols, find implementations, and trace call hierarchies. These operations give Claude more precise navigation than grep-based search, though availability may vary by language and environment.
-
-You don't need to configure diagnostics beyond installing the plugin. To read them yourself, press **Ctrl+O** when Claude Code shows an indicator such as **Found 3 new diagnostic issues in 2 files**.
-
-If you run into issues, see [Code intelligence troubleshooting](#code-intelligence-issues).
-
-### External integrations
-
-These plugins bundle pre-configured [MCP servers](/docs/en/mcp) so you can connect Claude to external services without manual setup:
-
-* **Source control**: `github`, `gitlab`
-* **Project management**: `atlassian` (Jira/Confluence), `asana`, `linear`, `notion`
-* **Design**: `figma`
-* **Infrastructure**: `vercel`, `firebase`, `supabase`
-* **Communication**: `slack`
-* **Monitoring**: `sentry`
-
-### Automatic security review
-
-The `security-guidance` plugin reviews each change Claude makes for common vulnerabilities and instructs Claude to fix what it finds in the same session. See [Catch security issues as Claude writes code](/docs/en/security-guidance) for what it checks and how to add project-specific rules.
-
-### Development workflows
-
-Plugins that add skills and agents for common development tasks:
-
-* **commit-commands**: Git commit workflows including commit, push, and PR creation
-* **pr-review-toolkit**: specialized agents for reviewing pull requests
-* **agent-sdk-dev**: tools for building with the Claude Agent SDK
-* **plugin-dev**: toolkit for creating your own plugins
-
-### Output styles
-
-Customize how Claude responds:
-
-* **explanatory-output-style**: educational insights about implementation choices
-* **learning-output-style**: interactive learning mode for skill building
-
-## Community marketplace
-
-The community marketplace at [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) hosts third-party plugins that have passed Anthropic's automated validation and safety screening. Each plugin is pinned to a specific commit SHA in the catalog. Unlike the official marketplace, you add it manually:
-
-```shell theme={null}
-/plugin marketplace add anthropics/claude-plugins-community
+The command prints `Successfully installed plugin: formatter@your-org (scope: project)` when it finishes.
+
+Some plugins install by running a command that their marketplace names, called a [`command` source](/docs/en/plugins/marketplace-reference#command-plugin-source). Claude Code shows you that command and asks you to accept it before it runs. A script has no one to answer that prompt, so pass `--yes` there to accept it.
+
+For every `claude plugin install` flag, see [plugin install](/docs/en/plugins/cli-reference#plugin-install).
+
+## Add a marketplace
+
+You only need this section when the plugin you want isn't in Anthropic's official marketplace, for example one a coworker published or one from Anthropic's community marketplace.
+
+A marketplace is a catalog of plugins, and Claude Code has to know about a marketplace before you can install from it. You add a marketplace once. After that, its plugins appear on the **Discover** tab and install with `/plugin install <plugin>@<marketplace>` in a session or `claude plugin install <plugin>@<marketplace>` in your shell, where `<marketplace>` is the name the marketplace registered under. To do both in one step, see [Add a marketplace and install in one command](#add-a-marketplace-and-install-in-one-command).
+
+In a Claude Code session, run `/plugin marketplace add` followed by the marketplace's source: a GitHub repository, a git repository on any host, a local directory or file, or a hosted `marketplace.json`.
+
+| Source                     | What you type                                                                                                                                                                                                                       | Example                                                                                                                        |
+| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
+| GitHub repository          | `owner/repo`. Add `#ref` to pin a branch or tag.                                                                                                                                                                                    | `/plugin marketplace add anthropics/claude-code`, or `/plugin marketplace add your-org/plugins#v1.2.0` to pin the `v1.2.0` tag |
+| Git repository on any host | The full clone URL. Add `#ref` to pin a branch or tag.                                                                                                                                                                              | `/plugin marketplace add https://gitlab.example.com/your-group/your-marketplace.git#v1.0.0`                                    |
+| Local directory or file    | A relative or absolute path to a directory that holds `.claude-plugin/marketplace.json`, or to the JSON file itself. Start a relative path with `./` or `../`, because Claude Code reads a bare `name/name` as a GitHub repository. | `/plugin marketplace add ./my-marketplace`                                                                                     |
+| Hosted `marketplace.json`  | Its `https://` URL                                                                                                                                                                                                                  | `/plugin marketplace add https://example.com/marketplace.json`                                                                 |
+
+From your shell, `claude plugin marketplace add` takes the same sources.
+
+<Tip>
+  `/plugin market` also works as a shorter form of `/plugin marketplace`.
+</Tip>
+
+Include the `https://` prefix on every URL, or use the `git@host:path` form for SSH. If you type a bare `gitlab.example.com/your-group/your-marketplace.git`, Claude Code reads it as GitHub `owner/repo` shorthand and rejects it.
+
+When the command succeeds, it prints `Successfully added marketplace: <name>`, and the marketplace's plugins appear on the **Discover** tab the next time you open `/plugin`, with no reload needed. If it fails, match the error message in [Troubleshoot plugins](/docs/en/plugins/troubleshooting#add-a-marketplace).
+
+### Add a marketplace and install in one command
+
+To install a plugin from a marketplace you haven't added yet, run `/plugin install` in a Claude Code session and name the marketplace source with `--marketplace`. Requires Claude Code v2.1.275 or later.
+
+```text theme={null}
+/plugin install deploy-helper --marketplace your-org/plugins
 ```
 
-Then install plugins from it using the `claude-community` marketplace name:
-
-```shell theme={null}
-/plugin install <plugin-name>@claude-community
-```
-
-To submit your own plugin to the community marketplace, see [Submit your plugin to the community marketplace](/docs/en/plugins#submit-your-plugin-to-the-community-marketplace) in the create-plugins guide.
-
-## Try it: add the demo marketplace
-
-Anthropic also maintains a [demo plugins marketplace](https://github.com/anthropics/claude-code/tree/main/plugins) (`claude-code-plugins`) with example plugins that show what's possible with the plugin system. Unlike the official marketplace, you need to add this one manually.
-
-<Steps>
-  <Step title="Add the marketplace">
-    From within Claude Code, run the `plugin marketplace add` command for the `anthropics/claude-code` marketplace:
-
-    ```shell theme={null}
-    /plugin marketplace add anthropics/claude-code
-    ```
-
-    This downloads the marketplace catalog and makes its plugins available to you.
-  </Step>
-
-  <Step title="Browse available plugins">
-    Run `/plugin` to open the plugin manager. This opens a tabbed interface you can cycle through using **Tab**, or **Shift+Tab** to go backward:
-
-    * **Discover**: browse available plugins from all your marketplaces
-    * **Installed**: view and manage your installed plugins
-    * **Marketplaces**: add, remove, or update your added marketplaces
-    * **Errors**: view any plugin loading errors
-    * **Stats**: see [what each of your skills costs in context and how often it gets used](/docs/en/skills#find-unused-skills), in sessions where `/skill-doctor` is available
-
-    Go to the **Discover** tab to see plugins from the marketplace you just added. When your administrator has allowlisted the marketplace via the [`pluginSuggestionMarketplaces`](/docs/en/settings-reference#pluginsuggestionmarketplaces) managed setting, plugins marked as relevant to your current working directory are pinned at the top with a **suggested for this directory** label.
-  </Step>
-
-  <Step title="Install a plugin">
-    Select a plugin to view its details. The details pane shows what the plugin contains and what it costs:
-
-    * A **Context cost** estimate so you can see how many tokens the plugin will add to your [context window](/docs/en/features-overview#understand-context-costs) every turn
-    * The plugin's **Last updated** date
-    * A **Will install** section listing the plugin's commands, agents, skills, hooks, and MCP and LSP servers, so you can review exactly what it adds before installing
-
-    Not every plugin provides the data behind these fields. For plugins from local or custom marketplaces, you may not see the **Context cost** and **Last updated** rows, and the **Will install** section may show **Components will be discovered at installation** instead.
-
-    Choose an installation scope:
-
-    * **User scope**: install for yourself across all projects
-    * **Project scope**: install for all collaborators on this repository
-    * **Local scope**: install for yourself in this repository only
-
-    For example, select **commit-commands**, a plugin that adds git workflow skills, and install it to your user scope.
-
-    You can also start the install from the command line:
-
-    ```shell theme={null}
-    /plugin install commit-commands@claude-code-plugins
-    ```
-
-    See [Settings files](/docs/en/settings#where-settings-live) to learn more about scopes.
-  </Step>
-
-  <Step title="Use your new plugin">
-    If the install summary reports `Run /reload-plugins to activate.`, Claude Code then runs that reload for you. If the reload warns that your next message would re-read the conversation, run `/reload-plugins --force` to activate the plugin.
-
-    Plugin skills are namespaced by the plugin name, so **commit-commands** provides skills like `/commit-commands:commit`.
-
-    Try it out by making a change to a file and running:
-
-    ```shell theme={null}
-    /commit-commands:commit
-    ```
-
-    This stages your changes, generates a commit message, and creates the commit.
-
-    Each plugin works differently. Check the plugin's details in the **Discover** tab to see the commands and skills it provides, or visit its homepage for usage guidance.
-  </Step>
-</Steps>
-
-## Add marketplaces
-
-Use the `/plugin marketplace add` command to add marketplaces from different sources.
-
-<Tip>
-  **Shortcuts**: You can use `/plugin market` instead of `/plugin marketplace`, and `rm` instead of `remove`.
-</Tip>
-
-* **GitHub repositories**: `owner/repo` format, for example `anthropics/claude-code`
-* **Git URLs**: any git repository URL, including GitLab, Bitbucket, and self-hosted servers
-* **Local paths**: directories or direct paths to `marketplace.json` files
-* **Remote URLs**: direct URLs to hosted `marketplace.json` files
-* **claude.ai**: marketplaces hosted on claude.ai for your account, such as your organization's plugin library, which you [add by name from the **Marketplaces** tab or your shell](#add-from-claude-ai) rather than by source
-
-### Add from GitHub
-
-Add a GitHub repository that contains a `.claude-plugin/marketplace.json` file using the `owner/repo` format, where `owner` is the GitHub username or organization and `repo` is the repository name.
-
-For example, `anthropics/claude-code` refers to the `claude-code` repository owned by `anthropics`:
-
-```shell theme={null}
-/plugin marketplace add anthropics/claude-code
-```
-
-### Add from other Git hosts
-
-Add a git marketplace repository by providing its full URL. For an `https://` URL, whether to include the `.git` suffix depends on the host:
-
-* **`github.com` and `gitlab.com`**: Claude Code recognizes a repository URL with or without the `.git` suffix and clones it. Adding a `gitlab.com` URL without the suffix requires Claude Code v2.1.232 or later. Before v2.1.232, Claude Code treated it as a direct link to a hosted `marketplace.json` file.
-* **Azure DevOps**: omit the suffix. Claude Code clones any URL whose path contains `/_git/`. If you append `.git` to a `/_git/` path, the clone fails.
-* **Every other host, including self-managed GitLab servers**: include the `.git` suffix so Claude Code clones the repository rather than treating the URL as a direct link to a hosted `marketplace.json` file. For a host whose clone URLs don't carry the suffix, such as AWS CodeCommit, add the marketplace as a git entry in [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) instead. Claude Code clones a git entry whether or not its URL ends in `.git`.
-
-Claude Code also clones a `gitlab.com` URL with nested subgroups, such as `https://gitlab.com/group/subgroup/project`.
-
-Include the `https://` prefix. Claude Code v2.1.196 and later reject a host typed without it, such as `gitlab.com/company/plugins.git`, as an invalid GitHub `owner/repo` shorthand, and the error tells you to add the prefix. Earlier versions misread it as a GitHub repository path and fail at clone time.
-
-Using HTTPS:
-
-```shell theme={null}
-/plugin marketplace add https://gitlab.com/company/plugins.git
-```
-
-Using SSH:
-
-```shell theme={null}
-/plugin marketplace add git@gitlab.com:company/plugins.git
-```
-
-Claude Code clones an SSH address whether or not it ends in `.git`.
-
-To add a specific branch or tag, append `#` followed by the ref:
-
-```shell theme={null}
-/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0
-```
-
-### Add from local paths
-
-Add a local directory that contains a `.claude-plugin/marketplace.json` file:
-
-```shell theme={null}
-/plugin marketplace add ./my-marketplace
-```
-
-You can also add a direct path to a `marketplace.json` file:
-
-```shell theme={null}
-/plugin marketplace add ./path/to/marketplace.json
-```
-
-### Add from remote URLs
-
-Add a remote `marketplace.json` file via URL:
-
-```shell theme={null}
-/plugin marketplace add https://example.com/marketplace.json
-```
-
-<Note>
-  URL-based marketplaces have some limitations compared to Git-based marketplaces. If plugin installs from a URL-based marketplace fail, see [Troubleshooting](/docs/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces).
-</Note>
-
-### Add from claude.ai
-
-In terminal sessions where [plugins sync from your claude.ai account](/docs/en/plugins-reference#synced-plugins), claude.ai can also list marketplaces for you, such as your organization's plugin library and your own claude.ai uploads. `claude plugin marketplace list` prints them in a `From claude.ai:` section, and the `/plugin` **Marketplaces** tab lists them. Select one there to add it. Adding a marketplace from claude.ai requires Claude Code v2.1.273 or later.
-
-To add a marketplace from that list in your shell instead, run `claude plugin marketplace add` with the `--claudeai` flag and the name the list shows:
+The source takes [the same forms as `/plugin marketplace add`](#add-a-marketplace), such as GitHub `owner/repo`, a git URL, or a local path, except that it can't contain spaces. Give the plugin name by itself, without an `@marketplace` suffix.
+
+If you haven't added that marketplace yet, Claude Code shows the source it resolved and asks you to confirm before adding it. Once the marketplace is added, the plugin's details open and you choose an [installation scope](#install-a-plugin). If the source matches a marketplace you've already added, Claude Code skips the confirmation and opens the plugin's details in that marketplace.
+
+### Add a private marketplace
+
+A private marketplace is one in a repository you need credentials to clone, on GitHub or any other git host. You add it with the same `/plugin marketplace add` or `claude plugin marketplace add` command as a public one. Claude Code clones it with the git credentials already on your machine and never prompts, so each way of connecting has a requirement:
+
+* **HTTPS**: your git credential helpers apply, so access you set up with `gh auth login`, the macOS Keychain, or `git-credential-store` works. Interactive prompts are suppressed, so a host you have never authenticated to fails instead of asking for a password.
+* **SSH**: the host must already be in your `known_hosts` file and the key must work without a passphrase prompt, because the host-fingerprint and passphrase prompts are suppressed too.
+* **GitHub `owner/repo` shorthand**: Claude Code checks whether your SSH key authenticates to `github.com`, then clones over SSH if it does and over HTTPS if it doesn't. Set [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/en/env-vars#variables) to skip that check and always clone over HTTPS.
+
+The same credentials apply when you run `/plugin install`, `/plugin marketplace update`, and `claude plugin update`.
+
+On a GitHub Enterprise Server host, see [Plugin marketplaces on GHES](/docs/en/github-enterprise-server#plugin-marketplaces-on-ghes) for the credentials each operation needs.
+
+If your organization registers the marketplace for you through managed settings, you don't add it yourself. See [Pre-install and require plugins](/docs/en/plugins/org#pre-install-and-require-plugins).
+
+<h3 id="add-from-claude-ai">
+  Add a marketplace from claude.ai
+</h3>
+
+In terminal sessions where [plugins sync from your claude.ai account](/docs/en/plugins/loading#synced-plugins), claude.ai can also list plugin marketplaces for you, such as your organization's plugin library and your own claude.ai uploads. You add one of these by its name rather than by a source. Adding a marketplace from claude.ai requires Claude Code v2.1.273 or later.
+
+Add a claude.ai marketplace from the `/plugin` panel or from your shell:
+
+* **Inside a session**: run `/plugin` and go to the **Marketplaces** tab, which lists the marketplaces from claude.ai. Select one there to add it.
+* **From your shell**: run `claude plugin marketplace list`, which prints them in a `From claude.ai:` section. Then run `claude plugin marketplace add` with the `--claudeai` flag and the name shown in the list.
+
+For example, this command adds a marketplace named `claudeai-organization-library`:
 
 ```bash theme={null}
 claude plugin marketplace add --claudeai claudeai-organization-library
 ```
 
-Claude Code registers the marketplace under a local name that starts with `claudeai-`, derived from the name that claude.ai lists it under: a marketplace listed as "Organization library" registers as `claudeai-organization-library`. Install its plugins by that name, for example with `claude plugin install <plugin>@claudeai-organization-library`.
-
-If you sign out or sign in with a different account, the marketplace stays configured but shows no plugins, and the plugins you already installed from it keep loading.
-
-The `From claude.ai:` section can also list git-based marketplaces shared through claude.ai. You add those with the ordinary `marketplace add` command, using the source that the list prints.
-
-## Install plugins
-
-Once you've added marketplaces, you can install a plugin by name. For a marketplace you haven't added yet, you can instead [add it and install in one command](#add-a-marketplace-and-install-in-one-command).
-
-To install by name:
-
-```shell theme={null}
-/plugin install plugin-name@marketplace-name
-```
-
-The command opens that plugin's details, where you choose an [installation scope](/docs/en/settings#where-settings-live). You see the same choices when you run `/plugin`, go to the **Discover** tab, and press **Enter** on a plugin:
-
-* **User scope**: install for yourself across all projects
-* **Project scope**: install for all collaborators on this repository, which adds the plugin to `.claude/settings.json`
-* **Local scope**: install for yourself in this repository only, not shared with collaborators
-
-To install without an interactive step, use the [`claude plugin install`](/docs/en/plugins-reference#plugin-install) shell command, which installs to user scope unless you pass `--scope`. For a plugin with a [`command` source](/docs/en/plugin-marketplaces#how-users-accept-the-command), pass `--yes` to accept the command it displays.
-
-You may also see plugins with **managed** scope. These are installed by administrators via [managed settings](/docs/en/managed-settings) and can't be modified.
-
-Claude Code looks the plugin up in its local copy of the marketplace catalog. How you name the plugin controls whether Claude Code refreshes that copy first:
-
-* **With a marketplace name**: when you install `plugin-name@marketplace-name`, in a session or with `claude plugin install`, Claude Code refreshes that marketplace before the lookup. Claude Code runs the refresh even if you turned off [auto-update](#configure-auto-updates) for the marketplace or set `DISABLE_AUTOUPDATER`. Before v2.1.232, Claude Code didn't refresh the marketplace before the lookup. Claude Code skips this refresh when:
-  * The marketplace wasn't [added from GitHub, another Git host, a remote URL](#add-marketplaces), or [claude.ai](#add-from-claude-ai).
-  * A [seed directory](/docs/en/plugin-marketplaces#pre-populate-plugins-for-containers) supplies the marketplace.
-  * Claude Code refreshed the marketplace within the last 30 seconds.
-  * You set [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/en/env-vars).
-  * [Managed settings](/docs/en/plugin-marketplaces#managed-marketplace-restrictions) block the marketplace, in which case Claude Code also refuses the install.
-* **Plugin name only**: when you run `/plugin install plugin-name` in a session, Claude Code refreshes only the marketplaces it also [updates in the background](#configure-auto-updates), and only after the lookup misses. When you run `claude plugin install plugin-name`, Claude Code reads the cached catalogs without refreshing. To install a plugin that was published after your last refresh, run `/plugin marketplace update <marketplace-name>` in a session or [`claude plugin marketplace update <marketplace-name>`](/docs/en/plugin-marketplaces#plugin-marketplace-update) in your shell, then retry the install.
-
-If the refresh before a named install fails, for example because you're offline, Claude Code looks the plugin up in the cached catalog anyway. `claude plugin install` reports `marketplace not refreshed` in its success message, and `/plugin install` shows the failure above the plugin's details or in its not-found message.
-
-When you install from the `/plugin` interface, the install summary tells you whether the plugin is active in your current session:
-
-* `Plugin is now active.`: Claude Code activated the plugin as part of the install.
-* `Run /reload-plugins to activate.`: the plugin isn't active yet, because activating it would [invalidate the prompt cache](/docs/en/prompt-caching#enabling-or-disabling-a-plugin) or because the activation attempt failed. Claude Code then runs `/reload-plugins` for you. If that reload warns about the prompt cache, run `/reload-plugins --force` to [activate the plugin anyway](#apply-plugin-changes-without-restarting).
-* If the plugin fails to load, the summary reports the failure and the `/plugin` **Errors** tab shows the detail.
-
-Before v2.1.221, no install took effect in the current session until you ran `/reload-plugins` or restarted.
-
-The `claude plugin install` shell command doesn't run in a session, so Claude Code loads the plugins it installs the next time you start Claude Code, or when you run `/reload-plugins` in a session that's already open.
-
-<Warning>
-  Make sure you trust a plugin before installing it. Anthropic doesn't control what MCP servers, files, or other software are included in plugins and can't verify that they work as intended. Check each plugin's homepage for more information.
-</Warning>
-
-### Add a marketplace and install in one command
-
-To install a plugin from a marketplace you haven't added yet, name the marketplace source with `--marketplace`. Requires Claude Code v2.1.275 or later.
-
-```shell theme={null}
-/plugin install quality-review-plugin --marketplace your-org/plugins
-```
-
-The source takes [the same forms as `/plugin marketplace add`](#add-marketplaces), such as GitHub `owner/repo`, a git URL, or a local path, except that it can't contain spaces. Give the plugin name bare, without an `@marketplace` suffix.
-
-Claude Code shows the source it resolved and asks you to confirm before adding the marketplace. Declining cancels the install and adds nothing. Once the marketplace is added, the plugin's details open and you choose an [installation scope](/docs/en/settings#where-settings-live). If the source matches a marketplace you've already added, Claude Code skips the confirmation and opens the plugin's details in that marketplace.
+Claude Code registers the marketplace under a local name that starts with `claudeai-`, derived from the name that claude.ai lists it under. For example, a marketplace listed as "Organization library" becomes `claudeai-organization-library`. Install its plugins by that name, for example with `claude plugin install <plugin>@claudeai-organization-library`.
+
+If you sign out, or sign in to a different claude.ai organization, the marketplace stays configured but shows no plugins, and the plugins you already installed from it keep loading.
+
+The `From claude.ai:` section can also list git-based marketplaces shared through claude.ai, and it prints a source for each of those. Add them by that source as in [Add a marketplace](#add-a-marketplace), not with `--claudeai`.
 
 ## Manage installed plugins
 
-Run `/plugin` and go to the **Installed** tab to view, enable, disable, or uninstall your plugins. The list is grouped by scope and sorted so you see problems first: plugins with load errors or unresolved dependencies appear at the top, followed by your favorites, with disabled plugins folded behind a collapsed header at the bottom.
-
-From the list you can:
-
-* press `f` to favorite or unfavorite the selected plugin
-* type to filter by plugin name or description
-* press Enter to open a plugin's detail view and enable, disable, or uninstall it
-
-Claude Code also lists the [plugins synced from your claude.ai account](/docs/en/plugins-reference#synced-plugins) in the **Installed** tab, with `synced` as their source. You can enable or disable one there unless your organization marked it as required. To remove one, turn it off on claude.ai. Synced plugins appear in terminal sessions on Claude Code v2.1.273 or later.
-
-When you uninstall a plugin that a project's `.claude/settings.json` enables, Claude Code asks which scope you mean: disable it for you alone, which writes an override to your `.claude/settings.local.json` and leaves the plugin installed for the project, or uninstall it for everyone, which removes it from the shared `.claude/settings.json`.
-
-The detail view shows the components the plugin contributes: commands, skills, agents, hooks, MCP servers, and LSP servers. The same inventory is available from the command line with `claude plugin details`.
-
-Claude Code also lists marketplace plugins you installed yourself but haven't used in at least two weeks, over a span of at least 10 sessions, under a **Not used recently** header in the **Installed** tab. The detail view shows a **Last used** line for each plugin. Use these to find plugins that still add startup and context cost even though you no longer use them, then disable or uninstall them.
-
-Two kinds of plugins are never listed as unused:
-
-* plugins that your organization manages or that you load with `--plugin-dir`
-* plugins that contribute a theme, output style, monitor, or workflow, since those deliver value without an invocation to track
-
-The **Not used recently** header and the **Last used** line are both hidden when your organization restricts marketplaces with [`strictKnownMarketplaces`](/docs/en/settings-reference#strictknownmarketplaces).
-
-A plugin's [language server](/docs/en/plugins#add-lsp-servers-to-your-plugin) counts as used when it delivers diagnostics or answers a code navigation request, so an LSP plugin whose server is active in your sessions isn't listed as unused. Before v2.1.203, language server activity couldn't be counted as use, so plugins that contribute an LSP server were exempt from the group entirely, the same way theme and output style plugins still are.
-
-The first session on a version that counts language server activity also resets the usage record of each LSP plugin that hadn't recorded any use yet, so Claude Code doesn't judge a plugin you installed earlier as unused based on data recorded before its server activity was tracked.
-
-When you install a plugin that declares dependencies, the install output lists which dependencies were auto-installed alongside it.
-
-You can also manage plugins with direct commands:
-
-* When you run `/plugin disable`, `/plugin enable`, or `/plugin uninstall`, Claude Code opens the plugin panel to make the change and leaves it open. Press **Esc** to close the panel before typing another command. [Apply plugin changes without restarting](#apply-plugin-changes-without-restarting) describes when the change takes effect in your session.
-* For scripting, use the `claude plugin` shell commands instead, which don't open the panel.
-
-List installed plugins without opening the menu:
-
-```shell theme={null}
-/plugin list
-```
-
-Pass `--enabled` or `--disabled` to show only plugins in that state.
-
-Disable a plugin without uninstalling:
-
-```shell theme={null}
-/plugin disable plugin-name@marketplace-name
-```
-
-Re-enable a disabled plugin:
-
-```shell theme={null}
-/plugin enable plugin-name@marketplace-name
-```
-
-In these identifiers, `plugin-name` is the plugin's `name` in the [marketplace entry](/docs/en/plugin-marketplaces#plugin-entries), which can differ from the `name` in the plugin's own `plugin.json`.
-
-As of Claude Code v2.1.195, **Enable** and **Disable** in the `/plugin` interface work for plugins whose two names differ, and `/plugin enable` and `/plugin disable` accept either name. When you disable such a plugin in an earlier version, Claude Code reports `already disabled` and leaves it enabled.
-
-Completely remove a plugin:
-
-```shell theme={null}
-/plugin uninstall plugin-name@marketplace-name
-```
-
-The `--scope` option lets you target a specific scope with CLI commands:
-
-```shell theme={null}
-claude plugin install formatter@your-org --scope project
+The **Installed** tab in `/plugin` lists your plugins with actions to enable, disable, update, or uninstall each one. In a Claude Code session, run `/plugin` and press **Tab** to reach it, or run `/plugin enable`, `/plugin disable`, or `/plugin uninstall` to open the panel and make that change there. Disabled plugins are grouped under a collapsed header at the bottom of the list. Use these keys on the list:
+
+* Type to filter by name or description.
+* Press **Space** to enable or disable the selected plugin, and **f** to favorite it.
+* Press **Enter** to open a plugin's details. The menu there offers **Disable plugin** or **Enable plugin**, **Update now**, and **Uninstall**. Plugins that take settings also offer **Configure options**.
+
+The tab can also show plugins at **Managed** scope. Your organization installed those through [managed settings](/docs/en/settings#settings-files), and you can't enable, disable, or uninstall them here.
+
+For a synced plugin that your organization requires on claude.ai, see [Manage plugins synced from claude.ai](#manage-plugins-synced-from-claude-ai).
+
+When you close the `/plugin` panel with pending changes you made in it, Claude Code runs `/reload-plugins` for you to apply them. If the reload would [invalidate the prompt cache](/docs/en/prompt-caching#enabling-or-disabling-a-plugin), it warns and leaves the changes pending instead. Run `/reload-plugins --force` to apply them anyway.
+
+### Manage plugins synced from claude.ai
+
+The **Installed** tab in `/plugin` also lists the [plugins synced from your claude.ai account](/docs/en/plugins/loading#synced-plugins), with `synced` as their source. Synced plugins appear in terminal sessions on Claude Code v2.1.273 or later.
+
+* **Enable or disable**: use the **Installed** tab, unless your organization marked the plugin as required.
+* **Remove**: turn the plugin off on claude.ai.
+
+When Claude Code syncs an added, updated, or removed plugin into an interactive session, you see `Plugins changed. Run /reload-plugins to activate.` Run `/reload-plugins` to load the change in that session, or leave it for the next time you start Claude Code.
+
+### Uninstall a plugin the project enables
+
+When you choose **Uninstall** for a plugin that this repository's `.claude/settings.json` enables, whether from the **Installed** tab or with `/plugin uninstall`, Claude Code asks whether to disable it for you or uninstall it for everyone:
+
+* **Disable for me**: press **y**. Claude Code writes `false` for the plugin in your `.claude/settings.local.json` and leaves it installed for the project.
+* **Uninstall for everyone**: press **u**. Claude Code removes the plugin from the shared `.claude/settings.json`.
+
+### See what an installed plugin adds to your sessions
+
+In your shell, run `claude plugin details <name>` for an installed plugin. The `Always-on` line is the number of tokens the plugin adds to every session where it's enabled, and the per-component rows show which skill or agent contributes most. For the full output and what each figure means, see [Measure what a plugin costs](/docs/en/plugins/measure#measure-what-a-plugin-costs).
+
+### Find plugins you no longer use
+
+On the **Installed** tab in `/plugin`, plugins you installed yourself and haven't used recently appear under a **Not used recently** header, and each plugin's details show a **Last used** line. Use that header and that line to find plugins that still add startup and context cost, then disable or uninstall them.
+
+### Plugins with dependencies
+
+A plugin can declare other plugins that it depends on. When you install, disable, or uninstall such a plugin from a marketplace, Claude Code acts on those dependencies too:
+
+* **Install**: Claude Code also installs and enables the plugin's declared dependencies at the same scope. The success message lists them.
+* **Enable**: Claude Code also enables the plugin's dependencies that are installed but disabled. If a declared dependency isn't installed, the enable fails and the message tells you to install it first.
+* **Disable**: when another enabled plugin still needs the one you named, Claude Code refuses and prints a chained command that disables both in the right order.
+* **Uninstall**: auto-installed dependencies stay until you run `claude plugin prune` in your shell; see [plugin prune](/docs/en/plugins/cli-reference#plugin-prune).
+
+If you loaded the plugin with `--plugin-dir` instead, see [Test a plugin and its dependency locally](/docs/en/plugins/dependencies#test-a-plugin-and-its-dependency-locally).
+
+### Manage plugins from your shell
+
+You can also manage plugins without starting a Claude Code session. In your shell, run `claude plugin install`, `enable`, `disable`, or `uninstall` as ordinary terminal commands; they change the same settings the `/plugin` panel does. Each takes `--scope` to target one scope, and uses a default scope when you omit it:
+
+* `enable` and `disable` act on the most specific scope whose settings already list the plugin.
+* `install` and `uninstall` act on user scope.
+
+For example, these commands disable and re-enable a plugin, then uninstall it at project scope:
+
+```bash theme={null}
+claude plugin disable formatter@your-org
+claude plugin enable formatter@your-org
 claude plugin uninstall formatter@your-org --scope project
 ```
 
-### Apply plugin changes without restarting
-
-When you close the `/plugin` menu, Claude Code runs `/reload-plugins` for you to apply the changes you made in it, such as installing, enabling, disabling, and uninstalling plugins. If the reload would [invalidate the prompt cache](/docs/en/prompt-caching#enabling-or-disabling-a-plugin), it warns and leaves the changes pending instead; run `/reload-plugins --force` to apply them anyway. If Claude is still responding when you close the menu, the reload runs after the response finishes.
-
-For plugin changes that happen outside the menu, run `/reload-plugins` yourself. These changes include:
-
-* A `claude plugin` command you ran in another terminal
-* Edits to a plugin you loaded with [`--plugin-dir`](/docs/en/plugins#test-your-plugins-locally) while you develop it
-* A plugin [auto-update](#configure-auto-updates) whose notification asks you to reload
-* A [sync from your claude.ai account](/docs/en/plugins-reference#synced-plugins) that added, updated, or removed a plugin and showed a notification asking you to reload
-* A change in a [`--plugin-dir` folder](/docs/en/plugins#test-your-plugins-locally) that Claude Code held because applying it would invalidate the prompt cache
-
-Before v2.1.268, plugins you enabled, disabled, or uninstalled in the menu, and installs that didn't activate during the install, stayed pending until you ran `/reload-plugins`.
-
-`/reload-plugins` also runs in sessions without an interactive terminal, such as the desktop app, the Agent SDK, and [non-interactive mode](/docs/en/headless) with `-p`. Requires Claude Code v2.1.260 or later. Two limits apply in those sessions:
-
-* The command runs only when you type it directly into the session, such as in the `-p` prompt or the desktop app's prompt box. When you send it over a remote connection instead, such as [Remote Control](/docs/en/remote-control) or a relayed chat message, the command declines without reloading anything.
-* The reload doesn't connect or disconnect plugin MCP servers. Those changes take effect in your next session.
-
-Claude Code reloads all active plugins and shows counts for plugins, skills, agents, hooks, plugin MCP servers, and plugin LSP servers, omitting the plugin MCP server count in a session without an interactive terminal. In the skills count, Claude Code includes every skill a plugin provides: both its `commands/` entries and its `SKILL.md` skills. Before v2.1.246, Claude Code counted only `commands/` entries, so it could reload a plugin's `SKILL.md` skills and still report `0 skills` in the summary.
-
-Reloading has a token cost on the next request: newly loaded components announce themselves in content appended to the conversation, while the existing history still reads from the prompt cache. A plugin that provides MCP servers costs more when its tools aren't deferred by [tool search](/docs/en/mcp#scale-with-mcp-tool-search): the change invalidates the cache and the next request re-reads the entire conversation. See [enabling or disabling a plugin](/docs/en/prompt-caching#enabling-or-disabling-a-plugin) for details.
+## Keep plugins updated
+
+Plugins update automatically when the marketplace they came from has auto-update turned on. After a session starts, Claude Code refreshes those marketplaces and updates the on-disk copies of the plugins you installed from them.
+
+The running session keeps the versions it already loaded. After an update, you see `Plugin updated: <name> · Run /reload-plugins to apply`, and the next session loads the new versions automatically.
+
+These are the auto-update defaults for each kind of marketplace:
+
+* **On by default**: `claude-plugins-official` and the other [official marketplace names](/docs/en/plugins/security#official-marketplace-names) except `knowledge-work-plugins` and `first-party-plugins`, plus [marketplaces added from claude.ai](#add-from-claude-ai).
+* **Off by default**: every other marketplace, including the community marketplace, third-party marketplaces, and local development marketplaces.
+
+For when auto-update runs, which plugins it skips, and the environment variables that turn it off, see [When auto-update runs](/docs/en/plugins/loading#when-auto-update-runs).
+
+### Turn auto-update on or off for a marketplace
+
+In a Claude Code session, run `/plugin` and go to the **Marketplaces** tab. Select the marketplace, then select **Enable auto-update** or **Disable auto-update**.
+
+### Update one plugin now
+
+In a session, open the plugin on the **Installed** tab in `/plugin` and select **Update now**, or in your shell run `claude plugin update <plugin>@<marketplace>`.
+
+### Auto-update from a private marketplace
+
+For a private marketplace, see [What background auto-update does with credentials](/docs/en/plugins/host-marketplace#what-background-auto-update-does-with-credentials) for how background auto-updates authenticate over SSH and HTTPS, and [Troubleshoot plugins](/docs/en/plugins/troubleshooting#add-a-marketplace) for the messages you see when they fail.
 
 ## Manage marketplaces
 
-You can manage marketplaces through the interactive `/plugin` interface or with CLI commands.
-
-### Use the interactive interface
-
-Run `/plugin` and go to the **Marketplaces** tab to:
-
-* View all your added marketplaces with their sources and status
-* Add new marketplaces
-* Update marketplace listings to fetch the latest plugins
-* Remove marketplaces you no longer need
-
-### Use CLI commands
-
-You can also manage marketplaces with direct commands.
-
-List all configured marketplaces:
-
-```shell theme={null}
-/plugin marketplace list
-```
-
-Refresh plugin listings from a marketplace:
-
-```shell theme={null}
-/plugin marketplace update marketplace-name
-```
-
-Remove a marketplace:
-
-```shell theme={null}
-/plugin marketplace remove marketplace-name
-```
-
-<Warning>
-  Removing a marketplace will uninstall any plugins you installed from it.
-</Warning>
-
-### Configure auto-updates
-
-Claude Code can automatically update marketplaces and their installed plugins in the background after startup. When auto-update is enabled for a marketplace, Claude Code refreshes the marketplace data and updates installed plugins to their latest versions on disk.
-
-Claude Code checks for marketplace and plugin updates after your session starts, with a random delay of up to ten minutes, so the running session keeps using the versions it loaded at launch. If any plugins were updated, you'll see a notification prompting you to run `/reload-plugins`, or the new versions load on your next launch.
-
-Auto-update also leaves out a plugin whose marketplace entry declares a `headersHelper`: Claude Code [neither runs the command nor downloads the archive](/docs/en/plugin-marketplaces#installs-and-updates-that-refuse-the-command-instead-of-asking) on that path; that section says when Claude Code lists the plugin in the `/plugin` Errors tab so you can update it from its own view.
-
-Claude Code updates plugins that have a [`command` source](/docs/en/plugin-marketplaces#command-sources) on a separate cadence from the marketplace auto-update setting and from `DISABLE_AUTOUPDATER`. Instead, it [re-runs the command once per session](/docs/en/plugin-marketplaces#when-claude-code-re-runs-the-command) and installs the output as a new plugin version when its [hash](/docs/en/plugins-reference#version-management) has changed.
-
-Toggle auto-update for individual marketplaces through the UI:
-
-1. Run `/plugin` to open the plugin manager
-2. Select **Marketplaces**
-3. Choose a marketplace from the list
-4. Select **Enable auto-update** or **Disable auto-update**
-
-`claude-plugins-official`, most other official Anthropic marketplaces, and [marketplaces added from claude.ai](#add-from-claude-ai) have auto-update enabled by default. Other third-party marketplaces and local development marketplaces have auto-update disabled by default.
-
-Administrators can also set `"autoUpdate": true` on each [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) entry in managed settings to enable auto-update for an organization marketplace without requiring each user to toggle it.
-
-To disable automatic updates for Claude Code and for plugins fetched from marketplaces, set the `DISABLE_AUTOUPDATER` environment variable. Plugins with a [`command` source](/docs/en/plugin-marketplaces#command-sources) follow their own once-per-session re-resolve. See [Auto updates](/docs/en/setup#auto-updates) for details.
-
-To keep plugin auto-updates enabled while disabling Claude Code auto-updates, set `FORCE_AUTOUPDATE_PLUGINS=1` along with `DISABLE_AUTOUPDATER`:
-
-```bash theme={null}
-export DISABLE_AUTOUPDATER=1
-export FORCE_AUTOUPDATE_PLUGINS=1
-```
-
-## Configure team marketplaces
-
-Team admins can set up automatic marketplace installation for projects by adding marketplace configuration to `.claude/settings.json`. Once a team member [trusts the repository folder](/docs/en/permissions#what-runs-before-you-trust-a-folder), Claude Code adds these marketplaces without a further prompt.
-
-As of Claude Code v2.1.195, adding the marketplace doesn't install plugins that come from an external source, on any path that loads plugins. A plugin that only the project's `.claude/settings.json` enables, and that comes from an external source such as a GitHub repository or npm package, doesn't load until the team member installs it. Until then, Claude Code reports the plugin as not installed and shows the `claude plugin install` command to run.
-
-Add `extraKnownMarketplaces` to your project's `.claude/settings.json`:
-
-```json theme={null}
-{
-  "extraKnownMarketplaces": {
-    "my-team-tools": {
-      "source": {
-        "source": "github",
-        "repo": "your-org/claude-plugins"
-      }
-    }
-  }
-}
-```
-
-For full configuration options including `extraKnownMarketplaces` and `enabledPlugins`, see [Plugin settings](/docs/en/settings-reference#plugin-settings).
-
-## Security
-
-Plugins and marketplaces are highly trusted components that can execute arbitrary code on your machine with your user privileges. Only install plugins and add marketplaces from sources you trust. Organizations can restrict which marketplaces users are allowed to add using [managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions).
-
-## Troubleshooting
-
-### /plugin command not recognized
-
-If you see "unknown command" or the `/plugin` command doesn't appear:
-
-1. **Check your version**: run `claude --version` to see what's installed.
-2. **Update Claude Code**:
-   * **Homebrew**: `brew upgrade claude-code`, or `brew upgrade claude-code@latest` if you installed that cask
-   * **npm**: `npm install -g @anthropic-ai/claude-code@latest`
-   * **Native installer**: re-run the install command from [Setup](/docs/en/setup)
-3. **Restart Claude Code**: after updating, restart your terminal and run `claude` again.
-
-### Common issues
-
-If plugin skills don't appear, clear the cache with `rm -rf ~/.claude/plugins/cache`, restart Claude Code, and reinstall the plugin.
-
-For detailed troubleshooting with solutions, see [Troubleshooting](/docs/en/plugin-marketplaces#troubleshooting) in the marketplace guide. For debugging tools, see [Debugging and development tools](/docs/en/plugins-reference#debugging-and-development-tools).
-
-### Code intelligence issues
-
-* **Language server not starting**: verify the binary is installed and available in your `$PATH`. Check the `/plugin` Errors tab for details.
-* **High memory usage**: language servers like `rust-analyzer` and `pyright` can consume significant memory on large projects. If you experience memory issues, disable the plugin with `/plugin disable <plugin-name>` and rely on Claude's built-in search tools instead.
-* **False positive diagnostics in monorepos**: language servers may report unresolved import errors for internal packages if the workspace isn't configured correctly. These don't affect Claude's ability to edit code.
+The **Marketplaces** tab in `/plugin` lists every marketplace you registered, along with its source. Select one to browse its plugins, update its listing, turn auto-update on or off, or remove it.
+
+You can also list, update, and remove marketplaces with commands, from your shell or inside a session:
+
+| Action                         | In your shell                             | Inside a session                    |
+| :----------------------------- | :---------------------------------------- | :---------------------------------- |
+| List marketplaces              | `claude plugin marketplace list`          | `/plugin marketplace list`          |
+| Update a marketplace's listing | `claude plugin marketplace update <name>` | `/plugin marketplace update <name>` |
+| Remove a marketplace           | `claude plugin marketplace remove <name>` | `/plugin marketplace remove <name>` |
+
+When you remove a marketplace, Claude Code uninstalls every plugin you installed from it and removes their `enabledPlugins` entries from your settings files. The **Marketplaces** tab names those plugins before it asks you to confirm.
 
 ## Next steps
 
-* **Build your own plugins**: see [Plugins](/docs/en/plugins) to create skills, agents, and hooks
-* **Create a marketplace**: see [Create a plugin marketplace](/docs/en/plugin-marketplaces) to distribute plugins to your team or community
-* **Technical reference**: see [Plugins reference](/docs/en/plugins-reference) for complete specifications
+* [Anthropic's marketplaces](/docs/en/plugins/anthropic-marketplaces): how the official, community, and demo marketplaces differ and where to browse each one
+* [Plugin loading reference](/docs/en/plugins/loading): why a plugin loaded, didn't load, or didn't change after an update
+* [Plugin security and trust](/docs/en/plugins/security): what to review before you install a plugin from a marketplace you don't know
+* [Troubleshoot plugins](/docs/en/plugins/troubleshooting): install and marketplace error messages with their fixes
+* [Create a plugin](/docs/en/plugins/create): build your own