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.
• 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.
• Plugins inherit the project's permission model. A plugin can only use tools and MCP servers that are already allowed for the session. It can't silently expand the permission boundary.

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.