verdict: start with repo instructions, then one MCP server, then one plugin only if the workflow repeats.
updated 2026-05-17: refreshed after the SEO repair pass. the rule did not change: repo policy first, one capability layer second, plugins only after the workflow repeats.
| if the problem is… | fix it with… | example |
|---|---|---|
| Claude ignores repo conventions | AGENTS.md / CLAUDE.md | commands, architecture, review rules |
| Claude needs to touch a system | MCP server | browser, GitHub, database, docs |
| Claude repeats a workflow badly | plugin / skill | TDD, review, debugging, planning |
if you have not decided where repo instructions belong yet, start with AGENTS.md vs CLAUDE.md vs Cursor/Windsurf/Copilot . plugins come after that; otherwise you’re dressing up bad repo policy.
lock instructions first
most bad Claude Code setups have the same shape: ten plugins, no repo policy.
that is backwards.
Claude needs a working contract before it needs more tricks. put the boring rules where the agent can actually read them:
- how to install dependencies;
- how to run tests;
- which files are generated;
- what not to touch;
- what “done” means for this repo;
- how to handle secrets, migrations, and deploys.
that contract belongs in your repo instruction file. for multi-agent repos, use AGENTS.md as the source-of-truth policy file and generate vendor adapters when needed. for Claude-only repos, CLAUDE.md can be enough.
then add one capability layer, usually an MCP server for browser, GitHub, docs, database, or local tooling.
then add plugins.
decision tree
what are you trying to fix?
├─ repo behavior is wrong
│ └─ edit AGENTS.md / CLAUDE.md
├─ Claude needs access to another system
│ └─ add one MCP server
└─ the same workflow repeats across tasks
└─ add a plugin / skill
use the smallest layer that fixes the problem. every plugin adds instructions. every instruction competes for attention.
selector matrix
this is a minimum viable stack, not a catalog.
| job | start with | skip for now | why |
|---|---|---|---|
| baseline Claude Code behavior | current official Claude Code plugin marketplace / official plugins | random “awesome” bundles as your first install | start with the native path before importing someone else’s taste |
| test-driven development | superpowers-style TDD workflow plugin | generic “10x coding” packs | TDD works because it forces a loop, not because the README sounds smart |
| project decomposition | a narrow task-planning plugin such as Taskmaster | full project-manager bots before repo policy exists | useful when the work has dependencies and sequence |
| structural refactors | AST-aware tooling such as ast-grep | regex-only refactor helpers | AST transforms beat vibes when code shape matters |
| browser workflows | Playwright MCP or browser MCP first | browser plugins before screenshot/trace access works | browser agents need observability, not more prose |
| source skepticism | a critical-thinking / review plugin | confidence booster skills | good agents should argue with the plan before they execute it |
| research | a search/retrieval MCP with receipts | unsourced summary plugins | retrieval should produce evidence, not longer summaries |
| content workflows | a narrow editorial review plugin | broad “content machine” packs | useful only when it encodes a repeatable standard |
if the row points to an MCP server, treat it as a prerequisite layer, not a plugin recommendation. the point is stack order.
minimum stack
for a new Claude Code setup, start here:
- repo instruction file;
- one MCP server for the system you actually need;
- one workflow plugin for the job that repeats most.
example:
AGENTS.md or CLAUDE.md repo policy
Playwright/GitHub/docs MCP external capability
TDD/review/planning plugin repeated workflow
run a real task after each layer. if Claude still fails because it lacks access, add a capability. if it fails because it does not understand the repo, edit the instruction file. if it fails because a workflow repeats badly, add one plugin.
install path
current Claude Code exposes plugin management through claude plugin:
claude plugin marketplace list
claude plugin marketplace add <github-repo-or-url>
claude plugin install <plugin-name>
some repos still call these objects “skills”. don’t fight the wording. verify the current install command in the plugin README or marketplace before adding it to your default stack.
for project-scoped installs, check the CLI help first:
claude plugin install --help
if a plugin is not in your configured marketplace, add the marketplace or follow the repo’s own install instructions. don’t paste stale install commands into your team docs and call that automation.
what to skip
skip anything that does one of these:
- injects a giant manifesto into every session;
- duplicates what your repo instruction file should already say;
- claims to “make Claude senior” without showing the workflow;
- hides source links and expected behavior;
- adds planning when your problem is testing;
- adds research when your problem is decision quality.
plugins are compressed checklists. install them when you want that checklist loaded repeatedly.
evaluation checklist
before a plugin becomes part of your default stack, run this:
| check | pass condition |
|---|---|
| source | you can read the instructions it injects |
| scope | it solves one named job |
| weight | it does not flood context with generic advice |
| test | it improves a real task in your repo |
| fallback | you can write the same rule in AGENTS.md if the plugin disappears |
if you cannot explain what the plugin changes, do not install it globally.
stack shape
repo policy AGENTS.md / CLAUDE.md
external access MCP servers
repeatable loops plugins / skills
execution terminal, tests, diffs, review
when those layers blur, you get stale instructions in memory, duplicated rules in five files, plugins fighting the repo, and Claude confidently doing the wrong thing.
that is why context engineering matters here. better context is not more text. better context is the right instruction in the right layer.
next
- first fix instruction placement: AGENTS.md vs CLAUDE.md vs Cursor/Windsurf/Copilot
- understand the mechanics: how the plugins system works
- write your own repeatable workflow: how to write Claude Code skills
- choose the capability layer: best MCP servers
- see the terminal-side thesis: why Claude Code wins the terminal