The whole hunk
from line 32, old and new numbered
/
lines
from line 32
3232
3333Skills and commands are automatically discovered when the plugin is installed.
3434
35If a plugin has no `skills/` directory and no `skills` manifest field, a `SKILL.md` at the plugin root is loaded as a single skill. Set the frontmatter `name` field to control the skill's invocation name. Without it, Claude Code falls back to the install directory name, which for marketplace-installed plugins is a version string that changes on every update. For plugins that ship more than one skill, use the `skills/` directory layout shown above.
35If a plugin has no `skills/` directory and no `skills` manifest field, a `SKILL.md` at the plugin root is loaded as a single skill. Set the frontmatter `name` field to control the skill's invocation name. Without it, Claude Code falls back to the install directory name. For a plugin [copied into the cache](#plugin-caching-and-file-resolution), that name is a version string that changes on every update. For plugins that ship more than one skill, use the `skills/` directory layout shown above.
3636
3737In plugin skills and commands, Boolean frontmatter fields such as `disable-model-invocation` accept `yes`, `no`, `on`, `off`, `1`, and `0` in any letter case, in addition to `true` and `false`. Before v2.1.218, Claude Code recognized only `true` and `false`.
3838
from line 509
509509
510510### Metadata fields
511511
512| Field | Type | Description | Example |
513| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
514| `$schema` | string | JSON Schema URL for editor autocomplete and validation. Claude Code ignores this field at load time. | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |
515| `displayName` | string | Human-readable name shown in the `/plugin` picker and other UI surfaces. For a marketplace-installed plugin, a `displayName` on the [marketplace entry](/docs/en/plugin-marketplaces#optional-plugin-fields) takes precedence over this value. When no display name is set in either place, users see `name`. Unlike `name`, may contain spaces and any casing. Not used for namespacing or lookup. | `"Deployment Tools"` |
516| `version` | string | Optional. Semantic version. Setting this pins the plugin to that version string, so users only receive updates when you bump it, except for a [`command` source](/docs/en/plugin-marketplaces#command-sources); see [Version management](#version-management). If also set in the marketplace entry, `plugin.json` wins. If omitted, the version comes from the next source in [Version management](#version-management). | `"2.1.0"` |
517| `description` | string | Brief explanation of plugin purpose | `"Deployment automation tools"` |
518| `author` | object | Author information | `{"name": "Dev Team", "email": "[email protected]"}` |
519| `homepage` | string | Documentation URL | `"https://docs.example.com"` |
520| `repository` | string | Source code URL | `"https://github.com/user/plugin"` |
521| `license` | string | License identifier | `"MIT"`, `"Apache-2.0"` |
522| `keywords` | array | Discovery tags | `["deployment", "ci-cd"]` |
523| `metadata` | object | Free-form object for your own data, such as entitlement or catalog fields. Claude Code doesn't read it, so the values never affect plugin behavior. Claude Code ignores a non-object value, and `claude plugin validate` reports it as a warning. Before v2.1.222, Claude Code treated the key as an [unrecognized field](#unrecognized-fields). | `{"catalogId": "cat-123"}` |
524| `defaultEnabled` | boolean | Whether the plugin starts in an enabled state when the user has not set one. Defaults to `true`. See [Default enablement](#default-enablement). | `false` |
512| Field | Type | Description | Example |
513| :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
514| `$schema` | string | JSON Schema URL for editor autocomplete and validation. Claude Code ignores this field at load time. | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |
515| `displayName` | string | Human-readable name shown in the `/plugin` picker and other UI surfaces. For a marketplace-installed plugin, a `displayName` on the [marketplace entry](/docs/en/plugin-marketplaces#optional-plugin-fields) takes precedence over this value. When no display name is set in either place, users see `name`. Unlike `name`, may contain spaces and any casing. Not used for namespacing or lookup. | `"Deployment Tools"` |
516| `version` | string | Optional. Semantic version. Setting this pins the plugin to that version string, so users only receive updates when you bump it, except for a [`command` source](/docs/en/plugin-marketplaces#command-sources) or a plugin [loaded in place](#plugin-caching-and-file-resolution); see [Version management](#version-management). If also set in the marketplace entry, `plugin.json` wins. If omitted, the version comes from the next source in [Version management](#version-management). | `"2.1.0"` |
517| `description` | string | Brief explanation of plugin purpose | `"Deployment automation tools"` |
518| `author` | object | Author information | `{"name": "Dev Team", "email": "[email protected]"}` |
519| `homepage` | string | Documentation URL | `"https://docs.example.com"` |
520| `repository` | string | Source code URL | `"https://github.com/user/plugin"` |
521| `license` | string | License identifier | `"MIT"`, `"Apache-2.0"` |
522| `keywords` | array | Discovery tags | `["deployment", "ci-cd"]` |
523| `metadata` | object | Free-form object for your own data, such as entitlement or catalog fields. Claude Code doesn't read it, so the values never affect plugin behavior. Claude Code ignores a non-object value, and `claude plugin validate` reports it as a warning. Before v2.1.222, Claude Code treated the key as an [unrecognized field](#unrecognized-fields). | `{"catalogId": "cat-123"}` |
524| `defaultEnabled` | boolean | Whether the plugin starts in an enabled state when the user has not set one. Defaults to `true`. See [Default enablement](#default-enablement). | `false` |
525525
526526### Default enablement
527527
from line 698
698698| `${CLAUDE_PLUGIN_DATA}` | [Persistent directory](#persistent-data-directory) that survives plugin updates, created on first reference | Installed dependencies such as `node_modules` or Python virtual environments, generated code, and caches |
699699| `${CLAUDE_PROJECT_DIR}` | The project root | Project-local scripts and config files |
700700
701All three are exported as environment variables to hook processes and to MCP and LSP server subprocesses. Which fields substitute them inline depends on the plugin component:
701All three are exported as environment variables to hook processes and to MCP and LSP server subprocesses. They aren't present in the environment of commands Claude runs through the Bash tool, in the main session or in a subagent. In plugin content, write the placeholder instead, and Claude Code substitutes the path inline when it loads the content. Which fields substitute them inline depends on the plugin component:
702702
703703| Plugin component | Fields where placeholders resolve |
704704| :------------------------------ | :------------------------------------------ |
from line 727
727727}
728728```
729729
730`${CLAUDE_PLUGIN_ROOT}` changes when the plugin updates. The previous version's directory remains on disk for a grace period after an update, but treat it as ephemeral and don't write state there. See [plugin caching](#plugin-caching-and-file-resolution) for cleanup semantics.
730For a copied plugin, `${CLAUDE_PLUGIN_ROOT}` changes when the plugin updates. The previous version's directory remains on disk for a grace period after an update, but treat it as ephemeral and don't write state there. For a plugin loaded in place from a local-directory marketplace, the variable points at the stable source directory. See [plugin caching](#plugin-caching-and-file-resolution) for which plugins are copied and for cleanup semantics.
731731
732When a plugin updates mid-session, hook commands, monitors, MCP servers, and LSP servers keep using the previous version's path. Run `/reload-plugins` to switch hooks, MCP servers, and LSP servers to the new path; monitors require a session restart. In a session without an interactive terminal, the reload leaves plugin MCP servers on the old path until the next session.
732When a copied plugin updates mid-session, hook commands, monitors, MCP servers, and LSP servers keep using the previous version's path. Run `/reload-plugins` to switch hooks, MCP servers, and LSP servers to the new path; monitors require a session restart. In a session without an interactive terminal, the reload leaves plugin MCP servers on the old path until the next session.
733733
734734For a plugin with a `command` source, Claude Code [can reload the plugin itself](/docs/en/plugin-marketplaces#when-claude-code-re-runs-the-command).
735735
from line 791
791791* Through `claude --plugin-dir` or `claude --plugin-url`, for the duration of a session.
792792* Through a marketplace, installed for future sessions.
793793
794For security and verification purposes, Claude Code copies *marketplace* plugins to the user's local **plugin cache** (`~/.claude/plugins/cache`) rather than using them in place, except for [`command` sources in link mode](/docs/en/plugin-marketplaces#copy-mode-and-link-mode), which Claude Code uses in place through links in the cache entry.
794For security and verification purposes, Claude Code copies *marketplace* plugins to the user's local **plugin cache** (`~/.claude/plugins/cache`), unless the plugin loads in place. A [`command` source in link mode](/docs/en/plugin-marketplaces#copy-mode-and-link-mode) loads in place through links in the cache entry. A [relative path source](/docs/en/plugin-marketplaces#relative-paths) in a marketplace added from a local directory loads in place from the marketplace folder.
795795
796For a plugin loaded in place from a local-directory marketplace, your edits to the source directory take effect at the next session start or `/reload-plugins`. You don't need a version bump. The plugin's hook processes and MCP and LSP servers receive a `CLAUDE_PLUGIN_ROOT` that points at the source directory. Claude Code doesn't install the plugin's [Node.js package dependencies](#node-js-package-dependencies) into the source directory. Install them there yourself, or from a hook into the [persistent data directory](#persistent-data-directory).
797
796798For copied plugins, each installed version is a separate directory in the cache, grouped by marketplace and plugin and named for the resolved version, with its own copy of the plugin's files and [Node.js package dependencies](#node-js-package-dependencies). A dependency resolved from a [release tag](/docs/en/plugin-dependencies#tag-plugin-releases-for-version-resolution) gets a directory name with a commit-SHA suffix.
797799
798800When you update or uninstall a plugin, Claude Code marks the previous version directory as orphaned and removes it in a background sweep roughly 14 days later. The grace period lets concurrent Claude Code sessions that already loaded the old version keep running without errors. Claude Code runs the sweep only while at least one plugin is installed; after you uninstall your last plugin, orphaned directories stay on disk until you install a plugin again.
from line 1435
14331435
14341436### Version management
14351437
1436Claude 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.
1438Claude 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. A plugin [loaded in place](#plugin-caching-and-file-resolution) from a local-directory marketplace loads its current source files at every session start, whatever its version string says.
14371439
14381440For every source type except `command`, Claude Code resolves the version from the first of these that is set:
14391441
from line 1449
14471449
14481450For those source types, this gives you three ways to version a plugin:
14491451
1450| Approach | How | Update behavior | Best for |
1451| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- |
1452| **Explicit version** | Set `"version": "2.1.0"` in `plugin.json` | Users get updates only when you bump this field. Pushing new commits without bumping it has no effect, and `/plugin update` reports "already at the latest version". | Published plugins with stable release cycles |
1453| **Commit-SHA version** | Omit `version` from both `plugin.json` and the marketplace entry | Users get updates whenever the source's resolved commit changes | Internal or team plugins under active development |
1454| **Digest version** | Use an [`archive` source](/docs/en/plugin-marketplaces#zip-archives) and omit `version` from both `plugin.json` and the marketplace entry | With a `sha256` pin, users get updates when you change the pin. Without one, users get updates whenever the hosted zip file's bytes change | Plugins published as zip files to a static server or artifact repository |
1452| Approach | How | Update behavior | Best for |
1453| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- |
1454| **Explicit version** | Set `"version": "2.1.0"` in `plugin.json` | Users get updates only when you bump this field. Pushing new commits without bumping it has no effect, and `/plugin update` reports "already at the latest version". For a plugin [loaded in place](#plugin-caching-and-file-resolution), the new content loads anyway. | Published plugins with stable release cycles |
1455| **Commit-SHA version** | Omit `version` from both `plugin.json` and the marketplace entry | Users get updates whenever the source's resolved commit changes | Internal or team plugins under active development |
1456| **Digest version** | Use an [`archive` source](/docs/en/plugin-marketplaces#zip-archives) and omit `version` from both `plugin.json` and the marketplace entry | With a `sha256` pin, users get updates when you change the pin. Without one, users get updates whenever the hosted zip file's bytes change | Plugins published as zip files to a static server or artifact repository |
14551457
14561458If you use explicit versions, follow [semantic versioning](https://semver.org) (`MAJOR.MINOR.PATCH`): bump MAJOR for breaking changes, MINOR for new features, PATCH for bug fixes. Document changes in a `CHANGELOG.md`.
14571459