i have been using cursor skills for a while to turn repeated work into runbooks the agent can follow on demand. that pattern still works. what changed is that some tasks are not slow because the steps are hard. they are slow because the same review or audit has to run five times across five folders, five categories, or five doc areas, and a single agent does them sequentially.
parallel subagents fix that kind of problem. they do not replace skills. they wrap them.
if you already reorganized your .cursor directory for token efficiency, think of this post as the next decision. skills stay the canonical playbook. subagents decide when to run several copies of that playbook at once.
quick answer#
use a skill when one agent should follow one bounded workflow end to end, such as reviewing one file, scaffolding one model, or running one sanity check category you explicitly scoped.
use a parallel subagent when the same underlying skill applies to several independent units and wall-clock time matters. the parent agent dispatches one subagent per unit, each subagent gets its own context window, and the parent aggregates the results afterward.
the rule i use is if the units can run without reading each other’s partial output, parallelize. if they share one mutable target or one sequential decision chain, keep it in one agent with one skill.
who this is for#
- people who already use cursor skills and notice multi-folder audits taking forever
- teams with repeatable review or maintenance workflows split across layers, packages, or doc areas
- builders who want faster end-of-task verification without giving up human control over writes
why this matters#
a skill makes work repeatable. a parallel subagent makes repeatable work concurrent.
that distinction sounds small until you run a standards review across five model layers, a sanity check across five categories, or a documentation audit across five doc zones. one agent can do all of it correctly and still feel painfully slow, because each unit waits for the previous one to finish.
parallel subagents change the timing. wall-clock cost becomes closer to the slowest unit instead of the sum of all units. you still pay token cost across multiple agents, so this is not free. it is a trade. you spend more tokens to buy back waiting time on work you already trust enough to decompose.
definitions: skills vs subagents#
before choosing, it helps to know which artifact does what.
| artifact | lives in | job | typical trigger |
|---|---|---|---|
| skill | .cursor/skills/<name>/SKILL.md | step-by-step runbook for one workflow | parent agent loads it when the task matches the skill description |
| parallel subagent | .cursor/agents/<name>.md | orchestration wrapper that dispatches the same skill across independent units | parent agent launches subagents when scope spans multiple units |
skills answer “how do i do this task correctly?”
subagents answer “how do i run that task many times at once without losing control?”
neither one replaces rules. rules stay passive guardrails. skills and subagents are active workflows.
when to use a regular skill#
reach for the underlying skill directly when the scope is one unit or when the work is inherently serial.
good skill cases:
- review one sql file or one yml file
- scaffold one new model and its metadata
- run one documentation update for one page
- sanity-check one small change where formal multi-category review would be ceremony
- any task where the next step depends on the output of the previous step
skills are also the right place to keep the canonical checklist, references, done criteria, and acceptance language. the skill is the source of truth. the subagent should not duplicate that content. it should point to it.
if you are unsure whether the scope is truly one unit, start with the skill. parallel orchestration adds coordination overhead. only use it when the parallelization is obvious.
when to use a parallel subagent#
reach for a parallel subagent when all of these are true:
- the same skill applies to multiple units
- the units are independent enough to review or audit separately
- you want results aggregated into one report
- the task is substantial enough that serial execution takes too long
good parallel subagent cases:
- standards review across every layer in a data platform repo
- yml review across the same layers as the paired sql review
- end-of-task sanity checks split by category such as correctness, compatibility, edge cases, conventions, and overall review
- documentation drift audits split by doc area
- dependency audits split by surface such as runtime, packages, ci, and container base image
- entity sync work when several new backend entities need the same scaffolding pattern at once
bad parallel subagent cases:
- a one-line typo fix
- a single-file edit where you already know the answer
- a workflow that must mutate the same shared file from multiple angles at once
- anything where step two genuinely requires step one’s write to exist first
the last point matters. parallel subagents are for read-mostly or analyze-then-decide work. when multiple units need to edit the same shared config, the parent should collect findings first and apply shared writes serially afterward.
the pattern i use: one skill, one orchestrator, many workers#
my parallel setup has three layers.
layer 1: the underlying skill#
this is the real playbook. it contains the checklist, canonical references, output format, and done criteria for one unit of work.
examples in my repos include skills for sql standards review, yml standards review, sanity checks, documentation audits, and entity sync scaffolding. each one knows how to handle one scoped slice.
layer 2: the parallel subagent#
this file lives in .cursor/agents/ and does not replace the skill. it defines:
- the default unit breakdown, such as one subagent per model layer or one subagent per sanity category
- which underlying skill each worker should follow
- the output contract each worker must return
- when not to use parallel mode
naming helps. i use a -parallel suffix on orchestrator subagents so the choice is obvious in the catalog.
layer 3: shared orchestration mechanics#
i keep one small shared skill for dispatch rules every parallel wrapper follows:
- use the explicit scope from the user. if the scope is one unit, call the underlying skill directly and skip orchestration.
- dispatch one self-contained prompt per unit in a single parent message. each prompt should include paths, the canonical skill, the expected output format, and write boundaries.
- aggregate results in the parent. label failed or partial units clearly. retry a transient failure once if that is useful.
- apply changes only when authorized. keep shared-file writes serial in the parent. never let workers mutate git state on their own.
- run proportionate final verification once at the end. skip formal orchestration for trivial edits.
that shared layer keeps every parallel subagent consistent without copying the same coordination instructions into five different files.
how the parent should dispatch work#
the parent agent is the conductor, not another worker.
a good dispatch prompt for each unit includes:
- the exact scope for that unit only
- a link or name for the canonical skill to follow
- read-only vs write permission for that unit
- the response format you want back, such as pass or concern, file list, violation counts, or missing coverage
a bad dispatch prompt says “review everything” and hopes the subagent guesses the boundary.
i send all dispatches in one parent turn when possible so the units actually run concurrently. then i aggregate in a fixed order. for reviews, i surface correctness and compatibility findings before style nits. for audits, i surface missing files and contract breaks before commentary.
what should stay serial#
parallel subagents are not an excuse to let five agents edit the same shared file at once.
keep these in the parent:
- writes to shared source files used by multiple units
- git staging, commits, pushes, or merges
- choosing which findings become actual code changes
- final compile, lint, or check commands that validate the combined result
workers analyze. the parent decides and applies.
that boundary is why parallel mode works well for reviews, audits, and sanity checks, and why i still use a single skill for a straightforward write workflow unless the units truly touch different files with no overlap.
a practical decision table#
| situation | use |
|---|---|
| one file, one model, one doc page | underlying skill |
| trivial edit, docs-only change, formatting | no formal workflow, or a very small inline ask |
| same review repeated across independent folders | parallel subagent |
| end-of-task verification across multiple categories | parallel subagent |
| several new entities needing the same scaffold pattern | parallel subagent, with shared files updated serially in the parent |
| step b requires step a’s write to exist | single agent, single skill, serial steps |
| background merge-ready pr hygiene | cloud or babysit workflows, not this pattern |
how to build your first parallel subagent#
you do not need a perfect fleet on day one. this sequence worked for me.
1) stabilize the underlying skill first#
if the single-unit workflow is still fuzzy, parallelizing it will just produce five fuzzy answers faster. get the checklist, references, and output contract right in the skill before you wrap it.
2) identify real units of independence#
ask where the task naturally splits. model layers, doc areas, sanity categories, dependency surfaces, and service entities are all common unit boundaries. the split should be obvious enough that you can write one paragraph of scope per unit without overlap.
3) create the orchestrator file in .cursor/agents/#
frontmatter should answer when to use it and when not to use it. point to the underlying skill and the shared orchestration skill instead of restating both.
4) define the default scope table#
a small table in the subagent file beats prose. one row per unit, with the path or category and what the worker should return.
5) test on a medium-sized real change#
run the parallel subagent once at the end of a substantial change set, not on every keystroke. check whether aggregation is readable and whether any shared-file write would have collided if workers had been allowed to edit freely.
6) link it from your local cursor index#
add one row to your .cursor catalog so future sessions route correctly. “use the skill for one unit, use the parallel subagent for many” should be discoverable without remembering filenames.
how this fits with cursor’s /multitask direction#
cursor has been moving toward async subagents and better multitask orchestration in the product itself. the repo pattern i describe here is the durable part regardless of ui changes.
skills remain the canonical instructions. subagents remain explicit orchestration boundaries. the parent remains responsible for aggregation and shared writes. whether the platform dispatches workers through /multitask, the agents window, or a manual multi-launch in chat, the decision rule stays the same.
parallelize independent units. keep shared mutation serial.
closing#
skills taught my agents how to do repeatable work well. parallel subagents taught them when to do several copies of that work at the same time without turning one conversation into a queue.
default to the skill. escalate to a parallel subagent when the scope spans independent units and the wait time starts to hurt. keep orchestration rules in one shared place, keep workers read-mostly, and let the parent own the merge.
that is the split that has saved me the most time on reviews and end-of-task checks without giving up control.
faq#
should i duplicate my skill checklist inside the subagent?#
no. the skill stays canonical. the subagent should only define unit boundaries, dispatch instructions, aggregation order, and when to skip parallel mode.
do parallel subagents cost more?#
usually yes, because several agents run at once and each carries its own context. you are trading token spend for wall-clock time. use them on substantial tasks where that trade is worth it.
can i parallelize writes?#
only when units touch completely separate files with no shared contract surface. even then, i prefer read-first parallel analysis and serial application in the parent. it is slower to apply than to analyze, but much safer.
what if one subagent fails?#
the parent should mark that unit failed or partial, continue aggregating the rest, and retry once if the failure looks transient. do not silently treat a missing unit as a clean pass.
when should i skip parallel mode entirely?#
skip it for trivial edits, single-file work, docs-only formatting, and any task where formal verification would be more expensive than the change itself. parallel orchestration is for substantial scope, not habit.
