Here is the mental model that finally made subagents useful to me. Skills are how I do X. Agents are go do X and report back. Two weeks ago I wrote about skills as playbooks: documented, tested procedures the assistant loads when a task matches. Agents are the other half. You hand a bounded task to a specialized worker, it runs on its own, and it comes back with a single report. The difference sounds small and it changes what the main conversation is for.
Three Traits Worth Protecting
| Trait | What it means | What it buys you |
|---|---|---|
| Stateless and scoped | Each invocation gets a full brief and returns one result; there is no back-and-forth | The brief has to be complete, which forces you to know what you are asking |
| Parallelizable | Independent read-only agents can run side by side | Three questions, three workers, one review |
| Specialized | A roster tuned to domains, not one general worker | Shorter briefs and more predictable reports |
The first row is the one people fight. The instinct is to want a conversation with the agent, to steer it mid-task. If you find yourself wanting that, the brief was incomplete. Fix the brief. An agent you can talk to is just the main thread with extra steps.
When to Dispatch
The tell is context. If the work would flood the main conversation with material you only need the conclusion of, that is an agent. The canonical case is a big question: where is this handled, and why. Answering it takes dozens of file reads, and if those reads land in the main thread, the model's attention is now on the search instead of the decision. I dispatch an exploration agent, it reads the dozens of files, and what comes back is a paragraph with line numbers.
| Situation | Main thread | Agent |
|---|---|---|
| A dozen or more file reads whose contents you do not need to see | yes | |
| A question with a short answer and a long search | yes | |
| Independent of other work in flight | yes | |
| Needs your judgment at several points along the way | yes | |
| Touches files you are also editing | yes | |
| One step, one file, one look | yes |
The Brief Is the Whole Job
Because there is no back-and-forth, everything you would have answered mid-task has to be answered up front. The brief I use has seven parts. An objective written as an end state, not an activity. A scope with an explicit out-of-scope list, because agents drift toward the interesting adjacent problem. Inputs, meaning everything the agent would otherwise have to rediscover. Constraints, where read-only is the default and anything irreversible or outward-facing is not delegated at all. An output contract that fixes the report's shape: answer first, evidence with file and line, then what was not found, then open questions as a list. Done criteria the agent can run against its own report. And stop conditions, so it returns early rather than pushing through a false premise.
The section that makes a report trustworthy is the one for gaps. An agent that says "not found" is more useful than one that fills the space, and a short report saying "the function you named does not exist, the nearest match is this" is a successful run, not a failed one.
The Roster
Generalized, mine has a fast read-only codebase explorer, which I reach for instead of chaining searches by hand; a data-query specialist loaded with the catalog; a documentation searcher over an indexed corpus; publishing workers; and a set of knowledge-base agents that route a question about a field, an architecture, or a past decision to the right index. More than a dozen in total. Each one exists because the same brief kept getting written, which is the same dispatch rule that creates a skill.
Take It
The brief template, the dispatch table, and notes on each field are in agent-brief.md. Fill every field. A blank field is a guess the agent will make for you, and it will make it confidently.
This is part of a track on agent tooling and spec-driven development that goes deeper than a field report, with something you can download and run in each one. Free for now while the track grows; the deepest installments become a paid tier later.