Skills vs MCP servers vs subagents: the architectural map for builders

If you've spent any time in Claude Code's documentation lately, you've seen these terms thrown around: Skills, MCP servers, subagents, slash commands, CLAUDE.md. They overlap. They sound similar. The official docs explain each one on its own but rarely tell you which one to reach for when.

That's the gap this piece fills. We'll walk through what each one is, what it's actually for, and — more usefully — when not to use it. By the end you should know which one fits the problem in front of you.

If you haven't read the cluster hub yet, start with What Claude Skills actually are. This piece picks up from there.

The five things builders confuse

Here's the cast of characters, ranked roughly by how often you'll reach for them.

CLAUDE.md — A plain text file at the top of your project. Claude reads it at the start of every conversation. Stays in Claude's attention the whole time. Use it for facts about your project that Claude needs to know constantly — your conventions, your codebase, things to avoid.

Skills — Reusable workflows stored as folders inside your project. Claude only loads them when you ask for something they apply to. Use them for tasks you repeat — playbooks, brand voice rules, deploy checklists.

MCP servers — Connections to other software you use: Slack, Linear, GitHub, your database, internal APIs. They give Claude the ability to do things in those systems. They're not instructions; they're plumbing.

Subagents — A separate Claude that you dispatch to do a task in its own private workspace. It does the work, comes back with the result, and you never see the messy middle. Useful for verbose research where you only want the conclusion.

Slash commands — The old version of Skills. Anthropic basically replaced them. If you see documentation about creating custom slash commands, that's old guidance. Ignore it.

That's five concepts. Most builders only need three of them: CLAUDE.md, Skills, and (sometimes) MCP servers. Subagents are advanced; defer them until you need them. Slash commands are legacy; ignore them.

What each one is actually for

The fastest way to lock in the mental model is the question each one answers.

CLAUDE.md answers: "What does Claude need to know about this project, every single time?"

It's the project's institutional memory. Naming conventions. Where to put new files. Which patterns to avoid. Why the database has that weird denormalisation. If a new contributor would need to know it on day one, it goes in CLAUDE.md.

Skills answer: "What workflow do I keep re-explaining to Claude?"

Look at your last twenty Claude sessions. Find the workflow you've described more than twice. That's a skill. The deploy checklist. The code review heuristics. The way your team writes commit messages. The brand voice rules. Anything procedural you keep typing belongs in a skill.

MCP servers answer: "What external system does Claude need to read from or write to?"

Slack, Linear, GitHub, your database, an internal API, a SaaS dashboard. Anywhere Claude needs to leave its sandbox and talk to another piece of software, that's an MCP server.

Subagents answer: "Will this task produce a lot of output I don't need to keep in context?"

Research tasks. Long codebase exploration. Multi-step investigations. Anything where the work is messy and verbose but the answer is short. Dispatch a subagent, let it do its thing in isolation, get the clean answer back.

When not to use each one

The flip side matters more.

Don't put workflow instructions in CLAUDE.md. It loads in every session. Workflows you only need sometimes shouldn't pay that token cost. They go in Skills.

Don't make a Skill for every prompt you run twice. Skills carry overhead — naming, descriptions, file structure. If you're going to use the prompt three more times in your life, just type it. Skills earn their place when the workflow shows up weekly.

Don't use an MCP server when a script would do. If Claude needs to run a one-off SQL query, you don't need a Postgres MCP server — Claude can write SQL and you can run it. MCP servers are for recurring connections you want to keep clean.

Don't dispatch a subagent for a task you'll need to extend. Subagents return a snapshot, not a session. If you'll want to ask follow-up questions about the work, keep it in the main thread.

Where it gets fuzzy: overlap zones

The official docs imply clean boundaries. In practice there are three zones where two concepts can both work, and the choice is judgement.

Zone 1: Skill vs CLAUDE.md

You have a piece of project context. Does it go in CLAUDE.md (always loaded) or a Skill (loaded when triggered)?

Rule of thumb: if Claude needs the information to answer the next message — every next message — it's CLAUDE.md. If Claude only needs it when working on a specific kind of task, it's a Skill.

Concrete example: "Our codebase uses TypeScript strict mode" → CLAUDE.md. Claude needs to know that for any code work. "When deploying, run the staging smoke tests first" → Skill. Only relevant when deploying.

