--- 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?, trigger?) continue(name, prompt, model?) status(name) interrupt(name, force?) ``` `start` and `continue` return as soon as the process is confirmed running, not once it finishes — a completion lands as a todo (`get_loose_ends`), same as any other producer. Use `status` for a zero-cost "is it still going" check; reach for `continue` only once you actually have a new instruction for it, since that spends a turn. `interrupt` genuinely stops a running turn (`force: true` for SIGKILL). 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. ## 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. ## 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.