The whole hunk
from line 63, old and new numbered
/
lines
from line 63
6363 ```
6464
6565 <Note>
66 Setting `version` means users only receive updates when you change this field, so bump it on every release. A plugin with a [`command` source](#command-sources) isn't pinned by this field. If you omit `version`, the version comes from the next source in [version management](/docs/en/plugins-reference#version-management).
66 Setting `version` means users only receive updates when you change this field, so bump it on every release. A plugin with a [`command` source](#command-sources) isn't pinned by this field. Neither is a plugin [loaded in place](/docs/en/plugins-reference#plugin-caching-and-file-resolution) from a marketplace added as a local directory. If you omit `version`, the version comes from the next source in [version management](/docs/en/plugins-reference#version-management).
6767 </Note>
6868 </Step>
6969
from line 108
108108To learn more about what plugins can do, including hooks, agents, MCP servers, and LSP servers, see [Plugins](/docs/en/plugins).
109109
110110<Note>
111 **How plugins are installed**: when users install a plugin, Claude Code copies the plugin directory to a cache location, except for a [`command` source in link mode](#copy-mode-and-link-mode), which is used in place. Copied plugins can't reference files outside their directory using paths like `../shared-utils`, because those files won't be copied.
111 **How plugins are installed**: when users install a plugin, Claude Code copies the plugin directory to a cache location, unless the plugin loads in place. A [`command` source in link mode](#copy-mode-and-link-mode) loads in place, and so does a [relative path source](#relative-paths) in a marketplace added from a local directory. Copied plugins can't reference files outside their directory using paths like `../shared-utils`, because those files won't be copied.
112112
113113 If you need to share files across plugins, use symlinks. See [Plugin caching and file resolution](/docs/en/plugins-reference#plugin-caching-and-file-resolution) for details.
114114</Note>
from line 200
200200
201201**Standard metadata fields:**
202202
203| Field | Type | Description |
204| :--------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
205| `displayName` | string | Human-readable name shown in UI surfaces. When neither the entry nor the plugin's `plugin.json` sets one, users see the plugin's `name`. May contain spaces and any casing. Not used for namespacing or lookup. |
206| `description` | string | Brief plugin description |
207| `version` | string | Plugin version. If set (here or in `plugin.json`), the plugin is pinned to this string and users only receive updates when it changes. A plugin with a [`command` source](#command-sources) isn't pinned by either field. If set in neither place, the version comes from the next source in [version management](/docs/en/plugins-reference#version-management). |
208| `author` | object | Plugin author information (`name` required; `email` and `url` optional) |
209| `homepage` | string | Plugin homepage or documentation URL |
210| `repository` | string | Source code repository URL |
211| `license` | string | SPDX license identifier (for example, MIT, Apache-2.0) |
212| `keywords` | array | Tags for plugin discovery and categorization |
213| `metadata` | object | Free-form object for your own fields, such as entitlement or catalog data. Claude Code doesn't read it. Before v2.1.222, `claude plugin validate` reported the key as an unrecognized field. |
214| `category` | string | Plugin category for organization |
215| `tags` | array | Tags for searchability |
216| `strict` | boolean | Controls whether `plugin.json` is the authority for component definitions (default: true). See [Strict mode](#strict-mode) below. |
217| `relevance` | object | Signals that tell Claude Code when to suggest this plugin to users. Takes effect only for marketplaces an administrator allowlists in managed settings. See [Recommend plugins for your org](/docs/en/plugin-relevance). |
218| `defaultEnabled` | boolean | Whether the plugin is enabled after install (default: true). Set to `false` to install the plugin disabled until the user opts in. Takes precedence over the same field in the plugin's `plugin.json`. See [Default enablement](/docs/en/plugins-reference#default-enablement). |
203| Field | Type | Description |
204| :--------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
205| `displayName` | string | Human-readable name shown in UI surfaces. When neither the entry nor the plugin's `plugin.json` sets one, users see the plugin's `name`. May contain spaces and any casing. Not used for namespacing or lookup. |
206| `description` | string | Brief plugin description |
207| `version` | string | Plugin version. If set (here or in `plugin.json`), the plugin is pinned to this string and users only receive updates when it changes. A plugin with a [`command` source](#command-sources) isn't pinned by either field. Neither is a plugin [loaded in place](/docs/en/plugins-reference#plugin-caching-and-file-resolution) from a marketplace added as a local directory. If set in neither place, the version comes from the next source in [version management](/docs/en/plugins-reference#version-management). |
208| `author` | object | Plugin author information (`name` required; `email` and `url` optional) |
209| `homepage` | string | Plugin homepage or documentation URL |
210| `repository` | string | Source code repository URL |
211| `license` | string | SPDX license identifier (for example, MIT, Apache-2.0) |
212| `keywords` | array | Tags for plugin discovery and categorization |
213| `metadata` | object | Free-form object for your own fields, such as entitlement or catalog data. Claude Code doesn't read it. Before v2.1.222, `claude plugin validate` reported the key as an unrecognized field. |
214| `category` | string | Plugin category for organization |
215| `tags` | array | Tags for searchability |
216| `strict` | boolean | Controls whether `plugin.json` is the authority for component definitions (default: true). See [Strict mode](#strict-mode) below. |
217| `relevance` | object | Signals that tell Claude Code when to suggest this plugin to users. Takes effect only for marketplaces an administrator allowlists in managed settings. See [Recommend plugins for your org](/docs/en/plugin-relevance). |
218| `defaultEnabled` | boolean | Whether the plugin is enabled after install (default: true). Set to `false` to install the plugin disabled until the user opts in. Takes precedence over the same field in the plugin's `plugin.json`. See [Default enablement](/docs/en/plugins-reference#default-enablement). |
219219
220220Both the entry and the plugin's own `plugin.json` can set the display fields `displayName`, `description`, `author`, `homepage`, `repository`, `license`, and `keywords`. In plugin listings and details, before and after install:
221221
from line 248
248248
249249Plugin sources tell Claude Code where to get each individual plugin listed in your marketplace. These are set in the `source` field of each plugin entry in `marketplace.json`.
250250
251Claude Code copies each installed plugin into the local versioned plugin cache at `~/.claude/plugins/cache`, except for a [`command` source in link mode](#copy-mode-and-link-mode), which Claude Code uses in place. Claude Code also [installs the plugin's eligible Node.js package dependencies](/docs/en/plugins-reference#node-js-package-dependencies) into the cached copy.
251Claude Code copies each installed plugin into the local versioned plugin cache at `~/.claude/plugins/cache`, unless the plugin loads in place. A [`command` source in link mode](#copy-mode-and-link-mode) loads in place, and so does a [relative path source](#relative-paths) in a marketplace added from a local directory. Claude Code also [installs the plugin's eligible Node.js package dependencies](/docs/en/plugins-reference#node-js-package-dependencies) into the cached copy. See [Plugin caching and file resolution](/docs/en/plugins-reference#plugin-caching-and-file-resolution) for how a plugin loaded in place from a local-directory marketplace picks up your edits.
252252
253253| Source | Type | Fields | Notes |
254254| ------------- | ------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
from line 1060
10601060Plugin 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. For git-based sources, if you omit `version`, Claude Code uses the source's resolved commit SHA, so users get an update whenever that commit changes; this is the simplest setup for internal or actively developed plugins. See [Version management](/docs/en/plugins-reference#version-management) for the full resolution order, including `archive` sources.
10611061
10621062<Warning>
1063 Setting `version` pins the plugin for every source type except [`command`](#command-sources), whose version always includes a hash of what the command produced. If you declare `"version": "1.0.0"` in `plugin.json` and push new commits without changing that string, existing users of those sources keep the cached copy, because Claude Code sees the same version. Bump the field on every release, or omit it to fall back to the resolved version.
1063 Setting `version` pins the plugin for every source type except [`command`](#command-sources), whose version always includes a hash of what the command produced. A plugin [loaded in place](/docs/en/plugins-reference#plugin-caching-and-file-resolution) from a marketplace added as a local directory isn't pinned either. If you declare `"version": "1.0.0"` in `plugin.json` and push new commits without changing that string, existing users of those sources keep the cached copy, because Claude Code sees the same version. Bump the field on every release, or omit it to fall back to the resolved version.
10641064
10651065 Avoid setting `version` in both `plugin.json` and the marketplace entry. Claude Code always uses the `plugin.json` value without warning, so a stale manifest version can mask a version you set in `marketplace.json`.
10661066</Warning>
from line 1505
15051505
15061506**Symptoms**: Plugin installs but references to files fail, especially files outside the plugin directory
15071507
1508**Cause**: Plugins are copied to a cache directory rather than used in place, except for a [`command` source in link mode](#copy-mode-and-link-mode). Paths that reference files outside a copied plugin's directory (such as `../shared-utils`) won't work because those files aren't copied.
1508**Cause**: Claude Code copies installed plugins to a cache directory, unless the plugin loads in place. A [`command` source in link mode](#copy-mode-and-link-mode) loads in place, and so does a [relative path source](#relative-paths) in a marketplace added from a local directory. Paths that reference files outside a copied plugin's directory (such as `../shared-utils`) won't work because those files aren't copied.
15091509
15101510**Solutions**: See [Plugin caching and file resolution](/docs/en/plugins-reference#plugin-caching-and-file-resolution) for workarounds including symlinks and directory restructuring.
15111511