How to Write Claude Code Subagent Descriptions That Trigger Delegation Reliably

Reference

A lot of Claude Code users create a subagent, give it a vague description, and then wonder why Claude almost never delegates to it — or delegates at the wrong time.

That usually comes down to one thing: the description is the routing layer.

Anthropic's Claude Code docs are explicit: Claude uses the task description in your request, the subagent's description field, and the current context to decide whether to delegate. Anthropic also says that if you want to encourage proactive delegation, you should include wording like "use proactively" in the description.

The real job of the description

Many people write descriptions as labels:

"Database expert"
"Testing helper"
"Refactoring agent"

That is too vague.

Claude does not need a slogan. It needs a clear trigger condition. The description should tell Claude:

• what this subagent is for
• when to use it
• what kind of tasks belong to it
• what kinds of tasks do not belong to it

If the description is fuzzy, you get two bad outcomes:

• Missed delegation — Claude keeps doing the work in the main conversation
• False positives — Claude sends work to the subagent when it should not

Built-in and custom subagents are selected based on the description, which is why description quality matters more than people think.

A bad description vs a good one

Bad:

description: Helps with tests

This is weak because it does not define scope. Does it run tests? Fix tests? Explain failures? Write new tests? Only unit tests? All of the above?

Better:

description: Investigate failing tests, identify likely root causes, and propose or implement targeted fixes. Use proactively when test failures, flaky tests, or CI test regressions are involved.

This is much better because it gives Claude a task type, a trigger, a boundary, and a signal to delegate proactively.

The simplest structure that works

A reliable subagent description usually has four parts.

1. Primary responsibility

What is the subagent supposed to do?

Investigate TypeScript type errors and propose minimal fixes.

2. Trigger language

When should Claude delegate to it?

Use proactively when the user mentions compile errors, broken types, or failing tsc checks.

3. Scope boundaries

What belongs here, and what does not?

Best for diagnosis and targeted fixes, not large feature work or broad refactors.

4. Expected output

What should come back?

Return the root cause, affected files, and the smallest safe change.

That is much stronger than a generic "TypeScript agent."

Why "use proactively" matters

Anthropic explicitly recommends phrases like "use proactively" if you want Claude to delegate more readily. Many users assume delegation will happen automatically as long as the subagent exists. In practice, the description needs to actively push Claude toward delegation when the pattern matches.

Strong example:

description: Review recent code changes for correctness, edge cases, and regression risk. Use proactively when the user asks for review, validation, or a second pass before merging.

Weak example:

description: Code reviewer

How false positives happen

Over-broad descriptions are the usual cause.

Bad:

description: Helps with backend code. Use proactively.

"Backend code" is too wide. Claude could route debugging, refactoring, architecture, tests, database work, and API changes through that one subagent.

Better:

description: Investigate database query issues, slow queries, and schema-related bugs. Use proactively when SQL performance, indexes, migrations, or query correctness are involved.

Now the routing is much cleaner.

How missed delegation happens

Missed delegation usually comes from descriptions that are:

• too short
• too abstract
• written like job titles
• missing the language users actually type

If users say things like "why is CI failing?", "why are these tests flaky?", "can you check this migration?" — then your descriptions should include those concepts directly or semantically close language. Delegation depends partly on the task wording in the request, so your descriptions should match the kinds of requests people actually make.

A practical template

description: [Do this specific job]. Use proactively when [clear trigger conditions]. Best for [scope]. Not for [out-of-scope work]. Return [expected result shape].

Example:

description: Investigate performance regressions in application code and database access. Use proactively when the user mentions slowness, timeouts, N+1 queries, or increased latency. Best for diagnosis and focused fixes, not full architecture redesigns. Return the likely bottleneck, affected files, and recommended changes.

Best practices in one shot

For reliable delegation:

• write descriptions as routing rules, not labels
• include "use proactively" when you want more automatic delegation
• name exact triggers
• define scope tightly
• say what the subagent should return
• avoid broad "expert" wording with no task boundaries

That is the difference between a subagent Claude actually uses and one that just sits there looking official.

For the broader picture of when subagents make sense in the first place, see Claude Code Subagents for Developers: When a Skill Is Not Enough.