Safeguard
Supply Chain Security•

Claude Code Plugins Explained: Anatomy, Marketplaces, Team Rollout and a Worked Example

How a Claude Code plugin is built and shipped: the plugin.json manifest, marketplace.json, source types, install scopes, versions, a worked team marketplace and when to package a plugin.

Safeguard Security Team
32 min read

A Claude Code plugin is a directory of skills, subagents, hooks, MCP servers and other components that Claude Code installs and loads as one unit, usually from a plugin marketplace that lists where to fetch it. A marketplace is a catalog file, .claude-plugin/marketplace.json, not a hosted store. This guide explains how both are built, installed, versioned and distributed to a team.

It is for platform engineers and developers asked to build, roll out or approve plugins. It covers the anatomy, the manifest, marketplaces and source types, install flow and scopes, versions and updates, a worked example you can copy, when to package a plugin at all, and how Codex, ChatGPT, Cursor and VS Code compare. Security gets one compact section, because Anthropic's documentation is blunt that an installed plugin "can execute arbitrary code on your machine with your user privileges." Claude Code facts come from Anthropic's docs at code.claude.com as they read on 15 November 2026, with key names quoted exactly.

This is the third post in a series. For the protocol and the OWASP MCP Top 10, read What is an MCP server and how to secure it. For skills in depth, read How to write and secure agent skills. Here both appear as plugin components.

Key takeaways

  • A plugin is a packaging format, not a new capability. It bundles components so they install, update and get disabled together.
  • Only name is required in plugin.json, and the manifest itself is optional.
  • A marketplace is a .claude-plugin/marketplace.json catalog in a git repository, a directory or at a URL.
  • Installs have three scopes: user, project and local. A project install is committed in .claude/settings.json so the whole repository gets it.
  • A plugin with no version field tracks its source commit; a pinned version keeps users put until you change the string. Auto-update is on by default for Anthropic's official marketplaces and off for third-party ones.
  • Hooks, monitors, MCP servers and LSP servers run outside Claude Code's sandbox with your user permissions, so review them before you enable a plugin and pin what you reviewed.

What a Claude Code plugin is

Anthropic's plugins overview defines a plugin as "a directory of skills, agents, hooks, MCP servers, or other components that Claude Code installs and loads as one unit." Each component also works on its own; the docs' rule is "Use a plugin when you want several skills, subagents, hooks, or MCP servers packaged as one unit."

So a plugin grants no new powers. What changes is distribution: one command installs a bundle someone else wrote, the bundle can update itself, and its components are active in every session where it is enabled, not only when you use it. The overview lists the consequences: skill and agent descriptions sit in Claude's context on every turn, the plugin's MCP servers run alongside each session and its hooks fire at their events, and "What the plugin runs, it runs as you."

The components a plugin can carry

The manifest reference gives each component a default location; a component there loads without any manifest entry.

