Make a plugin safe to install
Last reviewed October 24, 2026
Claude Code's security page says it plainly: "A Claude Code plugin you install can execute arbitrary code on your machine with your user privileges" (plugin security). That is what you are asking people to accept. This step is about making the request easy to say yes to.
What a plugin can do
Skills, commands and subagents reach the agent as instructions. Hooks are shell commands that run with the user's permissions. Hooks, MCP servers and language servers all run outside Claude Code's sandbox, and the permission rules people set apply only to the agent's own tool calls. So a hook does whatever it says, every time its event fires, without asking.
What people see before they install
Claude Code shows which skills, commands, hooks and servers a plugin will install, but not what a hook runs. Its docs tell people to read hooks/hooks.json, .mcp.json and everything in bin/ themselves. Codex holds back a plugin's hooks until the user has reviewed and trusted them. Gemini CLI asks for consent with a warning of its own:
The extension you are about to install may have been created by a third-party developer and
sourced from a public repository. Google does not vet, endorse, or guarantee the functionality or
security of extensions.Write for the person who does read the files. Use a hook only when a skill or command cannot do the job, keep each one short enough to understand at a glance, and say in the README what each hook runs and why.
Pin what you list
A marketplace entry that points at another repository without a sha installs whatever that repository holds on the day. Pin each outside source to a full commit SHA, or an archive to its sha256, so people install the code that was reviewed (the marketplace step shows how). Updates can change files after people have looked at them, which is one more reason to say in your changelog what each release changes.
Ask for secrets; never ship them
Everything in a plugin is readable by everyone who installs it. When the plugin needs a key, declare it in the manifest's userConfig with "sensitive": true. Claude Code asks the user for it, masks what they type, and keeps it in secure storage instead of the settings file:
"userConfig": {
"tracker_token": {
"type": "string",
"title": "Tracker API token",
"description": "A read-only token for your issue tracker.",
"sensitive": true
}
}Then refer to it where it is needed, and use https for a remote server:
{
"mcpServers": {
"tracker": {
"type": "http",
"url": "https://tracker.example.com/mcp",
"headers": { "Authorization": "Bearer ${user_config.tracker_token}" }
}
}
}The Agent Plugins format forbids secrets in a server's env or headers too, and Gemini CLI keeps a setting marked sensitive in the system keychain.
Let the validator catch the rest
claude plugin validate warns about the usual slips. Run against a careless version of the plugin above, it said:
⚠ mcpServers.tracker.url: url uses http:// to a non-loopback host — requests, headers and any
credentials travel in cleartext. Use https://
⚠ mcpServers.tracker.headers.Authorization: header value looks like a literal credential.
Everything shipped in a plugin is readable by everyone who installs it
⚠ hooks.SessionStart: Shell command uses ${CLAUDE_PLUGIN_ROOT} without quotesQuote "${CLAUDE_PLUGIN_ROOT}" in shell hooks so a path with a space still works, and keep anything the plugin writes in ${CLAUDE_PLUGIN_DATA}, since an update replaces the plugin folder. With --strict in CI, none of these warnings reaches a release.
This site's scan
This site's safety scan reads a plugin's manifest and README. It looks for instructions that override the agent's role, addresses that look like they carry data away, hidden or obfuscated text, embedded secrets, destructive commands and suspicious downloads. If a finding on your listing is wrong, sign in and dispute it from the listing page.
Building something else? See the guides to a skill and an MCP server.