Sub-agent or skill or MCP tool, which one do you pick when

Three ways to extend Claude Code, all of them in the docs and all of them sounding useful. Sub-agent, skill, MCP tool. At the start of the build-out of our fleet I built all three in the wrong order. First an MCP tool for something that should have been a skill, then a sub-agent for something that belonged in an MCP tool. Two days of migration later it was clear that the decision problem is bigger than the build problem. Here is the guide I would have needed back then.

1. Understand what the three actually are

A skill is a markdown file with frontmatter. You put it at ~/.claude/skills/<name>/SKILL.md. On every prompt Claude scans all skill descriptions and decides on its own whether to load one. If it does, the body comes in as context. No code, no API, just text that tells Claude how to do something.

A sub-agent is also a markdown file, but you call it explicitly. Via a task call, via a slash command, or because you say in the prompt "delegate that to the reviewer agent". It gets its own context, its own mini conversation, and hands you back a result at the end.

An MCP tool is code. Real code, in TypeScript or Python, running as a server. Claude calls the tool over JSON-RPC, gets structured data back, and can keep working with the result. Tools can run DB queries, fire off HTTP calls, write files, everything code can do.

Three different layers. A skill is knowledge. A sub-agent is workflow. An MCP tool is capability. In practice that gets mixed up constantly, which is why the rest of this playbook exists.

2. Decision question number one, do you need data from outside

That is the most important question and it comes first. If the solution has to read or write something external, it is an MCP tool. Not negotiable. Skills cannot do it, and sub-agents cannot do it directly either. Both only have access to what Claude Code itself can do (Read, Write, Bash, WebFetch and so on).

A concrete example from our fleet. We wanted Claude to be able to read our Postgres DB for memory lookups. The first attempt was a skill that said "when someone asks about memory, run a psql bash command". That worked but it was fragile. Bash escaping hell, no schema knowledge, nothing structured. After a week we rebuilt it as an MCP tool that does real SQL and returns typed results. The skill is deleted.

Rule of thumb: if the action needs an API, a DB, a service or a filesystem path that Claude cannot reliably find on its own, MCP tool.

3. Decision question number two, is it knowledge or workflow

If no external data is needed, we keep going. Knowledge or workflow.

Knowledge means: "when topic X comes up, also think about Y and Z". Example: "when the user wants to write Postgres migrations, remind them about backups first and about prisma migrate dev --create-only instead of applying directly". That is a skill. Markdown text, triggered through the description, Claude decides on its own.

Workflow means: "run step 1, then 2, then 3, and give me Y back at the end". That is a sub-agent. Defined input, defined output, a clear sequence in the middle.

If you ask yourself what you are about to build and you can phrase it as "when X, then remind about Y", it is a skill. If you phrase it as "does this, then that, and this comes out at the end", it is a sub-agent. If you cannot put it into words at all because all you need is data, MCP tool.

4. Decision question number three, how often does this happen

Skills trigger on every prompt that matches the frontmatter. That is good when you need it often. Bad when it happens twice a month, because then the skill body sits around as latent context and costs tokens for nothing.

Sub-agents only trigger when they are called explicitly. That is perfect for "I do this every Tuesday" or "I call this on every PR". You type the name and it runs.

MCP tools get registered in the tool list and Claude picks out what it needs. Scales well up to a lot of tools, but with a small list you barely notice a difference.

A concrete number from our practice. A "memory query" skill triggered on roughly 40 percent of our prompts (we talk about memory a lot). That was too much, the context filled up. Migrated to an MCP tool that only gets called on an explicit search. Today it is four times an hour instead of 40 times. Tokens halved.

5. Decision question number four, can it work without structural knowledge

Skills take free text in and give free text out. Sub-agents too. Both are conversational at heart. If the answer is "yes, read that, think about it, formulate a result", that is enough.

But if the answer is "read the user with ID 42 out of table X, fetch their last ten orders, sum them up and return JSON", then it is clearly an MCP tool. Structure and types.

Rule of thumb: if the caller (Claude or another tool) needs the result as parsable JSON, MCP tool. If a markdown block is enough, skill or sub-agent.

6. The trap, building a skill that is really a sub-agent

That was my first big mistake. I had a skill with a 200 line body that described exactly one workflow. "When the user asks for blog post ideas, do step 1, then step 2, then step 3". Classic sub-agent, built wrong.

It blows up once you use it. Skills trigger automatically, so the body sometimes came in during contexts where it did not belong. Performance suffered. A sub-agent solved it, because it only runs when it is called explicitly.

Symptom that you are doing this: your skill has Step-1, Step-2, Step-3 headlines. Then it is a sub-agent. Migrate.

7. The trap, building a sub-agent that is really an MCP tool

That was mistake number two. A sub-agent that called psql through the Bash tool and was supposed to parse the result. That worked for simple queries and failed on anything with joins or quotation marks. Migrated to an MCP tool with a real Prisma client. Four hours of migration, after that everything ran.

Symptom that you are doing this: your sub-agent uses a lot of Bash in the body, a lot of pattern matching on string output, and keeps falling over on edge cases. Then the logic core belongs in an MCP tool.

8. The rare anti-trap, an MCP tool that should be a skill

Rare, but it exists. You have an MCP server with a tool that simply returns a markdown text with instructions. "Tool 'review-checklist' returns: 1. Check imports, 2. Check tests, 3. Check types". That is a skill. Code for it is overhead.

Symptom: your tool makes no API call, no DB query, no file IO. It only returns constants or templates. Delete it, create it again as a skill.

9. Examples from real fleet setups

Four concrete cases from the last few weeks, so you can see the patterns.

Case A. "When the user talks about pricing, remind them about the Stripe live mode trap." Skill. A pure knowledge rule, no workflow, no data.

Case B. "Write me a release note entry out of this PR." Sub-agent. Clear input (PR URL), clear output (markdown block), a defined workflow in the middle.

Case C. "Tell me how many pageviews the Academy had yesterday." MCP tool. Needs an Umami API call, needs auth, returns a structured number.

Case D. "Check whether this idea lines up with our strategy." Sub-agent with MCP tools that it calls. Multi-layer. Sub-agent for the workflow, MCP tools for the data access (read strategy memory, check decisions).

10. Order for solo founders, what you learn first

If all you have right now is the weekend, this is the order.

Build skills first. Cheapest, fastest learning effect, no code. Two or three skills you need often (code review style, blog post style, Postgres caution). You then understand how triggers work and where the limits are.

Then a sub-agent. Take a workflow you do every week. Ticket to PR title, or voice note to tasks. Half an hour of building, immediate payoff.

Only then an MCP tool. Once you bump into the fact that you need real data, the question answers itself. Then the TypeScript setup effort is worth it. Not before.

Three ways, clearly divided up. If you have that in your head, you save the migration days that I needed.

If you want to build this right now, start with the playbook Your first own skill in 30 minutes. When the sub-agent is up next, look at Your first sub-agent in 30 minutes. For the MCP tool, Your first MCP server in 90 minutes.