ComponentDefault locationWhat it does
Manifest.claude-plugin/plugin.jsonMetadata and configuration; optional, and only name is required in it
Skillsskills/<name>/SKILL.mdInstructions Claude loads when relevant, runnable as /<plugin>:<name>
Commandscommands/*.mdOlder single-file format that skills supersede
Agentsagents/*.mdSubagents named <plugin>:<name>
Hookshooks/hooks.jsonHandlers at lifecycle events such as PreToolUse or SessionStart
MCP servers.mcp.jsonTool servers connected while the plugin is enabled
LSP servers.lsp.jsonLanguage servers for code intelligence
Monitorsmonitors/monitors.jsonBackground shell commands Claude Code starts itself; the manifest key sits under experimental
Executablesbin/Added to the Bash tool's PATH
Output styles, themes, workflowsoutput-styles/, themes/, workflows/Reply formatting, interface themes and multi-agent workflow scripts; themes are declared under experimental

A plugin can also hold a hooks module of JavaScript functions; a plugin with one is a mod, which the security page says "runs JavaScript inside Claude Code with your permissions." A CLAUDE.md at the plugin root is not loaded.

Skills. A plugin skill is the standard SKILL.md format, namespaced so skills/review/SKILL.md in my-plugin runs as /my-plugin:review. Two features matter for review: the allowed-tools frontmatter grants tools, and the skills page documents a !`<command>` syntax that "runs shell commands before the skill content is sent to Claude." A skill is not always inert text.

MCP servers. Declared in .mcp.json "in the same shape as a project .mcp.json," a plugin server appears in /mcp as plugin:<plugin>:<server> and its tools are named mcp__plugin_<plugin>_<server>__<tool>. That full name is what permission rules and hook matchers need; a matcher on the server name alone never fires. A stdio server is a process on your machine; a remote https:// server is also how a plugin reaches claude.ai and Cowork users. A plugin server is separate from a repository .mcp.json, whose approval rules are covered in why a cloned repo cannot approve its servers.

Hooks. A hook runs a shell command, HTTP request, MCP tool call, model prompt or subagent at a lifecycle point; the hooks reference lists the types as "command", "http", "mcp_tool", "prompt" and "agent". Timing is the surprise: "A plugin's hooks don't wait for one of the plugin's skills or commands to be used." They fire from the moment a session loads the plugin, and "Command hooks execute shell commands with your full user permissions." For how an exit code 2 block behaves in practice, see Claude Code hooks that block actions.

Paths and user configuration

Installed plugins live in a versioned cache, so components use variables: ${CLAUDE_PLUGIN_ROOT} (the installed version's path), ${CLAUDE_PLUGIN_DATA} (a data directory kept across updates) and ${CLAUDE_PROJECT_DIR} (the project root). Hook processes receive CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA in their environment, and shell-form commands should wrap the root path in double quotes.

For values like API tokens, the manifest's userConfig declares fields with type, title and description. A field marked "sensitive": true "masks input and stores the value in secure storage instead of settings.json." Values reach server config and exec-form hook args as ${user_config.KEY}, and hook processes as CLAUDE_PLUGIN_OPTION_<KEY>. Shell-form hooks, monitors and MCP headersHelper reject ${user_config.*} because a shell would re-parse the value, a deliberate injection guard and a reason to prefer exec form.

Where plugin files live

Where a plugin runs from depends on how it arrived, per the loading reference. Claude Code loads --plugin-dir plugins and skills-directory plugins in place and never copies them. A relative-path plugin in a marketplace you added from a local path also loads in place, so your edits take effect at the next session start or /reload-plugins. Every other marketplace plugin is copied into ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ at install, and ${CLAUDE_PLUGIN_ROOT} points at that copy.

Two consequences matter when you write a plugin. Files outside the plugin directory are not copied, so a script that reads ../shared finds nothing in the cache. And Claude Code rejects a component path that resolves outside the plugin root, including a symlink that leads outside it, with a path escapes plugin directory error; the plugin then loads without that component. Because the root path changes with every version, keep durable files in ${CLAUDE_PLUGIN_DATA}, which resolves to ~/.claude/plugins/data/<id>/ and is kept across updates. On uninstall from the last scope, Claude Code deletes that directory by default.

The plugin manifest, field by field

Inside plugin.json, only name is required. The fields that matter most for review:

FieldWhat it doesReview note
nameKebab-case identifier; components are namespaced under itReserved-name checks, see below
version"Setting it keeps users on that version until you change it"Decides whether commits reach users
description, author, homepage, repository, licenseMetadata; homepage must parse as a URLWho to hold responsible
defaultEnabledWhether it starts enabled; default trueInstalling usually enables
dependenciesOther plugins that must be enabledOne install can pull in more
userConfigValues prompted for on enableLook for sensitive on secrets
hooks, mcpServers, lspServersExtra hook, MCP and LSP definitions, loaded with the default filesComponents can hide in the manifest
skills, commands, agentsExtra component locationsNot everything lives in default folders

claude plugin validate errors on names that start with claude-, anthropic-, anthropics- or cc-plugin-, or that put official beside claude or anthropic. The docs add: "Claude Code still installs and loads a plugin whose name they refuse." Name checks guide honest authors; they do not stop hostile ones.

How plugin marketplaces work

A marketplace "is a repository or directory with a .claude-plugin/marketplace.json file that lists plugins and where to fetch each one. It's a catalog, not a hosted store." You add it once and install by plugin-name@marketplace-name.

The marketplace reference requires name, owner and plugins; optional top-level keys include description, version, metadata.pluginRoot, forceRemoveDeletedPlugins (uninstalls removed plugins on users' machines) and renames. Each entry needs name and source, and may set description, version, category, tags, strict, dependencies, defaultEnabled and displayName. With strict at its default true, an entry's skills, commands and agents are appended to the plugin's own manifest, and its hook matchers replace the manifest's for the same event. The catalog owner, not only the author, can change what a plugin runs.

Source typeFieldsWhat to know
Relative path./path stringA directory inside the marketplace repository
githubrepo, ref, shaowner/repo on GitHub
urlurl, ref, shaAny git repository
git-subdirurl, path, ref, shaOne subdirectory via sparse checkout
npmpackage, version, registryFetched "without running install scripts"
archiveurl, sha256HTTPS zip; a digest mismatch is refused
commandcommand, timeout, modeA local command prints the plugin path; re-runs once per session

For git sources, sha is "a full 40-character lowercase commit SHA. When you set both ref and sha, Claude Code checks out sha." That is the pin for anything you did not write.

Adding a marketplace

The install guide lists what /plugin marketplace add and claude plugin marketplace add accept: a GitHub owner/repo (add #ref to pin a branch or tag), a full git clone URL on any host (also with #ref), a local directory or file (start relative paths with ./ or ../, because a bare name/name reads as a GitHub repository), or the https:// URL of a hosted marketplace.json. A private marketplace is added the same way and cloned with your existing git credentials. /plugin market works as a shorter form of /plugin marketplace.

Choosing a plugin source

The source you pick decides what Claude Code can resolve and how it versions the plugin.

  • Relative path (./plugins/formatter) resolves from the marketplace root, not from .claude-plugin/, and must not contain ... It works only when Claude Code has the marketplace's files, which is true for github, git, file and directory marketplaces. A marketplace added from a bare url fetches only marketplace.json, so give each plugin an object source there. Setting metadata.pluginRoot to ./plugins lets you write the bare name formatter instead.
  • github, url and git-subdir point at separate repositories. git-subdir uses a sparse checkout, so a plugin in a large monorepo installs without downloading the rest.
  • npm takes package, an optional version (a version, range or dist-tag; omitted means latest) and an optional registry. Claude Code fetches it with your npm client and never runs its install scripts. Git addresses, folder paths and npm: aliases are refused as package values.
  • archive is an HTTPS zip, pinned by sha256 so a mismatched download is refused.
  • command runs a command on the user's machine that prints the plugin directory. Claude Code shows users the whole command string before it runs, and runs it again once per session. It suits plugins that another tool generates, and few teams need it.

Who runs which marketplace

The plugin security page sorts catalogs into tiers by name. Official names include claude-plugins-official and claude-code-plugins; community names are claude-community, claude-plugins-community and healthcare; everything else, including your own company's catalog, is third-party. Claude Code "accepts the official and community names only for marketplaces sourced from github.com/anthropics/ repositories," and where claude-community pins a commit SHA it "refuses to install a different commit." Claude Code adds claude-plugins-official on the first interactive session unless managed policy blocks it.

Commands and scopes

TaskIn a sessionIn your shell
Add a marketplace/plugin marketplace add your-org/plugins#v1.2.0claude plugin marketplace add your-org/plugins#v1.2.0
Install/plugin install name@marketplaceclaude plugin install name@marketplace --scope project
Disable, enable/plugin disable, /plugin enableclaude plugin disable name@marketplace
Update one pluginUpdate now in /pluginclaude plugin update name@marketplace
Inspectdetails pane in /pluginclaude plugin details name
Uninstall/plugin uninstallclaude plugin uninstall name@marketplace --scope project
Remove a marketplace/plugin marketplace remove nameclaude plugin marketplace remove name

In a session, /plugin install opens the details pane so you review and pick a scope first. The install guide defines three scopes: user (~/.claude/settings.json, every project), project (.claude/settings.json, committed for the whole repository) and local (.claude/settings.local.json). Local overrides project, project overrides user, and managed settings override all three. Removing a marketplace uninstalls every plugin from it.

Versions and auto-update

The loading reference computes a version for every plugin and uses it to detect updates: first version in plugin.json, then version in the marketplace entry, then the source. For github, url and git-subdir the fallback is the commit SHA shortened to 12 characters; for archive it is the digest; for command it is always a hash of the output. So a plugin without version changes on every commit, while a pinned "version": "1.0.0" keeps users on the cache "until its author changes the string, however many commits they push."

Auto-update is on by default for the official names except knowledge-work-plugins and first-party-plugins, and for marketplaces added from claude.ai; it is off for "every other marketplace, including the community marketplace, third-party marketplaces, and local development marketplaces." When on, Claude Code waits a random delay of up to ten minutes after your first message, refreshes, and updates the plugins on disk; the next launch loads the new code. The security page's warning: "the files you reviewed can change on disk."

Worked example: a small plugin and a team marketplace

acme-guardrails, for a fictional platform team, ships one skill, one defensive hook that blocks Claude's file tools from secret files, and one remote MCP server whose token lives in the credential store. It sits in a marketplace called acme-plugins beside a second plugin pinned to a commit.

agent-plugins/                      # the marketplace repository
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── acme-guardrails/
        ├── .claude-plugin/
        │   └── plugin.json
        ├── skills/
        │   └── dependency-review/
        │       └── SKILL.md
        ├── hooks/
        │   └── hooks.json
        ├── scripts/
        │   └── protect-secrets.sh
        └── .mcp.json

plugin.json

{
  "name": "acme-guardrails",
  "version": "1.2.0",
  "description": "Dependency review skill, secret file guard and internal docs server",
  "author": { "name": "Acme Platform Team", "email": "platform@example.com" },
  "homepage": "https://example.com/acme-guardrails",
  "repository": "https://github.com/your-org/agent-plugins",
  "license": "Apache-2.0",
  "userConfig": {
    "docs_token": {
      "type": "string",
      "title": "Internal docs API token",
      "description": "Token for the Acme internal docs MCP server",
      "required": true,
      "sensitive": true
    }
  }
}

The pinned version means a push reaches nobody until the team bumps it, and the sensitive token never lands in settings.json.

The skill: skills/dependency-review/SKILL.md

---
description: Reviews dependency changes in a pull request. Use when asked to review package.json, lockfiles or requirements files.
---

Read the diff of every manifest and lockfile in the change. For each added or
upgraded package, report the exact name and whether it is one or two characters
away from a better known package, whether the lockfile pins the version, and
whether the package is new to the repository. Do not install anything.

It runs as /acme-guardrails:dependency-review, with no !`command` lines and no allowed-tools grant, so it stays instructions only.

The hook: hooks/hooks.json and its script

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/protect-secrets.sh\"" }
        ]
      }
    ]
  }
}
#!/usr/bin/env bash
# Defensive guard: stop Claude's file tools from reading or editing secret files.
set -euo pipefail
path="$(jq -r '.tool_input.file_path // empty')"
case "$path" in
  *.env|*.env.*|*.pem|*.key|*id_rsa*|*id_ed25519*)
    echo "acme-guardrails: $path holds secrets and is blocked by policy" >&2
    exit 2
    ;;
esac
exit 0

Per the hooks reference, a PreToolUse hook that exits 2 "blocks the tool call" and its stderr becomes the reason Claude sees. Two honest caveats: it only sees Claude's Read, Edit and Write calls, not a script that opens the file itself, and it runs with your full user permissions, which is why a reviewer must be able to read it in a minute.

The MCP server: .mcp.json

{
  "mcpServers": {
    "acme-docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${user_config.docs_token}" }
    }
  }
}

It appears as plugin:acme-guardrails:acme-docs, and a search tool on it is mcp__plugin_acme-guardrails_acme-docs__search in permission rules. Being remote, nothing is downloaded or executed locally to run it.

marketplace.json

{
  "name": "acme-plugins",
  "description": "Plugins reviewed and approved by Acme platform security",
  "owner": { "name": "Acme Platform Team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "acme-guardrails",
      "source": "./plugins/acme-guardrails",
      "description": "Dependency review skill, secret file guard and internal docs server"
    },
    {
      "name": "acme-formatter",
      "source": {
        "source": "github",
        "repo": "your-org/formatter",
        "ref": "v2.0.0",
        "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
      },
      "description": "Formatter plugin pinned to a reviewed commit"
    }
  ]
}

Replace the placeholder sha with the commit you reviewed, and keep each entry name equal to that plugin's own name.

Validate, install and distribute

claude plugin validate ./plugins/acme-guardrails   # ends with: ✔ Validation passed
claude plugin validate .
claude plugin marketplace add your-org/agent-plugins
claude plugin install acme-guardrails@acme-plugins --scope project
claude plugin details acme-guardrails              # prints the Component inventory

To turn it on for a whole repository, commit this to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "acme-plugins": {
      "source": { "source": "github", "repo": "your-org/agent-plugins", "ref": "v1.2.0" }
    }
  },
  "enabledPlugins": { "acme-guardrails@acme-plugins": true }
}

Per the organization guide, the extraKnownMarketplaces entries "apply only in a folder the contributor has trusted." Setting enabledPlugins does not install anything: once the marketplace is registered, each contributor runs claude plugin install <name>@<marketplace> --scope project once per clone, for acme-guardrails and acme-formatter alike. Only a plugin listed by relative path in a local directory or file marketplace skips that step.

The development loop and maintaining the catalog

While you build, run claude --plugin-dir ./plugins/acme-guardrails to load the directory for one session, and /reload-plugins after an edit. Run claude plugin validate before every push; it checks the manifest, the marketplace file and name rules. Keep each marketplace entry name equal to the plugin's own name, and remember that plugin.json wins when both set a version.

Over time the catalog needs upkeep. Set forceRemoveDeletedPlugins to uninstall a plugin you delete from plugins on users' machines, use renames to map a former plugin name to its current one, and use dependencies in a manifest or entry when one plugin needs another: installing it installs and enables the declared dependencies at the same scope. The marketplace hosting docs also describe running release channels.

When to package a plugin and when not to

You want toBest fitWhy
Give Claude reusable instructionsA standalone skillOne readable file, no update channel
Connect Claude to one external systemA standalone MCP server or a directory connectorOne trust decision; directories handle OAuth
Enforce a rule every timeA hook, in a plugin or in your settingsThe docs say a rule that "must hold every time" belongs in a hook, not a skill
Add a prompt shortcutA skill run as a slash commandSkills supersede commands
Ship a skill that needs a specific MCP serverA plugin bundling bothThey install and update together
Roll out a team toolkitA plugin in your own marketplaceVersioned releases; policy can force-enable it

Security in brief: what to review and what to enforce

Plugin security has its own live guide, so this section keeps to the essentials. For the full install-time review and allowlist rollout, see Are AI coding agent plugins and skills safe to install. For where administrators put policy, see Claude Code managed settings: where admins put policy.

The security page draws the line that matters: "Claude Code's permission rules and sandbox cover the tool calls Claude makes, not the code a plugin runs by itself."

Plugin contentHow it runsPermission rules?Sandbox?
Command hooks, monitorsShell commands with your full user permissionsNoNo
ModsJavaScript inside Claude CodeNoNo
MCP and LSP serversProcesses Claude Code starts, or remote endpointsServer start no; each MCP tool call yesNo
bin/ executablesRun when Claude calls them through BashYesFollows Bash rules
Skills, commands, agentsInstructions in Claude's contextTheir effects go through Claude's toolsTheir effects follow tool rules

Three points follow from that table. First, hooks fire from the moment a session loads the plugin, not when someone uses it, so a hook is the first file a reviewer reads. Second, the catalog owner and the plugin author are separate parties: through strict, a marketplace entry can add components to a plugin, and Anthropic's install warning says it "does not control what MCP servers, files, or other software are included in plugins and cannot verify that they will work as intended or that they won't change." Third, trust timing differs by mode. Interactively, Claude Code holds back settings-file hooks until you accept the workspace trust dialog, but in a -p or SDK session it "treats the folder as trusted, so hooks committed in a repository's .claude/settings.json run in a folder you've never trusted."

Two more risks. A stdio MCP server whose command is npx or uvx resolves a package at start time, often the latest version, so it is ordinary dependency risk; Claude Code's own install of a plugin's Node dependencies uses a lockfile, frozen resolution and --ignore-scripts, but none of that applies when a plugin's hook runs npm install or pip install itself. And skills and MCP tool results are text Claude reads, so either can steer the next tool call; the MCP page warns that "Servers that fetch external content can expose you to prompt injection risk." The OWASP MCP Top 10 files these under scope creep (MCP02:2025) and supply chain (MCP04:2025).

Risk to control table

RiskDocumented controlWhat it does not cover
Untrusted marketplacestrictKnownMarketplaces allowlist and blockedMarketplaces blocklist in managed settingsPlugins inside an allowed catalog; block those with managed enabledPlugins set to false
SideloadingdisableSideloadFlags rejects --plugin-dir, --plugin-url, --agents and folders named in CLAUDE_CODE_PLUGIN_DIRS.mcp.json and claude mcp add; pair with MCP allowlists
Lookalike namesInstall the full name@marketplace from an allow-listed catalog; check claude plugin marketplace listValidator name checks do not block installs
Silent updates and pinningref plus sha, or sha256; "autoUpdate": false on managed extraKnownMarketplaces entries; disableCommandPluginSources. A pin only helps if it is checked, so read the hash-pin bypass CVE write-upUpdates you approve without re-reviewing
Hook executionRead every hook and script; allowManagedHooksOnly limits hooks to managed settings and force-enabled pluginsHooks of force-enabled plugins still run
Over-broad toolsPermission rules, evaluated deny, then ask, then allow, on mcp__plugin_... namesHook and server processes
Unapproved MCP serversallowedMcpServers and deniedMcpServers with serverUrl or serverCommand entries; see why a cloned repository cannot approve its own serversThe docs say serverName entries are "not a security control"
SecretsRead(./.env) style deny rules, sandbox filesystem isolation, userConfig with sensitivePlugin processes outside the sandbox
Unreviewed installspluginTrustMessage appends your policy to the install warningAdvisory only
Blind spotsclaude_code.plugin_installed and claude_code.plugin_loaded OpenTelemetry eventsTelemetry records; it does not block

The monitoring page says plugin_loaded is "logged once per enabled plugin at session start," which makes it the fleet inventory. Names of community and third-party plugins are replaced with third-party or omitted unless you set OTEL_LOG_TOOL_DETAILS=1. Our guide to sending Claude Code and Codex telemetry to Safeguard over OTLP shows the setup.

To remove a plugin you distrust, run claude plugin uninstall <plugin> with its --scope, delete its directory under ~/.claude/plugins/cache/ (otherwise kept 14 days), and remove the marketplace if you distrust its owner.

How other agents package extensions

Each vendor's own docs, as fetched on 2 November 2026:

  • OpenAI Codex and ChatGPT. "Plugins bundle capabilities into reusable workflows in ChatGPT and Codex. They can include skills and MCP servers," and both products "use one universal plugin directory," per OpenAI's plugins page; Codex CLI opens it with /plugins, and plugins can also come from a marketplace source. OpenAI's developer docs cover building plugins around an MCP server and skills.
  • Cursor. Cursor's docs say plugins "package rules, skills, agents, commands, MCP servers, and hooks," in two formats: Agent Plugins "with a plugin.json manifest at the plugin root," and Cursor Plugins "with a .cursor-plugin/plugin.json manifest." Its mcp.json uses ${CURSOR_PLUGIN_ROOT}.
  • VS Code. Microsoft's extension runtime security page says "The extension host has the same permissions as VS Code itself." Open VSX publishes extensions under a namespace taken from the publisher field.
Claude CodeCodex and ChatGPTCursorVS Code
Manifest.claude-plugin/plugin.jsonPer OpenAI's plugin docsplugin.json or .cursor-plugin/plugin.jsonpackage.json
BundlesSkills, agents, hooks, MCP and LSP servers, moreSkills and MCP servers, per OpenAI's overviewRules, skills, agents, commands, MCP, hooksExtension code
Local codeHooks, monitors, stdio servers, bin/Local MCP servers; OpenAI says to review and trust plugin hooks before they runHooks, local MCP serversThe whole extension

Where Safeguard fits

Safeguard fits around plugins in these places.

Install Safeguard from the directory first. The download page says "Add Safeguard from Claude's connector directory on web, desktop or mobile," with OAuth sign-in, and "Install Safeguard from the ChatGPT plugin directory." A custom MCP URL on mcp.safeguard.sh is the fallback; verify the publisher in the official MCP Registry first.

Companion skills, and a benchmark for vendor plugins. Safeguard publishes companion skills on GitHub at Safeguard-sh/safeguard under Apache-2.0: safeguard, safeguard-triage, safeguard-reporting and safeguard-at-scale. The README is explicit that "The connector is read only," and that a plugin build "also bundles the connector definition." A bundle like that needs only a manifest and a remote server entry, along these lines (shown here with the public custom URL from the download page):

{
  "mcpServers": {
    "safeguard": { "type": "http", "url": "https://mcp.safeguard.sh/mcp" }
  }
}

Use that shape as your benchmark: a remote HTTPS server with OAuth, skills that are instructions only, no hooks and no bin/. The public Cursor plugin follows the same idea with a root plugin.json and mcp.json.

Vet bundled servers and skills with Gold Open Source. Gold Open Source is free and needs no login. gold.safeguard.sh/mcp lists servers from the official MCP Registry with detail pages, so you can confirm the namespace belongs to the publisher you expect. gold.safeguard.sh/skills lists skills "from official Anthropic Agent Skills to notable community skills" with the publisher and canonical source. Both settle identity first, so your review time goes to hooks and code. See vet an MCP server and vet an agent skill.

Control what plugins install with Package Firewall. The docs describe it as a way to "Stop malicious and typosquatted dependencies at install time," with "inline allow / warn / block enforcement for typosquats, dependency confusion, and known-malicious packages." It "runs as an install-time proxy fronting npm and pip," and "coverage is transitive by construction." That covers an npx-launched MCP server or a hook running npm install or pip install on a machine routed through the proxy. More in the Package Firewall overview.

Common mistakes

  • Entry name and manifest name that differ. Installing by the manifest name then fails with Plugin "<manifest-name>" not found in marketplace "<marketplace>".
  • A relative path in a url marketplace. Only marketplace.json is fetched, so nothing resolves.
  • Matching hooks or rules on the server name. Use mcp__plugin_<plugin>_<server>__<tool>.
  • Leaving version unset and expecting stability. Every commit is then an update; pin version or a commit.

FAQ

What is a Claude Code plugin?

A directory of components, such as skills, subagents, hooks, MCP and LSP servers, usually with a manifest at .claude-plugin/plugin.json, that Claude Code installs and loads as one unit, typically from a marketplace.

Are Claude Code plugins safe?

As safe as the code in them. Anthropic says a plugin can execute arbitrary code with your privileges and that it does not control what third-party plugins include. Review hooks, MCP definitions and executables, and pin what you reviewed.

How do I install a plugin from a marketplace?

Run claude plugin marketplace add owner/repo, then claude plugin install name@marketplace, or the /plugin equivalents in a session. The official marketplace is added on your first interactive session.

What is the difference between a plugin, a skill and an MCP server?

A skill is a SKILL.md of instructions, an MCP server gives Claude tools, and a plugin packages both, plus hooks and more, so they install and update together.

Do plugins update automatically?

Only from marketplaces with auto-update on: by default the official ones, not community or third-party ones. Updates load on the next launch or after /reload-plugins.

How do I pin a plugin version?

Use a git source with ref and a full 40-character sha, or an archive source with sha256. A version string in plugin.json also holds users on the cached copy.

How can an organization restrict plugins?

Managed settings: strictKnownMarketplaces, blockedMarketplaces, enabledPlugins, disableSideloadFlags, and optionally allowManagedHooksOnly and disableCommandPluginSources.

Plugins pull open source packages onto developer machines and CI runners, and the MCP servers they bundle carry dependencies of their own. When one of those components has a known vulnerability, the fix path is the same as for any other dependency you ship.

Fix it without waiting for upstream

Whatever the vulnerability, most of the risk sits in two gaps. The first is the time between a fix being published and that fix actually running in your production builds. The second, and worse, is the time before any fix exists at all, while a maintainer works out a patch and a release schedule. Waiting through both gaps is a habit, not a requirement. Safeguard gives teams three ways to close them.

1. Autonomous remediation: pull requests, not tickets

When a fixed version exists, Griffin, Safeguard's security model, opens a policy gated pull request that moves the affected dependency to the safe version, and your own CI runs your tests on it before anyone merges. You can run it on one repository or in bulk across every project that carries the vulnerable version. Remediation categories include dependencies, licenses, security posture and findings, and each one is set separately. Reachability analysis ranks the vulnerable code paths your application actually calls first, so the first pull requests you merge are the ones that matter most. Auto-merge is a separate switch and stays off by default, so your team decides what merges on its own and what still needs a human approval.

2. Gold Open Source: the safe version in seconds, free

gold.safeguard.sh is free and needs no login. Search any CVE or package to see affected and fixed versions, CVSS, EPSS, CISA KEV status and a recommended safe version, or use the "Am I affected?" checker. The same data is available through a free read API, README status badges and RSS threat feeds.

3. Gold Registry: start from components that are already fixed

Safeguard Gold rebuilds patched versions of open-source packages and images from source, signs each build, attaches an SBOM, SLSA provenance and VEX, and serves them from registry.safeguard.sh to your organization. Every Gold artifact is held continuously to zero exploitable critical or high CVEs and a completed license check, with signed build provenance (signed with Safeguard's key and verifiable with cosign, SLSA Build Level 3 as the design target) and a public evidence page you can hand to an auditor. An artifact loses its Gold badge if it regresses. Teams can point their own package directory at the registry so hardened equivalents resolve without changing how developers install anything.

When upstream has no fix yet, or will not ship one, Safeguard first works to get the fix accepted upstream. If the issue is severe or upstream will not move, Safeguard builds a fork, fixes the vulnerability there and publishes a hardened Gold build, so you are not stuck on a maintainer's release schedule. You can also request a hardened build of a specific package. Ask which packages it covers before you plan around it.

Your situationWhat to use
A fixed version existsAutonomous remediation opens the upgrade pull request; Gold Open Source confirms the safe version
You need to know today whether you are affectedGold Open Source lookup and "Am I affected?" checker, free and without login
You want vulnerable versions to stop shippingSafeguard policies and gates in CI
Upstream has no fix yet, or will not ship oneA custom Gold request; fork and patch
You want to start clean on new projectsPull hardened components and images from Gold Registry

The steps above apply to the open source dependencies and container images you build and ship, which is where most teams carry the largest and least tracked share of their exposure.

See how Safeguard would help

These demos show real Safeguard sessions on other examples, not a plugin review.

The Claude demo connects Claude to the Safeguard MCP server with OAuth and chooses which tools Claude can use. Choosing a narrow tool set is the same discipline to apply to any connector a plugin bundles.

Click through it at your own pace, or open it full screen.

The CLI demo installs the Safeguard CLI, asks it to fix a vulnerable dependency, approves each step and runs a scan. The same loop applies to a vulnerable dependency in a repository that holds a plugin.

Click through it at your own pace, or open it full screen.

The local runner demo sets up the runner on your own machine, approves it with a device code and scans from the terminal, for teams that want scanning next to the code.

Click through it at your own pace, or open it full screen.

Quick check

Which plugin components run outside Claude Code's sandbox and permission rules?

Hooks, monitors, MCP servers, LSP servers and processes a mod starts. Permission rules cover Claude's tool calls, including calls to a plugin's MCP tools and executables in its bin/ directory, but not code the plugin runs on its own.

A third-party plugin has no version field and its marketplace has auto-update on. What happens when the author pushes a commit?

The computed version becomes the new commit SHA, so the next background refresh updates the cached copy on disk and the next session loads the new code.

What is the tool name to use in a permission rule for a tool called query on a server named db in a plugin named my-plugin?

mcp__plugin_my-plugin_db__query. A rule or matcher on the server name alone never matches.

Which managed setting stops users loading plugins with --plugin-dir?

disableSideloadFlags. The strictKnownMarketplaces allowlist does not cover --plugin-dir.

Sources

Last reviewed: 15 November 2026.

Never miss an update

Weekly insights on software supply chain security, delivered to your inbox.

We email you a link to confirm, and only then add you to the list. Unsubscribe in one click. Privacy

Self-healing security runs on Safeguard.

Your first fix PR is minutes away.

No sales call required, even your agent can complete the purchase over MCP.