Tool, Skill, or Subagent? The Claude Code Decision

Summary:

1. Tool, skill, or subagent is a routing decision, not a default. Walk four axes before you build anything.
2. Cold-start cost climbs: inline prompt is free, a tool call is cheap, a skill is low, a subagent is the most expensive.
3. Most logic is not a subagent. The framework’s most common answer is “inline prompt.”
4. Bonus: the cost ladder, the four-axis tree, and the live subagent frontmatter field reference.

Tool, skill, or subagent? Most operators never ask. They reach for a subagent because subagents are the most-talked-about feature, and they end up with the 47-specialist library a Reddit poster described: “Everyone’s making these massive subagent libraries with 47 different specialists and wondering why their code still sucks. My first attempt had a ‘CSS perfectionist’ agent that just added more divs to everything.” That is the failure mode this framework prevents. More subagents do not mean better results.

When should you use a subagent vs a tool or skill?

Walk four questions in order, and most logic routes away from a subagent. The decision is a cost ladder: each option pays a different cold-start tax, and you want the cheapest one that does the job. The CSS-perfectionist case is the canonical “should have been a skill”: the operator wanted opinionated review, spun up a fresh-context subagent that had no codebase awareness, and got generic advice applied blind. A skill would have loaded the real conventions for a fraction of the cost.

Here is the cost ladder from your /usage line, in rough tokens:

A subagent is roughly fifteen times the cold-start cost of a tool call. That gap is the reason the default matters.

The four-axis decision

For any piece of logic you are about to delegate, ask in order:

1. Fresh task or continuation? A continuation belongs in the main session. You already paid to load the context; spinning a fresh window throws it away. Continuation means inline prompt or tool call. Stop here. Fresh task means proceed.
2. Reusable instruction set? A set of steps you want Claude to follow every time a class of task comes up (“open a PR from an issue,” “review code for style”) belongs in a skill. A skill loads into the running session without the cold-start cost of a fresh window. If not reusable, proceed.
3. Separate context window? This is the actual mechanical reason subagents exist: either the task pollutes the main context (a review across 200 files) or it needs isolation for correctness (a reviewer that should not see the planner’s assumptions). If yes, subagent. If no, inline prompt or tool call.
4. Needs parallel? This only fires if axis 3 already said subagent. Fan out three workers, collect three results. If yes, design it with parallel safety (worktrees, named branches). If no, it is a serial fresh-context delegation, still a subagent, dispatched one at a time.

Most operator confusion comes from skipping straight to axis 3 (the subagent default) without checking axes 1 and 2 first. If your worksheet has every section returning “subagent,” you walked the framework wrong. Go back to axis 1.

When you do build one: the subagent frontmatter fields

When a task survives all four axes, you build the subagent. These are the configuration fields, from the Claude Code subagents docs:

That last field is the key to good decomposition. Instead of cramming reusable instructions into the subagent body, name them in skills and let Claude preload the content:

---
name: code-reviewer
description: Reviews diffs against project style, security, and coverage conventions.
tools: Read, Grep, Bash
model: sonnet
skills:
  - code-style
---

The code-style skill is its own small file holding the reusable rules:

---
name: code-style
description: Use when reviewing a pull request for style, security, and coverage.
---

# Code Style
- Follow the security baseline in docs/security-conventions.md.
- Flag missing test coverage on public functions.
- Flag any console.log left in production paths.

The skill holds the reusable rules; the subagent does the boring isolation work. That split is the difference between a 70%-token-reduction decomposition and a 400-line prompt that re-explains your conventions on every call.

The reality check: most logic is not a subagent

Here is the honest read most subagent content skips. The framework’s most frequent output is “inline prompt.” The second is “tool call.” Skills are third. Subagents are fourth, and rare.

Take “write a commit message for the current diff.” It feels like a fresh task, so operators build a commit-message-writer subagent. Walk axis 1: it is a continuation. The main session already knows the diff and the issue context. An inline prompt costs roughly fifty tokens. The subagent version cold-starts its system prompt, re-reads the diff because it inherits nothing, and returns a summary, for roughly three thousand tokens. Sixty times the cost for the same output. That is the structural reason the “10-20% performance boost” confessions on Reddit happen: a stack that feels sophisticated, paying cold-start tax on tasks that should have been inline prompts.

The litmus test: if the main session already has the relevant files and context loaded, the task is a continuation. Type the prompt and move on. Run the /usage check before and after any decomposition to prove the savings instead of assuming them:

# In the Claude Code session, before and after the decomposition
/usage

What should you actually do?

• If you default to “make another subagent” → walk axes 1 and 2 first. Most logic stops at inline prompt or skill.
• If a subagent re-explains your conventions on every call → move those into a skills: preload and watch the per-call tokens drop.
• If you have a “CSS perfectionist” style agent → it should be a skill with real codebase conventions, not a blind fresh-context reviewer.

The bottom line

• Tool, skill, or subagent is a cost decision. Pick the cheapest cold start that does the job, and that is rarely a subagent.
• The four axes are the filter. Skipping to “subagent” is how libraries bloat to 47 specialists that ship nothing.
• A subagent earns its slot only when it needs a separate context window. Everything else is an inline prompt, a tool call, or a skill.