subagent-brief

---
name: subagent-brief
description: Use BEFORE invoking the Task or Agent tool to spawn a subagent. Anthropic does NOT share prefix cache across subagents — every subagent cold-starts and re-tokenizes its full prompt (system prompt + tool definitions + the context you handed it). Spawning N subagents with full context = N× token cost; a single fan-out can burn an entire Max-plan day. This skill enforces a pre-flight discipline: compress every subagent prompt into a ≤200-word brief before spawning. Triggers when the agent is about to call Task / Agent tool, especially with long files, full repo dumps, or N parallel subagents on similar work.
---

# Subagent Brief Discipline

Pre-flight checklist for spawning subagents in Claude Code. The single most
expensive mistake in multi-agent workflows is treating subagents as free
threads. They are not. Each subagent is an independent LLM call that
re-tokenizes the entire prompt you hand it.

There is **no prefix sharing across subagents** in Anthropic's serving stack
today. The multi-agent topology is a known optimization opportunity (see
arXiv 2604.25899 *Pythia: Predictability-Driven Agent-Native LLM Serving*,
2026-04) but has not yet shipped in production. Until it does, the burden
of compression falls on the orchestrating agent.

The math: 20 subagents × 50K shared context = ~1M tokens per fan-out. One
careless Task call exhausts a Max-plan daily quota.

## When to Use

- About to invoke the Task tool or any subagent-spawning tool
- About to fan out N parallel subagents on similar tasks
- Subagent prompt is shaping up longer than ~200 words
- About to embed a long file, full repo dump, or full PRD in a subagent prompt
- The user is on a metered plan (Max / Pro / API) and has not signaled "burn budget"

## When NOT to Use

- Spawning a single subagent with a one-line task ("read X and summarize")
- The subagent genuinely needs the full document (translation, full audit, line-by-line review)
- Throwaway exploration where token cost truly does not matter
- The orchestrator already received a compressed brief from the user — pass it through, do not re-compress

## The Discipline

For every subagent you are about to spawn, apply these five rules in order.

### 1. Strip your own context

The subagent gets its own system prompt, its own tool list, and its own
task framing automatically. Do **not** paste your own conversation history,
your TODO list, or your reasoning trail into the subagent prompt unless
the subagent literally needs them to do its job.

### 2. Replace files with paths

```
BAD:  Here is the full content of foo.py: <800 lines>
GOOD: Read /abs/path/to/foo.py and report the public API.
```

The subagent has Read access. One Read call is cheaper than re-tokenizing
800 lines on every spawn.

### 3. Replace context with summaries

```
BAD:  <entire 50K context window dump> — now look for X
GOOD: Project context: <3-line summary>. Look for X in <specific path>.
```

If you genuinely synthesized something useful from your context, summarize
it in 1-3 sentences and pass that summary. Never paste the raw window.

### 4. Compress to ≤200 words

The brief should fit in a tweet-length window. If it does not, you are
either dumping context the subagent can fetch itself, or handing over a
task too large for one subagent — split it.

### 5. Fan-out check

Before spawning N parallel subagents, ask: do they all share the same long
context? If yes, you are about to multiply cost by N. Either:

- Spawn **1 subagent** that handles all N items sequentially, **or**
- Pre-compute a shared brief once and hand each subagent only the *delta*
  (the per-item task), not the shared context.

## The Brief Template

```
ROLE:    <one line — what this subagent is>
GOAL:    <one line — what it should produce>
INPUTS:
  - <path or 1-line summary, never raw content>
  - <path or 1-line summary>
CONSTRAINTS:
  - <output format, what NOT to do>
RETURN:  <one line — what to report back>
```

Total ≤ 200 words. If it does not fit, the task is too large for one
subagent. Split it.

## Rationalizations to Reject

| Excuse | Reality |
|---|---|
| "Faster to just paste the whole file." | Faster for *you*. The subagent re-tokenizes 800 lines on every spawn. |
| "Parallelism will be 5× faster." | 5× faster wall-clock, 5× more tokens — and Max plan caps are *daily*, not hourly. The hourly speedup costs you the rest of the day. |
| "The subagent needs context." | It needs *information*. A summary is information. The raw window is dump. |
| "I'll just pass the whole repo, it's small." | "Small" repos compound across 10 subagents into a Max-plan kill. |
| "I don't have time to summarize." | Summarizing forces you to clarify what the subagent should do — which is 80% of why subagents fail anyway. |
| "The user wanted parallel." | The user wanted *fast*. Token-budget parallel ≠ wall-clock parallel. Default to sequential unless tasks are genuinely independent. |

## After the Brief

Spawn the subagent. Then evaluate:

- Returned with **hallucinated assumptions** → brief was too vague. Add a
  constraint and re-spawn (rare).
- Asked for **more context** → brief was too thin. Add the missing fact and
  re-spawn (rare).
- **Succeeded** → brief was right-sized. This is the common case if you
  followed the five rules.

Most "subagent failures" are brief failures, not subagent failures.

## Red Flags in Your Own Output

If you catch yourself writing any of these in a subagent prompt, stop and
re-compress:

- Three or more paragraphs of background before the actual task
- Verbatim file contents longer than 20 lines
- The phrase "for context, here is..."
- Lists of things the subagent "might want to know"
- More than one task per subagent (split into separate Task calls instead)

## Why This Skill Exists

Multi-agent serving is a 2026 research topic, not a shipped feature.
arXiv 2604.25899 (Pythia, 2026-04) demonstrates that exposing multi-agent
topology to the serving layer can recover 3-5× of wasted tokens via prefix
sharing — but no production LLM provider has shipped this yet. Anthropic,
OpenAI, Codex: every subagent today is a cold-start, full-prefix
re-tokenization.

Until that changes, **the brief is the only knob you have.** Use it.