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
nameis required inplugin.json, and the manifest itself is optional. - A marketplace is a
.claude-plugin/marketplace.jsoncatalog 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.jsonso the whole repository gets it. - A plugin with no
versionfield tracks its source commit; a pinnedversionkeeps 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.
| Component | Default location | What it does |
|---|---|---|
| Manifest | .claude-plugin/plugin.json | Metadata and configuration; optional, and only name is required in it |
| Skills | skills/<name>/SKILL.md | Instructions Claude loads when relevant, runnable as /<plugin>:<name> |
| Commands | commands/*.md | Older single-file format that skills supersede |
| Agents | agents/*.md | Subagents named <plugin>:<name> |
| Hooks | hooks/hooks.json | Handlers at lifecycle events such as PreToolUse or SessionStart |
| MCP servers | .mcp.json | Tool servers connected while the plugin is enabled |
| LSP servers | .lsp.json | Language servers for code intelligence |
| Monitors | monitors/monitors.json | Background shell commands Claude Code starts itself; the manifest key sits under experimental |
| Executables | bin/ | Added to the Bash tool's PATH |
| Output styles, themes, workflows | output-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:
| Field | What it does | Review note |
|---|---|---|
name | Kebab-case identifier; components are namespaced under it | Reserved-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, license | Metadata; homepage must parse as a URL | Who to hold responsible |
defaultEnabled | Whether it starts enabled; default true | Installing usually enables |
dependencies | Other plugins that must be enabled | One install can pull in more |
userConfig | Values prompted for on enable | Look for sensitive on secrets |
hooks, mcpServers, lspServers | Extra hook, MCP and LSP definitions, loaded with the default files | Components can hide in the manifest |
skills, commands, agents | Extra component locations | Not 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 type | Fields | What to know |
|---|---|---|
| Relative path | ./path string | A directory inside the marketplace repository |
github | repo, ref, sha | owner/repo on GitHub |
url | url, ref, sha | Any git repository |
git-subdir | url, path, ref, sha | One subdirectory via sparse checkout |
npm | package, version, registry | Fetched "without running install scripts" |
archive | url, sha256 | HTTPS zip; a digest mismatch is refused |
command | command, timeout, mode | A 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 forgithub,git,fileanddirectorymarketplaces. A marketplace added from a bareurlfetches onlymarketplace.json, so give each plugin an object source there. Settingmetadata.pluginRootto./pluginslets you write the bare nameformatterinstead. github,urlandgit-subdirpoint at separate repositories.git-subdiruses a sparse checkout, so a plugin in a large monorepo installs without downloading the rest.npmtakespackage, an optionalversion(a version, range or dist-tag; omitted meanslatest) and an optionalregistry. Claude Code fetches it with your npm client and never runs its install scripts. Git addresses, folder paths andnpm:aliases are refused aspackagevalues.archiveis an HTTPS zip, pinned bysha256so a mismatched download is refused.commandruns 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
| Task | In a session | In your shell |
|---|---|---|
| Add a marketplace | /plugin marketplace add your-org/plugins#v1.2.0 | claude plugin marketplace add your-org/plugins#v1.2.0 |
| Install | /plugin install name@marketplace | claude plugin install name@marketplace --scope project |
| Disable, enable | /plugin disable, /plugin enable | claude plugin disable name@marketplace |
| Update one plugin | Update now in /plugin | claude plugin update name@marketplace |
| Inspect | details pane in /plugin | claude plugin details name |
| Uninstall | /plugin uninstall | claude plugin uninstall name@marketplace --scope project |
| Remove a marketplace | /plugin marketplace remove name | claude 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 to | Best fit | Why |
|---|---|---|
| Give Claude reusable instructions | A standalone skill | One readable file, no update channel |
| Connect Claude to one external system | A standalone MCP server or a directory connector | One trust decision; directories handle OAuth |
| Enforce a rule every time | A hook, in a plugin or in your settings | The docs say a rule that "must hold every time" belongs in a hook, not a skill |
| Add a prompt shortcut | A skill run as a slash command | Skills supersede commands |
| Ship a skill that needs a specific MCP server | A plugin bundling both | They install and update together |
| Roll out a team toolkit | A plugin in your own marketplace | Versioned 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 content | How it runs | Permission rules? | Sandbox? |
|---|---|---|---|
| Command hooks, monitors | Shell commands with your full user permissions | No | No |
| Mods | JavaScript inside Claude Code | No | No |
| MCP and LSP servers | Processes Claude Code starts, or remote endpoints | Server start no; each MCP tool call yes | No |
bin/ executables | Run when Claude calls them through Bash | Yes | Follows Bash rules |
| Skills, commands, agents | Instructions in Claude's context | Their effects go through Claude's tools | Their 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
| Risk | Documented control | What it does not cover |
|---|---|---|
| Untrusted marketplace | strictKnownMarketplaces allowlist and blockedMarketplaces blocklist in managed settings | Plugins inside an allowed catalog; block those with managed enabledPlugins set to false |
| Sideloading | disableSideloadFlags 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 names | Install the full name@marketplace from an allow-listed catalog; check claude plugin marketplace list | Validator name checks do not block installs |
| Silent updates and pinning | ref 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-up | Updates you approve without re-reviewing |
| Hook execution | Read every hook and script; allowManagedHooksOnly limits hooks to managed settings and force-enabled plugins | Hooks of force-enabled plugins still run |
| Over-broad tools | Permission rules, evaluated deny, then ask, then allow, on mcp__plugin_... names | Hook and server processes |
| Unapproved MCP servers | allowedMcpServers and deniedMcpServers with serverUrl or serverCommand entries; see why a cloned repository cannot approve its own servers | The docs say serverName entries are "not a security control" |
| Secrets | Read(./.env) style deny rules, sandbox filesystem isolation, userConfig with sensitive | Plugin processes outside the sandbox |
| Unreviewed installs | pluginTrustMessage appends your policy to the install warning | Advisory only |
| Blind spots | claude_code.plugin_installed and claude_code.plugin_loaded OpenTelemetry events | Telemetry 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.jsonuses${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
publisherfield.
| Claude Code | Codex and ChatGPT | Cursor | VS Code | |
|---|---|---|---|---|
| Manifest | .claude-plugin/plugin.json | Per OpenAI's plugin docs | plugin.json or .cursor-plugin/plugin.json | package.json |
| Bundles | Skills, agents, hooks, MCP and LSP servers, more | Skills and MCP servers, per OpenAI's overview | Rules, skills, agents, commands, MCP, hooks | Extension code |
| Local code | Hooks, monitors, stdio servers, bin/ | Local MCP servers; OpenAI says to review and trust plugin hooks before they run | Hooks, local MCP servers | The 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
urlmarketplace. Onlymarketplace.jsonis fetched, so nothing resolves. - Matching hooks or rules on the server name. Use
mcp__plugin_<plugin>_<server>__<tool>. - Leaving
versionunset and expecting stability. Every commit is then an update; pinversionor 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 situation | What to use |
|---|---|
| A fixed version exists | Autonomous remediation opens the upgrade pull request; Gold Open Source confirms the safe version |
| You need to know today whether you are affected | Gold Open Source lookup and "Am I affected?" checker, free and without login |
| You want vulnerable versions to stop shipping | Safeguard policies and gates in CI |
| Upstream has no fix yet, or will not ship one | A custom Gold request; fork and patch |
| You want to start clean on new projects | Pull 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
- Plugins overview, Claude Code Docs
- Add components to a plugin, Claude Code Docs
- Plugin manifest reference, Claude Code Docs
- Marketplace reference, Claude Code Docs
- Create a marketplace, Claude Code Docs
- Install and manage plugins, Claude Code Docs
- Plugin loading reference, Claude Code Docs
- Plugin security and trust, Claude Code Docs
- Manage Claude Code plugins for your organization, Claude Code Docs
- Hooks reference, Claude Code Docs
- Skills, Claude Code Docs
- MCP, Claude Code Docs
- Managed MCP, Claude Code Docs
- Permissions, Claude Code Docs
- Sandboxing, Claude Code Docs
- Settings, Claude Code Docs
- Monitoring usage, Claude Code Docs
- Model Context Protocol specification, version 2025-11-25
- MCP security best practices, version 2025-11-25
- OWASP MCP Top 10
- Plugins in ChatGPT and Codex, OpenAI
- Model Context Protocol in Codex, OpenAI
- Plugins developer documentation, OpenAI
- Plugins, Cursor Docs
- Extension runtime security, Visual Studio Code Docs
- Publishing Extensions, Open VSX wiki
- Safeguard companion skills, GitHub
- Safeguard plugin for Cursor, GitHub
- Download and connect Safeguard, safeguard.sh
- Package Firewall, Safeguard Docs
- Gold Open Source
Last reviewed: 15 November 2026.