Plugin loading reference - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Use this page when a plugin didn’t load, loaded a different copy than you expected, or didn’t pick up an update, and you want to see which source, settings scope, or file on disk decided that.
It gives the rules Claude Code applies when a session starts and each time you run /reload-plugins . You can also ask Claude to read this page and diagnose your setup. These cases are covered on other pages: Install, enable, disable, and update steps : see Install and manage plugins You have a specific error message : see Troubleshoot plugins Start with Check which stage a plugin reached for the three stages an installed plugin passes through, or go to the section that matches what you’re seeing: A plugin you turned off still loads: Find where a plugin is enabled An update changed nothing: Versions and updates You’re looking at the files under ~/.claude/plugins/ : Find plugins on disk A --plugin-dir plugin didn’t load, or a same-named plugin loaded instead: Name conflicts A plugin under ~/.claude/skills/ or .claude/skills/ didn’t load, and no error says why: Skills-directory plugins blocked by managed settings Check which stage a plugin reached An enabledPlugins entry becomes a plugin you can use in stages: your settings declare it, Claude Code fetches it to disk, and the running session loads it.
When a plugin doesn’t behave as a settings file suggests, check which stage it reached: Declared, in settings : enabledPlugins says which plugins should be on, and extraKnownMarketplaces says which marketplaces should exist. When you run claude plugin marketplace add , Claude Code writes the marketplace to extraKnownMarketplaces in your user settings as well as to disk Fetched, on disk under ~/.claude/plugins/ : the records of what Claude Code has fetched, and the fetched files themselves: known_marketplaces.json records each marketplace Claude Code has fetched, with its source , installLocation , lastUpdated , and autoUpdate .
There is one known_marketplaces.json per user, so a marketplace you add in one project is available in every project installed_plugins.json records each install with its scope , installPath , and version cache/ holds the plugin files Loaded, in the running session : the plugin set Claude Code loaded at startup or at the last reload. After you install, update, enable, or disable a plugin outside the /plugin panel, run /reload-plugins in the session or start a new session Plugins and marketplaces that aren’t on disk at session start Plugins load at session start from installed_plugins.json and the cache without using the network.
After the session starts, Claude Code checks the declared marketplaces in the background: A marketplace that settings declare but known_marketplaces.json lacks : Claude Code clones it, then reloads plugins and downloads enabled plugins that aren’t cached yet A declared marketplace whose source changed in settings : Claude Code re-fetches it from the new source and shows Plugins changed. Run /reload-plugins to activate.
An enabled plugin that neither path fetched and that has no usable cache directory shows Plugin "<name>" not cached at <path> in the /plugin Errors tab. For the fix, see Plugin "<name>" not cached at <path> . Find where a plugin came from Every plugin has an id of the form <name>@<origin> , which is what you see in settings files and in claude plugin list --json . The part after @ tells you where Claude Code found the plugin: ID ends in How the plugin got there How you turn it on or off @<marketplace> You installed it from a marketplace you added "<name>@<marketplace>": true or false under enabledPlugins in a settings file @inline You started Claude Code with --plugin-dir or --plugin-url , set CLAUDE_CODE_PLUGIN_DIRS , or an Agent SDK app passed the plugins option.
It loads for that session only On for the session unless the manifest sets defaultEnabled: false or a settings file sets "<name>@inline": false @skills-dir You saved a plugin directory that has a .claude-plugin/plugin.json under ~/.claude/skills/ or the project’s .claude/skills/ The manifest’s defaultEnabled , unless a settings file sets "<name>@skills-dir" to true or false @synced You or your organization turned it on for your claude.ai account, and Claude Code downloaded it On unless the manifest sets defaultEnabled: false or a settings file sets "<name>@synced": false .
A plugin your organization marks as required loads regardless For a marketplace plugin, <name> is the entry name in marketplace.json ; for @inline and @skills-dir it’s the name in the plugin’s manifest. The origin names in this table are reserved, so no marketplace can be named inline , skills-dir , or synced . Entry name and manifest name A marketplace plugin has two names, and they can differ: The entry name in marketplace.json : the install and enable key.
It’s what you write in enabledPlugins , what the cache directory is named after, and what claude plugin list shows The name in the manifest : what the plugin’s components are namespaced under, and what name conflicts compare Plugins shared through a repository To share a plugin through a repository, list it under enabledPlugins in .claude/settings.json or place it under .claude/skills/ . Claude Code doesn’t scan a project’s .claude/plugins/ directory.
A cloud session doesn’t add the marketplaces a repository lists under extraKnownMarketplaces , because that requires the workspace trust dialog, which a cloud session never shows. Trust check and component limits for repository plugins A project-scope plugin is checked into the repository and reaches every collaborator who clones it. Because that content comes from the repository rather than from you, it loads only after the same trust check that applies to project allow rules in .claude/settings.json .
Trusting a parent folder or running with -p isn’t enough. Components that run code are restricted further: MCP servers it declares go through the same per-server approval as a project .mcp.json MCP servers it declares as an MCP bundle , a .mcpb or .dxt file, or from a file outside the plugin directory are skipped. Declare them inline or in a .mcp.json inside the plugin directory Background monitors do not load Neither the trust check nor these component limits apply to a plugin under your own ~/.claude/skills/ .
For how to write --plugin-dir and skills-directory plugins, see Create plugins . Check why a repository plugin didn’t load If a plugin in your repository’s .claude/skills/ doesn’t load, check for these causes: In a subdirectory : a plugin at the repository root doesn’t load. Claude Code reads the .claude/skills/ of the session’s primary working directory and, unlike plain skills and commands, doesn’t search parent directories for plugins.
Launch from the repository root instead, or move the session there with /cd on v2.1.246 or later From the desktop app, in a worktree : the plugin loads from the main checkout’s .claude/skills/ rather than the worktree’s. See What worktrees share with the main checkout In a folder you haven’t trusted : the plugin loads only after you accept the workspace trust dialog for that folder In an organization that manages Claude Code : see Skills-directory plugins blocked by managed settings Skills-directory plugins blocked by managed settings If a plugin folder in ~/.claude/skills/ or a project’s .claude/skills/ didn’t load and you see no error, your administrator may have blocked it through managed settings .
These folders come from you or your repository rather than from a marketplace, so Claude Code skips them when your administrator sets one of these restrictions: Customization locked to plugins : strictPluginOnlyCustomization set to true or
The rest of this page is on the live site.