What Claude Code plugin recommendations are
Claude Code plugin recommendations let you suggest a plugin from your organization's marketplace when someone's session matches the work that plugin is for. You add a relevance block to the plugin's entry in marketplace.json, list the signals that mean the plugin is useful, and an administrator allowlists the marketplace in managed settings. When a signal matches and the plugin is not installed, Claude Code shows an install suggestion. The user always confirms the install.
This fixes the most common failure of an internal marketplace: people do not know a plugin exists. You build a Terraform plugin with your house conventions, announce it once in a channel, and six weeks later half the team is still writing Terraform without it. Relevance moves the announcement to the moment it matters, when someone is actually in a .tf file.
How a relevance match turns into a suggestion
Each signal is a pattern Claude Code tests against the current session. Matching runs locally on the user's machine and adds no network traffic. Claude Code does not report which signals matched, or their values, to Anthropic or to the marketplace operator. That matters when you explain this to a security team: you are not collecting anything by turning it on.
Where a matched plugin shows up
| Place | What the user sees | When |
|---|---|---|
| Spinner tip | Working with Terraform? Install the terraform-helpers plugin, followed by the /plugin install command | While Claude is responding, after any signal matches |
| Session-start notice | plugin suggestion: terraform-helpers@your-marketplace | Before the first message, only when a cwd signal matches |
| /plugin Discover tab | The plugin pinned to the top, annotated with the signal, such as suggested for this directory | The first time the user opens the tab while the signals match |
If no signal matches, the plugin keeps its normal place in the Discover list and never appears as a spinner tip. Users who set spinnerTipsEnabled to false, or replace the built-in tips with spinnerTipsOverride and excludeDefault, also lose the spinner tip and the session-start notice. The Discover pin is not affected by either setting.
Add a relevance block to a plugin entry
Open your marketplace.json and add a relevance object to the plugin's entry, next to its name, source and description. The object has two fields: topic and signals.
- topic is optional. It fills the blank in Working with ___? on the spinner tip, up to 64 characters. Without it, Claude Code uses the plugin name with each hyphen segment capitalized. Use a product name like Terraform, or a domain like design when the plugin name reads badly as a topic.
- signals is the part that matters. Claude Code only suggests the plugin if at least one signal is set.
- For the Terraform example, the entry gets a relevance object with topic set to Terraform, and signals with cli set to terraform and filesRead set to **/*.tf.
Pick the right signal for each plugin
There are five signals. Each has its own matching rules and limits, and picking the wrong one is the main reason a suggestion never fires.
The five relevance signals
| Signal | Matches | Limit |
|---|---|---|
| cwd | Glob patterns against the working directory, as an absolute path and, inside a git repo, relative to the repo root | 10 patterns, 256 characters each |
| cli | The command name of shell commands Claude has run this session, exact match | 10 entries, 64 characters each |
| hosts | Hostnames in http or https URLs in Bash commands this session. Bare lowercase hostname only, no scheme, port or path | 20 entries, 128 characters each |
| filesRead | Glob patterns against paths of files Claude has read, case-insensitive | 10 patterns, 256 characters each |
| manifestDeps | A pair of regular expressions: one for the manifest file path, one for its contents | 10 entries, 256 characters per value. Manifests over 512 KB are skipped |
Three details catch people. First, cwd is the only signal that can match before the user types anything, so it is the one that produces the session-start notice. A cwd pattern matches the directory and everything under it, so infra, infra/ and infra/** behave the same. Second, cli records only the first command in a compound command: cd infra && terraform plan records cd, not terraform. Pair cli with filesRead so you still catch that session. Third, filesRead and manifestDeps also match files Claude has written or edited, and the project's auto-loaded CLAUDE.md files.
manifestDeps is the right signal for an SDK plugin. Point the file pattern at package.json, anchored at the end of the path since the path is usually absolute, and the content pattern at your package name followed by a colon. In JSON, every backslash in those regular expressions is written twice, which is the usual source of a pattern that never matches.
Validate the marketplace before you publish
Run claude plugin validate against your marketplace directory in a terminal, for example claude plugin validate ./my-marketplace. It warns about unknown keys under relevance and relevance.signals, flags a relevance value that is not an object, and rejects a hosts entry that includes a scheme, port or path. Each finding prints with the path of the field, and the output ends with Validation passed, Validation passed with warnings or Validation failed.
My recommendation: make that command a required check on every change to marketplace.json. One plugin entry broken by an overlong pattern stops installs of that plugin for everyone, and a CI check catches it before it merges.
Allowlist the marketplace in managed settings
Writing relevance blocks is half the job. In the terminal, users see no suggestions from a marketplace until an administrator allowlists it in managed settings, even if every plugin in it declares relevance. Two keys do it.
- Add the marketplace name to pluginSuggestionMarketplaces.
- For any marketplace other than the official one, also declare its source, either as that name's entry in extraKnownMarketplaces or as an entry in strictKnownMarketplaces. For a GitHub-hosted marketplace, the source is github plus the repo name.
The source check is a security feature, not paperwork. On a machine where the marketplace is not registered, or is registered under the allowlisted name from a different source, no suggestions appear. That stops someone from registering an unrelated marketplace under your allowlisted name to get their plugins suggested across your company. The official marketplace, claude-plugins-official, can only register from Anthropic's source, so it needs the name alone. The managed settings guide covers how to deploy the file.
How often users see a suggestion
Claude Code rations suggestions so a well-tuned marketplace does not turn into nagging. This is worth knowing before someone tells you the plugin was suggested once and then disappeared.
- A given plugin is suggested at most once every three sessions, counting the spinner tip and the session-start notice together.
- The session-start notice stops once the tip and the notice have shown that plugin two times in total.
- Neither repeats once the plugin is installed.
- The Discover tab pins the plugin only the first time the user opens it while signals match. After that it is recorded in ~/.claude.json and the plugin appears in normal order on that machine.
So you get a small number of chances per person. Spend them on the right moment: tight signals that only match when the plugin will help, not broad ones that fire in every repo.
The CCC Relevance Map
Here is how I would roll this out for a team. I call it the CCC Relevance Map: one row per plugin, one strongest signal, one backup signal, and a check that the suggestion is earning its place.
- List every plugin in your marketplace and write the one situation where it obviously helps. If you cannot write that sentence, the plugin should not get a relevance block.
- Pick the strongest signal for that situation: cwd for a team or repo, filesRead for a file type, cli or hosts for a tool, manifestDeps for a library.
- Add a backup signal for the gaps, such as filesRead next to cli for compound commands.
- Keep patterns narrow. A cwd of the whole monorepo suggests the plugin to everyone and burns the few suggestions each person gets.
- Run claude plugin validate in CI on every marketplace change.
- Allowlist the marketplace with pluginSuggestionMarketplaces and declare its source.
- After a month, count plugin_installed events per plugin against the month before suggestions went live, and drop or narrow relevance on plugins nobody installs.
One limit to know: the separate claude-code-hint mechanism, where a CLI or SDK prompts the install itself, only works for plugins in Anthropic's official marketplaces. For internal plugins, relevance is the route. For a refresher on what a plugin can contain, see Claude Code plugins explained.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How do I get Claude Code to recommend a plugin?
Add a relevance block to the plugin's entry in your marketplace.json with at least one signal, such as cwd, cli, hosts, filesRead or manifestDeps. Then an administrator adds the marketplace to pluginSuggestionMarketplaces in managed settings and declares its source.
Does Claude Code install recommended plugins automatically?
No. Claude Code only suggests the plugin with a spinner tip, a session-start notice or a pin in the /plugin Discover tab. The user always confirms the install.
Does plugin relevance send my data anywhere?
No. Signal matching happens locally on the user's machine and adds no network traffic. Claude Code does not report which signals matched, or their values, to Anthropic or to the marketplace operator.
Why is my plugin suggestion not showing up?
The usual causes are a marketplace missing from pluginSuggestionMarketplaces or with no declared source, a cli signal that misses compound commands, spinner tips turned off, the plugin already installed, or the once-every-three-sessions limit. Run claude plugin validate to rule out a broken entry.
Which signal shows a suggestion at session start?
Only cwd. It matches the working directory, so it can fire before the user sends a first message. The other signals need Claude to run a command or read a file first.
How do I stop plugin suggestions?
Set spinnerTipsEnabled to false, or use spinnerTipsOverride with excludeDefault, to remove the spinner tip and the session-start notice. The pin in the /plugin Discover tab is not affected by either setting.
Last reviewed by David Iya on November 19, 2026


