Claude Code — Part 6 — Subagents and the Agent Tool

Introduction

Part 5 covered packaging a repeatable procedure as a Skill. This post covers a related but different problem: a task that is worth doing, but whose intermediate work you have no reason to keep looking at afterward, a deep search across a large scripts library, a pass through several days of logs, an audit of every scheduled task on a server.

Doing that inline fills your main conversation with file contents and search results you will not reference again. A subagent runs the same work in a separate context window and returns only the summary.

What Is a Subagent?

A subagent is a specialised assistant that handles one kind of task, running in its own context window with its own system prompt, its own tool access, and independent permissions. When your request matches a subagent’s description, Claude delegates the work to it, the subagent works independently, and only its result comes back into your main conversation.

Think of it as sending a colleague off to dig through an archive and come back with a one-page summary, rather than having them read every document out loud to you as they go.

Built-in Subagents

Claude Code ships with several subagents that are used automatically, no setup required.

Claude picks one of these on its own when a task fits the shape. You do not have to name a subagent explicitly for the built-in ones to be used.

When It Is Worth Delegating

The test is whether the intermediate work is something you will actually reference again. Reading through fifty scripts to find the three that still call a decommissioned server, or scanning several days of a log for a pattern, both produce a lot of noise on the way to a short answer. That noise belongs in a subagent’s own context, not yours.

Creating a Custom Subagent

Custom subagents are markdown files with YAML frontmatter, saved to a specific location depending on scope.

Only name and description are required. tools restricts what the subagent can touch, and model lets you route routine audits to a cheaper model rather than whatever you are running the main session on.

Following on from the CLAUDE.md example in Part 4, here is a read-only subagent that audits PowerShell scripts against that same quality baseline, without being able to edit anything itself.

# Save to .claude\agents\script-auditor.md

---
name: script-auditor
description: Reviews PowerShell scripts for quality baseline violations, missing StrictMode, aliases in place of full cmdlet names, untyped parameters. Use after writing or updating a script, or when asked to audit the scripts folder.
tools: Read, Grep, Glob
model: sonnet
---

You are a PowerShell quality auditor. For each script you review, check for:
- Set-StrictMode -Version Latest present
- No aliases such as ? or % in place of full cmdlet names
- Typed parameters with validation attributes where appropriate
- Comment-based help header present

Report findings as a short list per file: what was checked, what passed,
and what needs fixing. Do not edit files yourself.

Invoking It

Once the file is saved, Claude picks it up automatically when a request matches the description, or you can name it directly.

audit the scripts in this folder against our quality baseline

use the script-auditor agent on Get-ADHealthReport.ps1

Final Thoughts

Subagents are about protecting your main session, not about making Claude smarter at any single task. The value is entirely in keeping the noisy, disposable part of an investigation out of the conversation you are actually trying to have.

Start with the built-in Explore agent for anything read-only, and only reach for a custom subagent once you notice yourself asking for the same kind of audit or research more than once.