17 — Plugin Deep Dive
Most plugins aren't worth installing. Here's how to tell the difference before you commit.
What a plugin actually contains
A Claude Code plugin is a directory that can export any combination of:
- Agents — named sub-models with a defined role and system prompt
- Skills — reusable instructions Claude can invoke by name
- Commands — slash commands that trigger a specific prompt sequence
- Hooks — scripts that run on lifecycle events (session start, file write, commit, etc.)
Before installing anything, check which of these it exports. A plugin with only hooks is very different from one with agents. Know what you're adding.
The evaluation rubric
Four questions before you install:
1. Does it do something you can't already do? If it's just a prompt wrapper for something Claude does fine natively, skip it. Real value is new capability — an MCP connection, a hook that enforces a rule, an agent trained on a domain.
2. Is it maintained? Check the last commit date. A plugin that hasn't been touched in a year may have broken hooks or agents that reference deprecated behaviour. Prefer active repos.
3. Does it overlap with something you already have? Two memory plugins, two review agents, two design-system hooks — conflicts are subtle and hard to debug. Map what you have before adding more.
4. Can you read it before you run it? Hooks especially run code on your machine. If the plugin executes shell scripts and you can't read them, don't install it.
Plugin categories worth knowing about
Three categories come up often enough to understand:
Memory plugins Persist context across sessions — entities, decisions, project state. Useful when you work on long-lived projects and don't want to re-brief Claude each time. Evaluate: what does it store, where, and how does it retrieve?
Hook plugins Enforce rules automatically: lint before commit, inject context on session start, format files on write. The best ones are invisible when working and loud when something would have gone wrong. Evaluate: what lifecycle event does each hook attach to, and what does it actually run?
Design system plugins Inject visual rules — component conventions, token usage, accessibility checks — into Claude's context. Useful if you have an established system and want Claude to work within it. Evaluate: is it generic enough to apply to your stack, or is it hardwired to someone else's setup?
Debugging a plugin
If something behaves unexpectedly after installing a plugin:
- Check which hooks are active:
claude hooks list - Check which agents are loaded:
claude agents list - Disable the plugin and reproduce the issue — if it goes away, you found it
- Read the hook scripts directly — they're plain files in the plugin directory
Most plugin bugs are hook ordering issues or conflicts between two plugins touching the same event.
The right install cadence
Add plugins one at a time. Run your normal workflow after each addition. If nothing breaks and the new capability is useful, keep it. If you can't tell what changed, remove it.
A small set of well-understood plugins beats a large set of ones you've forgotten about.