Zone 2: Skill vs subagent

Both encapsulate work. Both can be invoked from a main conversation. When does each fit?

Rule of thumb: Skills run inline in your main context. Subagents run in isolation. If the work produces output you'll want to reference, build on, or follow up about, it's a skill. If the work is exploratory and you just want the conclusion, it's a subagent.

Concrete example: "Write a SQL query for X" → skill. The query becomes part of the conversation. "Explore the codebase and tell me which files handle authentication" → subagent. The exploration is verbose; you only want the list.

Zone 3: MCP server vs Skill that calls a script

You need Claude to interact with an external system. You can either set up an MCP server for it, or write a skill that runs a CLI tool or script.

Rule of thumb: MCP servers are for stable, structured access to systems with real authentication and rate limits. Scripts inside skills are for one-off integrations or local tools. If five teams in your company need the same access, build an MCP server. If only you need it, a skill with a script is fine.

Concrete example: "Pull issues from Linear" → MCP server. Linear has an API, real auth, multiple users will want this. "Run our internal deploy CLI tool" → skill that calls the tool. Local, idiosyncratic, not worth the MCP overhead.

A real decision tree

When you're staring at a workflow and wondering where it belongs, ask these in order:

1. Does Claude need this knowledge in every conversation in this project?

Yes → CLAUDE.md. Stop. Done.

No → continue.

2. Does this require connecting to an external system?

Yes → you'll need an MCP server (or a script inside a skill). Continue to step 3 to figure out which.

No → continue.

3. Is this a workflow you repeat across sessions?

Yes, often (weekly+) → Skill.

Yes, but rarely → just include it in the prompt when it comes up.

No, this is a one-off → just type it.

4. Will the task produce verbose output you don't need to keep?

Yes → subagent.

No → stay in the main thread.

A workflow can hit multiple branches. A "weekly sprint status update" might need:

• An MCP server to fetch issues from Linear
• A skill that says "when the user asks for sprint status, query the relevant Linear views and summarise into our standard template"
• CLAUDE.md noting "we use Linear, not Jira, and the sprint cycle is two weeks"

Three of the four mechanisms, working together. That's normal.

Worked example: how we'd build code review

To make this concrete, here's how we'd architect AI-assisted code review for a real engineering team.

CLAUDE.md holds the project's coding standards: language version, testing approach, naming conventions, the patterns the team avoids. Claude reads this every session.

A code-review skill captures the team's review heuristics: the kinds of issues to look for first, how to structure the review, the tone for comments. Triggered when someone asks for a review.

A GitHub MCP server gives Claude access to read PRs, fetch the diff, leave comments. Without it, Claude can't actually read your PR.

A subagent could be dispatched for the heavy work — read all the changed files, walk the call graph, identify the riskiest changes — returning a single review report rather than cluttering the main conversation with file-by-file analysis.

A team running all four pieces well gets code review that actually saves time. A team that tries to put everything in CLAUDE.md gets a 30k-token system prompt that costs money on every conversation. A team that skips the GitHub MCP server has to manually paste diffs. A team that puts review heuristics directly in the prompt re-explains them every PR.

What you don't need

Most builders we've talked to over-build their setup. They install eight MCP servers they barely use, write twelve skills that overlap with each other, and end up with a fragmented stack that does less than a clean three-piece setup.

You don't need an MCP server for everything. Claude can run shell commands. If a task is one-off or local, that's enough.

You don't need a skill for every workflow. Many "workflows" are just one-paragraph prompts. Type them. Skills earn their place by repetition.

You don't need subagents. They're an advanced pattern that helps with verbosity at scale. If you're not running into context-window pressure, defer them.

You don't need CLAUDE.md to be exhaustive. It loads on every session. Every line costs tokens forever. Keep it tight: the things Claude actually needs every conversation.

The goal is not maximum surface area. The goal is the smallest set of mechanisms that makes your work reliably faster. For most teams, that's CLAUDE.md plus three to five skills plus one or two MCP servers. Add more only when you feel the gap.

The summary table

If you only remember one thing from this piece, make it this:

| You need... | Use | |---|---| | Information Claude needs every session | CLAUDE.md | | A workflow you repeat | Skill | | Connection to an external system | MCP server | | Heavy task with verbose output | Subagent |

Everything else is detail.

The detail matters when you're shipping. The framework is what gets you there.