Claude Skills vs Agents: When to Reach for Which

If you build on the Claude Agent SDK, two words follow you everywhere: skills and agents. On the surface they feel like the same idea - a way to hand Claude an extra ability. They are not the same thing, and reaching for the wrong one is the kind of quiet mistake that costs you a couple of days before you notice.

Here is the whole thing in one line: a skill is knowledge, an agent is a worker. That sentence carries most of the difference. The rest of this post is the part people actually trip on - and the single question I fall back on whenever I am not sure.

A skill is a folder

A Claude Skill is, almost literally, a folder. Inside it sits a SKILL.md file plus whatever scripts or reference files that knowledge needs to do its job.

• The model decides, on the fly, that the folder is relevant to your request and loads it into the current turn.
• It shapes how Claude answers - the format, the steps, the rules it follows.
• Then it exits with the turn. A skill lives for exactly one response.

Think of a skill as a cheat sheet Claude pulls off the shelf the moment it realises it needs it. A good example is a "brand voice" skill: your tone rules, a few do-and-don't examples, maybe a logo. You ask Claude to draft a post, it notices the skill is relevant, loads it, writes in your voice, and the folder leaves with the answer.

An agent is a subprocess

A Claude Agent is a separate Claude instance spun up for a scoped job. It gets its own context window, its own tool set, its own system prompt, and its own loop.

• It is spawned by you, the developer, or by a parent agent.
• It runs, does the work, returns a result, and exits.
• An agent lives until its goal is reached - that might be one step or fifty.

Picture an agent told to "migrate this test suite to the new framework." It reads the files, rewrites them, runs the tests, reads the failures, fixes them, and loops until the suite is green. That is the agent's entire life: one job, start to finish, then gone.

The real difference: who is in charge

This is the line that actually matters, and it is the one the diagrams usually skip.

• A skill is triggered by the model. Claude decides a folder is relevant and pulls it in. You never call it directly - you make it available and trust Claude to reach for it.
• An agent is spawned by the developer (or a parent agent). Something deliberately starts it for a specific job.

Skills are pulled. Agents are launched. If you find yourself wanting to control exactly when something runs, that is a strong hint you are looking at an agent.

How long each one lives

• A skill lives for one turn. It shapes a single response and disappears.
• An agent lives for one job. It persists across many steps, holding its own state, until the goal is done.

This lifetime gap is why the choice matters more than it looks. A skill cannot remember what happened two messages ago - it was not even loaded then. An agent can, because keeping state across steps is the whole point of it.

Two checks for when you are not sure

After enough wrong turns, I boiled it down to two quick diagnostics.

If your SKILL.md is trying to enforce execution order, you probably need an agent. The moment your skill reads "first do this, then that, and loop back if it fails," you are using a knowledge file to control flow. Skills are bad at that. Flow control is an agent's job.

If your agent's system prompt is just re-implementing your style guide, you probably need a skill. If a whole subprocess exists mainly to repeat your tone, formatting, and naming rules, you are paying for a worker to do something a folder of knowledge would do for free.

They work best together

Skills and agents are not rivals, and the strongest setups use both. A "refactor" agent can, mid-job, load your "house code style" skill so every file it touches comes out in your conventions. The agent owns the multi-step work - reading, editing, testing, looping. The skill owns the voice - how the output should look. Neither is trying to do the other's job, which is exactly why the combination holds up.

A quick decision table

What you have	Reach for
Knowledge that shapes one response	Skill
Behavior that spans many steps	Agent
Style, format, voice	Skill
Tools, retries, branching	Agent

So which are you building?

When you are still on the fence, ask one question: does this thing need to remember anything between steps?

If yes, it owns state - and the smallest unit that owns state is an agent. If no, if it just shapes a single answer, it is a skill. Knowledge that shapes one response is a skill. Behavior that carries state across steps is an agent. Get that one distinction right and the rest of the SDK stops feeling like a maze.