Claude Code

Verified against Claude Code · 2026-07-23

Define a specialized Claude Code subagent instead of overloading the main thread

A prompt that produces a complete .claude/agents/*.md subagent definition — scoped tools, a narrow system prompt, and a model choice — for a repeated task that deserves its own isolated context rather than living in the main conversation.

Claude Code5 fillable variables

The prompt

Ready to copy — highlighted parts are example details you can swap.

Define a Claude Code subagent as a single markdown file for .claude/agents/, to be invoked either automatically when its description matches the moment, or explicitly by name.

JOB THIS SUBAGENT DOES, AND ONLY THIS JOB
Run the full test suite after any code change, parse failures, and report which specific test names failed and why, without attempting to fix anything.

WHEN IT SHOULD BE INVOKED
Automatically whenever the main conversation has just finished editing code and is about to claim a task is complete; also invokable explicitly by name.

WHY IT NEEDS ITS OWN CONTEXT RATHER THAN RUNNING IN THE MAIN THREAD
Test output for a large suite can run to thousands of lines; parsing that in the main conversation would consume context the actual coding task still needs, so it should happen in a disposable subagent context instead.

STRUCTURE THE FILE AS
1. YAML frontmatter: name (short, kebab-case, matching the filename), description (written as a clear trigger condition the main agent could match against, not a vague summary — state the situation that should cause delegation to this subagent), tools (an explicit, narrow list; grant only what this specific job needs, never the full default set out of convenience), and model, set to a faster, cheaper model than the main conversation, since parsing test output is high-volume and low reasoning difficulty if the job is simple and high-volume enough to justify a cheaper or faster model than the main conversation is using.
2. A system-prompt body written in second person, addressed to the subagent itself, stating its one job, its boundaries, and explicitly what it must hand back to the main conversation rather than silently deciding on its own.
3. An output contract: the exact shape the subagent must return to the calling conversation, since the subagent's own reasoning and any tool output it generated does not automatically appear in the main thread — only what it explicitly returns does.

CONSTRAINTS
- Do not give this subagent authority the described job does not need. A subagent that only reads code and reports findings should not have Write or Bash access, even if that access would make some future job easier — scope it to today's job, not a hypothetical future one.
- Make the description field specific enough that the main agent would not mistakenly delegate an unrelated task to this subagent, and would not fail to delegate a task that actually belongs to it. Ambiguous descriptions cause both failure modes at once.
- State explicitly, inside the subagent's own body, that it should not consume its own context speculatively exploring the repo beyond what the job requires — an isolated subagent with unbounded scope defeats the reason for scoping it narrowly in the first place.
- If this subagent's job overlaps at all with an existing subagent already defined in .claude/agents/, name the overlap and propose either merging the two responsibilities or drawing a sharper boundary between them, rather than leaving two subagents with descriptions vague enough to both plausibly match the same situation.

OUTPUT
The complete file content, frontmatter and body, ready to save as-is. After it, one sentence on what the main conversation must still do that this subagent explicitly will not — the actual boundary of delegation.

Customize

Optional — swap in your own details for the highlighted parts above.

Why this works

A Claude Code subagent executes in its own separate context window, and the mechanism that matters here is narrower than it sounds: only what the subagent explicitly returns crosses back into the main conversation, so a thousand-line test-failure log or a sprawling grep across a large repo can be absorbed and distilled inside the subagent's disposable context without ever touching the main thread's budget, which is the actual reason to isolate a noisy task rather than just a way to organize files. The tools field in the frontmatter is an enforced permission boundary at the subagent level, the same mechanism that scopes a slash command — a subagent whose job is reading test output and reporting failures can be denied Write and Bash entirely, so it is structurally incapable of attempting a fix even if its own reasoning drifted toward doing so, which is a stronger guarantee than an instruction not to fix anything embedded only in prose. The description field is not documentation, it is the literal input Claude's main agent matches against when deciding whether to delegate a given moment to this subagent automatically, so a vague description produces two distinct failure modes rather than one: it can cause the main agent to delegate something unrelated because the description was broad enough to plausibly match, or it can cause the main agent to handle a task itself that should have gone to the subagent because the description never clearly claimed that territory — specificity here has a direct behavioral effect on delegation, not just a documentation-quality effect. Setting model to a smaller or faster option than the main conversation is using is a real lever, not a cosmetic setting, because high-volume, low-reasoning-difficulty work such as parsing structured test output does not benefit from the main conversation's more expensive model, and running it on a cheaper one changes the actual latency and cost of a workflow that might run after every single code change. The constraint against speculative exploration inside the subagent exists because an isolated context with unbounded scope reintroduces the exact context-consumption problem isolation was meant to solve, just moved one level down.

Verified against

Claude Code Sonnet 4.6 · 2026-07-23

Changelog

  • 2026-07-23 Initial publish, verified against Claude Code subagents (Sonnet 4.6).

Building this for real?

This is a free starting point. If you'd rather have custom software built and running for your business, that's Scult's day job.

EXPLORE CUSTOM SOFTWARE
All Claude Code prompts

Check your AI visibility

One URL in, a 0–100 score and the exact fixes out.

RUN THE CHECK

Browse all the tools

15 tools across six categories
13 of them never send your data anywhere

Free · No signup · No trial clock

SEE THE DIRECTORY