---
name: claude-subagents
description: Spin up a short-lived headless `claude` sub-instance to grind through a well-scoped, mechanical batch (bulk relabeling, a repetitive find/replace, a mechanical migration) instead of burning your own context on it inline. Use this when a task has a clear, describable recipe and is either big enough to eat your context or long enough that you'd rather not babysit it. Not for judgement-heavy work, anything needing operator back-and-forth, or a task whose blast radius you can't bound up front.
---

# Ephemeral Sub-Agents

A sub-instance you spawn inherits the same filesystem and credentials you
have. This is a first-class tool for offloading a bounded, mechanical
batch.

## When to use it

- **Yes:** mechanical batches with a clear recipe (relabel N issues,
  rewrite a call-site pattern, migrate a config field), especially when
  the batch would eat your context or take long enough that you'd
  rather not babysit it turn-by-turn.
- **No:** judgement-heavy work, anything needing back-and-forth with a
  human, or a task whose blast radius you can't bound up front.

## The `subagent` MCP tools

Your container's `subagent` MCP server (`hive-subagent-daemon`) runs this
skill's recipe for you:

```
start(name, prompt_file, model?, effort?, trigger?)
continue(name, prompt, model?, effort?)
status(name)
interrupt(name)
```

`start` and `continue` return once the turn is under way, not once it
finishes — a completion lands as a todo (`get_loose_ends`), same as any
other producer. `continue` takes the extra moment to confirm the resume
actually attached, so a `continue` naming a session that isn't there
fails the tool call outright instead of looking like it worked; the error
says which directory it searched, which is usually the fix (pass `dir`).
`dir` defaults to your work dir, `/agents/<you>/work`, which has no
`AGENTS.md` above it, so a subagent started there does not load yours
(until that directory exists, the daemon's cwd is used).
Use `status` for a
zero-cost "is it still going" check — for a running subagent it also
reports how long since that turn last produced output, so a few seconds
means it's working and an age climbing into the minutes means it's
wedged and worth an `interrupt`. Reach for `continue` only once you
actually have a new instruction for it, since that spends a turn.
`interrupt` genuinely stops a running turn, with SIGINT so claude stops
the commands it started; `status` says `stopping` until claude has exited.

Model choice, prompt hygiene, splitting big batches, verify-then-report —
everything else in this skill — applies exactly the same whether you're
calling the tool or thinking through the recipe by hand.

## Model choice

Pick the cheapest model that can do the job, and lean toward the cheap end
more readily than you might for your own work — a subagent is throwaway
compute, not a peer you're rationing. Haiku in particular is cheap enough
that you don't need to be precious about spinning one up: for a mechanical,
well-scoped batch (the shape this skill is for), reach for it liberally
rather than defaulting to a bigger model "to be safe." On a small context
Haiku costs next to nothing up to `high` effort, so there's no cost reason
to cap its effort at `medium` by reflex. Effort is a real lever on Haiku
though: at `max` it behaves like a slightly weaker Sonnet at about the cost
of Sonnet on `low`, so `max` on Haiku buys nothing over Sonnet on `low`.
Stay at `high` or below, and move to a stronger model when the batch needs
more judgement (see Pitfalls below). When you do pick Sonnet, pass `low`
yourself: its default effort is `high`, a big price bump.

This isn't "always pick the smallest model regardless of task" — a batch
that actually needs judgement calls still wants a stronger model (see
Pitfalls below). It's "don't under-use Haiku out of habit-driven caution
when the task is mechanical enough for the skill to apply at all."

## Effort

An omitted `effort` defaults to `medium` here — cheaper than claude's own
model default (`high` on most models), a deliberate cost-conscious choice
for subagent work specifically, same spirit as the model-choice guidance
above. Raise it explicitly when the task is complex enough to actually
need deeper reasoning, not as a reflex. **Exception: on Haiku with a small
context, cost stays near zero up to `high`.** See Model choice above: skip this
default-medium caution there, but keep `max` for a stronger model.

Anthropic's own levels (per current Claude Code docs — names/availability
are model-dependent, check before relying on an exact list): `low`,
`medium`, `high`, `xhigh`, `max`. Each trades token spend for capability:

- **`low`** — short, scoped, latency-sensitive tasks that aren't
  intelligence-sensitive.
- **`medium`** — cost-sensitive work that can trade off some intelligence.
  This skill's default for subagent work.
- **`high`** — balances token usage and intelligence; Anthropic's own
  recommended default for most _interactive_ coding tasks (not what this
  skill defaults subagents to — see above).
- **`xhigh`** — deeper reasoning at higher token spend.
- **`max`** — demanding tasks only; diminishing returns and overthinking
  are a real risk, per Anthropic's own guidance — don't reach for it as a
  default.

