lockstep
6 min readNaman Jain

Claude Code workflows: what they are and when to use one

Claude Code dynamic workflows explained: how they differ from skills, subagents, and agent teams, how to run and save one, and what they cost.

You ask Claude Code to check every API route for missing auth checks. Forty files in, the conversation is half full of file contents, Claude has lost track of which routes it covered, and you're scrolling to find the findings. The task is fine for an agent. It's too big for one conversation.

That's the job Claude Code workflows were built for. This guide explains them from Anthropic's dynamic workflows documentation, checked on 16 November 2026.

What a workflow is

A dynamic workflow is a JavaScript script that orchestrates many subagents at once. Claude writes the script for your task; a runtime executes it in the background while your session stays responsive. When it finishes, you get one result instead of a turn-by-turn transcript.

Workflows are available on all paid plans, through the Anthropic API, and on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry. On Pro, turn them on in /config. They work in the CLI, desktop app, IDE extensions, claude -p, and the Agent SDK.

Workflows vs skills vs subagents vs agent teams

All four can run a multi-step task. The difference is who holds the plan:

SubagentsSkillsAgent teamsWorkflows
What it isA worker Claude spawnsInstructions Claude followsA lead agent supervising peer sessionsA script the runtime runs
Who decides the next stepClaudeClaudeThe lead agentThe script
Where results liveClaude's contextClaude's contextA shared task listScript variables
ScaleA few tasks per turnSame as subagentsA handful of peersDozens to hundreds of agents
If interruptedRestarts the turnRestarts the turnTeammates keep runningResumable in the same session

The key shift: with the first three, Claude orchestrates turn by turn and every result lands in a context window. With a workflow, the loop, branching, and intermediate results live in the script, so Claude's context only holds the final answer.

Use a skill for a procedure you want Claude to follow. Use a workflow when the work fans out across many files or sources, or when you want the orchestration itself saved and rerun. More on the others in CLAUDE.md vs skills vs hooks vs subagents and Claude Code agent teams.

Running one

Three ways in:

  1. The built-in one: /deep-research <question> searches the web from several angles, cross-checks the sources, and returns a cited report with unsupported claims filtered out.
  2. Ask in a prompt: include ultracode, as in ultracode: audit every endpoint under src/routes/ for missing auth checks, or say "use a workflow."
  3. Let Claude decide: /effort ultracode makes Claude plan a workflow for every substantive task in the session. That uses more tokens per request; turn it off with /effort ultracode off.

Before a run starts, Claude Code can ask you to approve its planned phases; when it asks depends on your permission mode. Watch progress with /workflows, which shows each phase, its agents, and each agent's token use.

The ultracode keyword only counts in a prompt you type. It doesn't trigger from a -p prompt, a scheduled task, or text relayed from a pull request comment.

Good tasks for a workflow

From Anthropic's examples:

  • Audit many files for the same issue, such as missing auth checks
  • Migrate many files in parallel, such as a 500-file API change
  • Keep fixing until a check passes
  • Review every changed file and write one summary
  • Research across many sources, with claims cross-checked

Workflows can also apply a quality pattern, such as having independent agents review each other's findings before reporting them. That's harder to get from a single pass.

Saving and sharing

In /workflows, select a run and press s:

  • .claude/workflows/ in the project, shared with everyone who clones the repository
  • ~/.claude/workflows/, for you across all projects

It then runs as /name. A saved script looks like this:

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

agent() spawns one subagent, pipeline() runs one per item, and parallel() runs several at once. To share across repositories, put workflows in a plugin.

Limits and cost

  • No input mid-run. For sign-off between stages, run each stage as its own workflow.
  • The script can't touch files or run commands itself. Its agents do, under the same permission checks and sandboxing as any tool call.
  • Up to 16 agents at once by default, and 1,000 agents per run.
  • Cost. A run can use far more tokens than the same task in conversation. Claude Code flags runs above 25 agents or a projected 1.5 million tokens with a Large workflow warning. Try a small slice first.
  • Size guideline. /config sets how many agents Claude aims for: small (under 5), medium (under 10, the default), or large (under 50).

Admins can turn workflows off with "disableWorkflows": true in managed settings.

What every agent in a run should know

A workflow that migrates 500 files runs hundreds of agents, each starting fresh. If the team decided last month to keep the v1 response format for one more release, every one of those agents needs to know, or the migration is fast and wrong. Put rules that apply to the whole run in CLAUDE.md, and put the task's constraints in the prompt that starts it.

Where Lockstep fits

Lockstep briefs Claude Code sessions on the team's approved decisions that apply to the work, captured from PRDs, Slack, and pull requests and approved by their owners. For a large run, lockstep brief prints the relevant decisions so you can include them in the prompt that starts the workflow.

See how it works.

Sources checked 16 November 2026

For subagent basics, see Claude Code subagents: 5 examples. For the token side, see how to reduce Claude Code token usage. For skills, see the Agent Skills open standard. For running Claude Code from your own code, see Claude Agent SDK vs Claude Code. For the two other ways to run many agents, see Claude Code subagents vs agent teams.

Frequently asked questions

What is a Claude Code workflow?
A dynamic workflow is a JavaScript script that orchestrates many subagents at once. Claude writes the script for the task you describe, a runtime executes it in the background, and your session stays free. You get one result at the end instead of a long transcript.
What is the difference between a Claude Code workflow and a skill?
A skill is instructions Claude follows, deciding each step itself, with results going into its context window. A workflow is a script the runtime executes: the script decides what runs next, holds intermediate results in variables, and can run dozens to hundreds of agents. Skills fit procedures; workflows fit large fan-out work.
How do I run a workflow in Claude Code?
Run the built-in /deep-research with a question, include the keyword ultracode in a prompt, or ask in your own words, such as 'use a workflow'. Watch progress with /workflows. Setting /effort ultracode makes Claude plan a workflow for every substantive task in the session.
Can I save and share a Claude Code workflow?
Yes. In /workflows, select a run and press s. Save to .claude/workflows/ to share it with everyone who clones the repository, or to ~/.claude/workflows/ for yourself. It then runs as /name. To share across repositories, put it in a plugin.
Are Claude Code workflows expensive?
They can be. A run spawns many agents and uses more tokens than doing the task in conversation. Claude Code shows a Large workflow warning above 25 agents or a projected 1.5 million tokens. Test on a small slice first, and use a smaller model for stages that don't need the strongest one.

Keep reading