Agent vs Workflow in Claude Code: When to Use Which

People overcomplicate this. One question tells you which to build: can you write the exact steps out ahead of time, or does the next move depend on what Claude finds along the way?

If you can write the steps out and they’d run the same way every time, you want a workflow. If the steps change based on what it discovers, you want an agent.

Workflow = recipe

You wrote the steps down. Anyone can run it and get the same result every time. It follows the path you set.

Agent = chef

You hand over a goal, like "make something great with what’s in the fridge," and it decides the steps for itself based on what it finds.

Here’s the trap: people reach for the chef when a recipe would have been cheaper and more reliable. When the steps are known, you don’t need something to think. You need something to execute.

A workflow is a path you decide once and lock in. Same steps, same order, every run. In Claude Code that’s a skill you run with a slash command: a file at .claude/skills/<name>/SKILL.md that lists the steps, so typing /<name> runs the whole thing. Add disable-model-invocation: true to its frontmatter and it only runs when you type the command. Older .claude/commands/<name>.md files still work the same way.

The Tell

You can write down every step before you start, and nothing about the task changes based on what Claude finds.

Great workflow jobs

Turn one video script into a caption, an email and three posts, the same pipeline every time
Build your weekly numbers report in your exact format from the same sources
Turn raw meeting notes into a clean summary plus action items
Take a finished blog post and format, tag and publish it the same way
Run every new client through your standard onboarding sequence

Why It Wins

Predictable, cheap and fast. You’re paying Claude to run a path you mapped once instead of reasoning at every step. For anything repetitive, that’s what you want.

An agent is a specialist you hand a goal, and it figures out its own steps. In Claude Code that’s a subagent: a file at .claude/agents/<name>.md that runs in its own context window with its own instructions and tools, then hands a summary back to your main chat. That keeps your main conversation clean.

The Tell

You can’t write step three until you see what step two turns up. The task needs judgment.

Great agent jobs

"Research what my top competitor changed this month." It has no idea what it’ll find until it looks.
"Look at my landing page and tell me what’s hurting sales." What it finds decides the next move.
"Go through my inbox and surface what needs me." Every inbox is different.
"Figure out why my ad costs jumped last month." It’s an investigation, not a checklist.
"Review this draft and flag anything weak or confusing." Real judgment, no fixed steps.

The easiest way to try one: say "use a subagent to..." on a task. To make sure a specific one runs, type @ and pick it from the list.

The Tradeoff

More powerful, less predictable and more expensive, because it’s reasoning at every turn. Subagent work still counts toward your usage limits. Worth it when the task truly needs to think.

Build a workflow when

You can write the steps out up front
The output should look the same every run
The task is repetitive
You want it cheap, fast and predictable

Build an agent when

The next step depends on what it finds
There’s real judgment involved
You can’t map the path up front
You’re handing off a goal instead of a script

Anthropic draws the same line in Building Effective Agents: workflows run on predefined paths, and agents direct their own process. Their advice matches mine too. Start with the simplest thing that works, and only add an agent when the task needs to think for itself.

Paste this into Claude Code in your project folder. It runs the one-question test on your task, then writes the skill or the subagent file for you.

Agent Or Workflow Builder

You are helping me set up a repeatable task in Claude Code. Your job is to decide whether it should be a WORKFLOW (a skill I run with a slash command) or an AGENT (a subagent), and then build the right file. The task: [describe the job in 2 to 3 sentences, e.g. "every Monday, turn my last 7 days of sales CSVs into a one-page numbers report"] What I give it each time: [files, links, folders or notes it starts from] What "done" looks like: [the exact output, format and where it should be saved] Steps: 1. Ask me up to 3 questions if anything above is unclear. Wait for my answers. 2. Apply this test: can every step be written down before the task starts, and would it run the same way each time? If yes, it is a workflow. If the next step depends on what you find along the way, it is an agent. Tell me which one in one line and why. 3. If it is a WORKFLOW: create .claude/skills/[name]/SKILL.md with name and description in the frontmatter, add disable-model-invocation: true so it only runs when I type /[name], then list the numbered steps, the inputs and the exact output format. 4. If it is an AGENT: create .claude/agents/[name].md with name, description and only the tools it needs, then write a system prompt that states the goal, what good looks like, what it must never do, and what to report back to me when it finishes. 5. Show me the file, then tell me the exact thing to type to run it. Rules: - Use lowercase-hyphen names. - Don't give the file more tools or permissions than the task needs. - If the task is half fixed and half judgment, build a workflow for the fixed part and say where a subagent should take over. - Don't run the task yet. Just build it and show me.

Agent OrWorkflow?

Agent Or
Workflow?