Anthropic's guidance: treat effort as a general preference, not a
task-by-task dial — raise it if a subagent keeps skipping files, not
running tests, or not double-checking its own work; lower it for routine
work where quality hasn't suffered. Changing effort between turns on the
_same_ session invalidates prompt caching, so pick a level for the whole
session rather than flipping it turn-to-turn.

## Prompt hygiene - this is where batches succeed or fail

- **Concrete constants, not "figure it out":** exact ids, field names,
  option values, endpoints.
- **Critical ordering rules, spelled out** - the sub-agent won't infer
  invariants you don't state.
- **Explicit scope + exemptions**, plus a fallback rule for ambiguous
  cases: "leave it as-is where genuinely unclear; do not guess."
- **Ask for a report file** - per-item results + anything skipped and
  why, so you can verify without re-deriving.
- **Tune on ONE item first**, eyeball the result, fix the prompt, _then_
  turn it loose on the full batch. A prompt bug replicated across 100
  items is 100 cleanups.

## Split a big independent batch across parallel subagents

One subagent is a sequential worker — a 50-item batch takes roughly 50
items' worth of wall-clock even though nothing about the recipe forces
serialization. If the items are independent (each one touches its own
file/issue/row, nothing depends on another item's result) and the batch
is big enough that wall-clock matters, chunk it across N subagents
running at once instead of handing the whole thing to one.

- **Split by natural boundaries**, not an arbitrary item count — one
  subagent per file, per directory, per module, per label, whatever
  grouping keeps each worker's slice self-contained. A worker that has
  to coordinate with another worker mid-task isn't actually independent
  work; re-scope the split until it is.
- **Isolate each worker's writes.** For a git-based batch, give each
  worker its own `git worktree` (own working directory, own branch, same
  underlying repo — cheap, no full reclone) so N workers editing
  different files never race on the same working tree or index. For a
  non-git batch (issue relabeling, API calls), independent items don't
  need filesystem isolation at all — just launch N in parallel.
- **Launch all N and don't babysit any single one** — same as the
  one-subagent case, just N `start` calls instead of one. Check on them
  as a batch, not by polling each individually in a loop.
- **Mind the container's memory cap before picking N.** Your whole
  container shares one `MemoryMax` (a few GB by default) with every
  subagent you spawn _and_ your own process. A `claude` process plus its
  MCP servers can hold several hundred MB to ~1GB depending on the task;
  spawning a dozen at once on a small container doesn't just slow
  things down, it can OOM the whole container — taking your own
  in-flight turn down with it, not just the subagents. Rule of thumb:
  **2-4 concurrent workers** on a default-sized container; check
  `free -h` (or ask whoever owns the container's config for its
  `MemoryMax`) before going higher, and chunk a bigger batch into
  successive waves of that size rather than firing everything at once.
- **You own the merge.** Once all N report done, review + verify each
  worker's slice (same "don't trust the self-report blind" rule as
  below), then combine — for a git-based split, that's you merging N
  branches (or cherry-picking) into one, not each worker pushing/PRing
  its own slice.

Skip this for a batch small enough to finish in a couple minutes single-
threaded — the coordination overhead isn't worth it below that size.

## Resume for follow-ups

`continue` reuses the same session, so the sub-agent keeps every constant
and gotcha it already discovered instead of re-learning the surface from
a cold prompt. Reach for `start` under a new name only for a genuinely
unrelated task.

## Verify, then report

On completion: read the report file, spot-check a handful of results
yourself (don't trust the self-report blind), then summarize. Surface
anything the sub-agent left ambiguous or exempted for a human call.

## A failed command is the result, not a gap to fill

Tell every subagent, in the prompt: if a command FAILS (non-zero exit, an
error like "no repo specified", empty output where output was expected),
STOP and report the failed command and its output verbatim as the result.
No workaround, no inference, no plausible fill-in. An invented answer is
worse than none, because you will act on it.

This happens: a subagent spawned in a scratch directory with no git
`origin` remote could not run its forge CLI, mentioned that in one line,
then filled the report with invented issue numbers and a confident
conclusion that was the opposite of the truth. The report looked cleaner
than a real one. So spawn tool-using subagents where their tools work (a
real checkout, or pass the target explicitly), and spot-check one cheap
fact from every report against the real system.

## Pitfalls (all observed in practice)

- Using a model bigger than yourself → paying premium cost for
  mechanical work that didn't need it.
- Skipping the one-item tuning pass → a systematic mistake smeared
  across the whole batch.
- `start`-ing fresh instead of `continue`-ing for a follow-up → throws
  away all the context the first pass earned.
- Baking an unverified assumption into the recipe - if a quick check
  suggests something "isn't possible" or "doesn't exist," confirm it
  before writing that conclusion into the prompt; a wrong assumption
  gets replicated across the whole batch.
- Handing a big independent batch to one subagent instead of splitting
  it across several in parallel - a 50-item sequential run burns wall-
  clock the split-by-worktree approach above would've avoided for free.