Skip to content

Directory-Aware Plugin Suggestions via pluginSuggestionMarketplaces

Three managed-settings levers — pluginSuggestionMarketplaces allowlist, marketplace relevance declaration, defaultEnabled: false — pin only directory-relevant plugins in the /plugin Discover tab.

The pattern earns its place once an internal marketplace exceeds roughly ten plugins. Below that, the Discover tab is short enough to scan and a relevance pin adds an unobservable ranking step without reducing real noise. Above it, every session pays attention tax to a Discover list of plugins it will never use.

The three-lever gate

The pattern composes three Claude Code settings, each enforcing a different leg of the gate:

  1. pluginSuggestionMarketplaces (managed settings only, v2.1.152) — the admin allowlists the marketplace names whose plugins may surface as contextual install suggestions. From the Claude Code settings docs: "Marketplace names whose plugins can appear as contextual install suggestions, in addition to the official marketplace." A name only takes effect when the marketplace is registered on the machine and its registered source is also declared in managed settings — either through extraKnownMarketplaces or strictKnownMarketplaces. Claude Code silently ignores a marketplace registered from a different source under an allowlisted name, which closes the obvious name-collision spoof.
  2. Per-plugin relevance in marketplace.json (v2.1.154) — the marketplace entry declares directory-matching signals. From the Claude Code changelog: "The /plugin Discover tab now pins plugins whose relevance signals match the current directory with a 'suggested for this directory' annotation." The full relevance schema is not yet documented publicly, and the anthropics/claude-plugins-official marketplace catalogue does not yet populate the field. Until the schema lands, treat any plugin-author relevance declaration as untrusted input — no lint surface bounds how broad an author's match can be.
  3. defaultEnabled: false in plugin.json or the marketplace entry (v2.1.154) — the plugin installs disabled and the user opts in. From the plugins reference, Default enablement: "Set defaultEnabled: false in plugin.json to ship a plugin that installs disabled. The user turns it on with claude plugin enable <plugin> or the /plugin interface." The same field can appear in the marketplace entry, where it takes precedence over plugin.json.

Without lever 3, lever 2 is destructive. Suggested plugins are already loaded and paying context cost from session start, so "suggestion" silently becomes "always-on tax."

Why it works

The mechanism is a strict-deny baseline with explicit grants. Nothing appears unless the marketplace is trusted, the plugin claims directory relevance, and the user opts in. Each lever closes a separate failure mode. pluginSuggestionMarketplaces closes the supply-chain leg: no community marketplace nudges an enterprise session. relevance closes the noise leg: a 50-plugin internal marketplace surfaces only the 3 or so a directory needs. defaultEnabled: false closes the cost leg: a suggestion is an install or enable prompt, not silent activation. The Discover-tab change inverts the previous default: instead of "everything available, you discover what's relevant" the surface becomes "nothing pins to the top unless three independent admin- and author-set conditions hold" (Discover plugins docs).

When this backfires

  • Misconfigured relevance declarations spam every directory. A plugin author who writes a signal matching .git or package.json re-spams every Node project. Until a central lint or admin review of relevance exists, an internal marketplace degenerates back to "everything is suggested" the moment one author over-claims.
  • Polyglot monorepos break the assumption. A monorepo opened at the root holds a Python service, a Go service, and a TypeScript app. Any signal keyed on one language fires, or all fire, defeating the relevance pin. The pattern assumes the working directory reflects the task scope; in a monorepo it does not.
  • Small marketplaces (under 10 plugins) gain little. Below this scale the Discover-tab list is already short enough to scan. The relevance pin primes operators to trust an unobservable ranking signal without producing measurable noise reduction.
  • An admin can misconfigure the extraKnownMarketplaces source. The gating rule silently ignores allowlisted names whose registered source does not match the managed-settings declaration (Claude Code settings docs). The admin then enables the allowlist, sees no suggestions, and assumes the feature is broken rather than the configuration. The diagnostic surface is thin.
  • The official marketplace is always implicit. pluginSuggestionMarketplaces extends the suggestion pool; it does not replace it. To suppress official-marketplace suggestions, use strictKnownMarketplaces to lock down which marketplaces are even known on the machine (Plugin marketplaces, managed restrictions).
  • No third party has published precision or recall data on real repos at the time of writing. The mechanism is plausible; its accuracy in your stack is unverified until you ship and measure.

Example

A 30-plugin internal marketplace at acme-corp/plugins, mostly language- and stack-specific (Terraform formatters, Python type-checkers, Vault clients, internal SDK helpers). The pre-pattern Discover tab shows all 30 every session.

Managed settings (managed-settings.json):

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-corp-plugins": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  },
  "pluginSuggestionMarketplaces": ["acme-corp-plugins"]
}

A representative marketplace entry (marketplace.json), with defaultEnabled: false so install does not silently activate:

{
  "name": "terraform-policy-pack",
  "source": { "source": "github", "repo": "acme-corp/tf-policy-pack" },
  "description": "Sentinel-style policy checks for internal Terraform modules",
  "defaultEnabled": false,
  "relevance": { "files": ["*.tf", "terraform.tfstate"] }
}

When a user opens a project containing *.tf files, the Discover tab pins terraform-policy-pack at the top with the 'suggested for this directory' label (Discover plugins docs). The other 29 plugins are still installable, just not pinned. In a directory with no *.tf files, the plugin does not appear at the top, is not auto-enabled, and contributes zero per-turn tokens.

The relevance payload shape above is illustrative — the public schema is not yet documented, and a misconfigured signal still requires manual review until a lint surface ships.

Key Takeaways

  • Three Claude Code settings compose into one pattern: pluginSuggestionMarketplaces (admin allowlist), per-plugin relevance (directory signals), and defaultEnabled: false (opt-in activation). All three are required to deliver the value.
  • pluginSuggestionMarketplaces is managed-settings-only and depends on the marketplace also being declared in extraKnownMarketplaces or strictKnownMarketplaces (Claude Code settings docs).
  • Without defaultEnabled: false, "directory-aware suggestion" silently becomes "always-on context tax" — the plugin is already loaded by the time it is suggested.
  • The relevance schema is not yet publicly documented; treat author-declared relevance as untrusted input until a lint surface bounds how broadly an author can claim relevance.
  • The pattern only earns its place at ~10+ plugins per marketplace; below that, the Discover tab is already short enough to scan and the relevance pin adds an unobservable ranking step with no real noise to reduce.
Emerging — single recent source Last reviewed: 2026-06-03
Feedback