Claude Code Subagents: Designing Delegation That Protects Your Context

When you hand a large task to Claude Code, exploration output, logs, and file contents you will never reference again tend to flood the main conversation. Subagents handle that work in an isolated context and return only a summary. This article walks through their storage, frontmatter, and delegation model from a practical angle, based on the official docs.

This article is compiled by Hashito System from the official Claude Code documentation (Anthropic). Behavior can change between versions. Please confirm the latest and exact details in the primary source linked at the end.

1. What a subagent is

A subagent is a specialized AI assistant that handles a specific type of task. Per the official docs, each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns results.

The main benefits are:

• Preserve context by keeping exploration and implementation out of the main conversation.
• Enforce constraints by limiting which tools a subagent can use.
• Reuse configurations across projects with user-level subagents.
• Specialize behavior with focused system prompts for specific domains.
• Control costs by routing tasks to faster, cheaper models like Haiku.

2. Where the files live (storage and scope)

Subagents are Markdown files with YAML frontmatter. The file location determines who can use them.

• .claude/agents/ — for the current project. Check them into version control so your team can use and improve them.
• ~/.claude/agents/ — personal subagents available in all your projects.

When multiple subagents share the same name, Claude Code uses the one from the higher-priority (project) location. Directories are scanned recursively, so you can organize files into subfolders such as agents/review/ (identity comes only from the name field).

3. Writing the frontmatter

The frontmatter defines the subagent's metadata and configuration; the body becomes its system prompt. Only name and description are required. Here is a read-only code reviewer:

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality and best practices. Use after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a code review expert. Check changes for readability,
maintainability, and obvious bugs, and return specific findings.
Do not modify files.

The key frontmatter fields are:

• name (required) — the identifier. Keep it unique across the tree.
• description (required) — when to use it. Claude reads this to decide when to delegate.
• tools — an allowlist of tools. The example above grants no write or MCP tools.
• model — the model to use (e.g. sonnet, haiku). Route light work to cheaper models.

4. How they are invoked (automatic delegation)

Claude uses each subagent's description to decide when to delegate automatically. That is why writing a clear, specific description is the single most important step. Claude Code watches ~/.claude/agents/ and .claude/agents/, detects file changes within a few seconds, and uses the updated definition on the next delegation, usually with no restart needed.

Note that the /agents command's behavior has changed across versions. In recent versions the interactive creation wizard is gone; running it prints a reminder to ask Claude or edit .claude/agents/ directly.

5. When to reach for a subagent

Subagents shine when a side task produces a lot of intermediate output you will not need in the main conversation.

• Code exploration — ask "where is this handled?" and get back only the conclusion.
• Research — have it read many files or logs and return a summary.
• Review — delegate to a dedicated code-review subagent after changes.

This complements the idea of "designing agentic loops" that we covered in another article: prepare a small loop (subagent) per role and run it without polluting the main context.