Plugins

A plugin is a shareable bundle that drops slash commands, subagent definitions, MCP server configs, and hooks into your Claude Code setup in one shot. Instead of manually wiring up a formatter hook, a /lint command, and a test-writing agent separately, you ship them as a single installable unit. Anthropic launched a curated marketplace in December 2025 with 36 plugins; you can also install directly from a GitHub URL.

The directory structure is what defines a plugin: a plugin.json manifest at the root, plus commands/, agents/, hooks/, mcp/, and scripts/ folders for each capability type. Only include the folders your plugin actually needs.

How you use it day-to-day

• Install from the marketplace. Run /plugin install <plugin-name> to pull a curated plugin by name. For a third-party plugin, pass the full GitHub URL instead.
• Discover what's available. Use /plugin search <keyword> to browse the marketplace without leaving the session.
• Package a workflow you repeat. If you've built a set of slash commands and hooks for a project pattern (e.g., a code-quality suite with auto-format-on-write), bundle them into a plugin so every project can install it in seconds rather than copying files around.
• Reference plugin scripts from hooks. The ${CLAUDE_PLUGIN_ROOT} variable in hooks/hooks.json resolves to the installed plugin directory, so your hook commands can call bundled scripts without hardcoded paths.
• Know when a plugin is a mod. Since 2.1.287 a plugin can also carry a mod: JavaScript or TypeScript that runs inside Claude Code and can change tool calls, prompts and the screen. /plugin shows a line like 1 mod active · name when one loads. See Mods for what that means and how to switch them off.
• Publish via GitHub. Put plugin.json at the repo root, tag a release, and anyone can install it with the URL form. Submit to the marketplace if you want it curated.

Gotchas

• Manifest is required. plugin.json must be at the repo root or the install will fail. Every capability your plugin uses (commands, agents, hooks, mcp) needs a corresponding entry in the manifest pointing to the right path globs or files.
• Hooks run with plugin scope. Use ${CLAUDE_PLUGIN_ROOT} for plugin scripts and ${CLAUDE_PROJECT_DIR} for project-relative paths. Mixing them up is the most common source of hook failures after install.
• Single responsibility keeps plugins composable. A plugin that does too much (formatting
  • testing + docs + CI) becomes a liability when you only need one piece. Scope each plugin to one domain; users can install multiple.
• Commands, agents and skills inherit your permission model; mods do not. Those parts of a plugin can only use tools already allowed for the session. A plugin that contains a mod (2.1.287 and later) runs code inside Claude Code with your permissions, unsandboxed, and can approve tool calls your ask rules or your own PreToolUse hooks would stop. Run claude plugin validate on it first. See Mods.

Build vs install. If you just need a one-off slash command or hook for a single project, drop it in .claude/commands/ or .claude/settings.json directly. A plugin makes sense once you want to reuse or share that setup across projects or teammates.