Claude Custom Subagents: Build Your Own AI Workers

Channel: CampusX (Nitish Singh)
Playlist: Claude Code Mastery Series

Overview

This video is a hands-on build guide for creating custom subagents in Claude Code — going beyond the conceptual introduction of the previous episode to show the full configuration syntax, scope management, and design patterns for authoring production-grade AI workers.

What Are Custom Subagents?

Claude Code ships with three built-in subagents — Explore (read-only Haiku-powered codebase search), Plan (read-only context-gathering during plan mode), and general-purpose (full-tool multi-step operations). Custom subagents let you define your own workers with:

• A custom system prompt that specialises the agent’s reasoning
• Tool access control — grant only the tools the worker needs
• A specific model (Haiku for speed/cost, Sonnet for balanced, Opus for complex tasks)
• Permission modes — from fully interactive to bypassPermissions for automation
• Persistent memory — optional cross-session knowledge accumulation

The File Format

Custom subagents are Markdown files with YAML frontmatter, stored in .claude/agents/ (project-scoped) or ~/.claude/agents/ (user-scoped):

---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after any code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
---
 
You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Identify critical issues, warnings, and suggestions

The description field is the routing key — Claude reads it to decide when to automatically delegate. Writing “use proactively” in the description encourages automatic delegation without explicit prompting.

Frontmatter Fields Reference

The full set of configurable fields:

Field	Purpose
name	Unique lowercase identifier (also the @-mention handle)
description	When Claude should delegate (routing signal)
tools	Allowlist of tools; inherits all if omitted
disallowedTools	Denylist; applied before tools allowlist
model	sonnet, opus, haiku, full model ID, or inherit
permissionMode	default, acceptEdits, auto, dontAsk, bypassPermissions, plan
maxTurns	Max agentic turns before auto-stop
skills	Preload skill content into context at startup
mcpServers	Scope MCP servers to this agent only
hooks	Lifecycle hooks (PreToolUse, PostToolUse, Stop)
memory	user, project, or local for persistent cross-session memory
background	true to always run concurrently
isolation	worktree for git-isolated execution
color	Visual identifier in the UI

Scope Hierarchy

Subagents are discovered at four levels, with higher priority winning on name collision:

1. Managed (org-wide, highest priority)
2. CLI --agents flag (current session only)
3. .claude/agents/ (project-level, version-controlled)
4. ~/.claude/agents/ (user-level, all projects)

Project subagents in .claude/agents/ should be committed to version control so the whole team shares the same worker definitions.

The /agents Command

The /agents command opens a tabbed UI for managing subagents:

• Running tab — see live agents, open or stop them
• Library tab — create, edit, delete, and inspect all agents

You can create a new agent by selecting Generate with Claude and describing what you want in plain English — Claude writes the name, description, and system prompt for you.

Key Design Patterns

Pattern: Read-Only Specialist

Limit tools to Read, Grep, Glob, Bash to create a safe reviewer that can never modify files. Pair with model: haiku for low-cost invocations.

Pattern: MCP-Scoped Worker

Use mcpServers to give an agent exclusive access to an MCP server (e.g., Playwright for browser testing) without adding that server’s tools to the parent context.

Pattern: Hook-Validated Worker

Use PreToolUse hooks to add conditional validation — for example, blocking SQL write operations while permitting SELECT queries.

Pattern: Memory-Accumulating Reviewer

Set memory: project so the agent writes codebase patterns, recurring issues, and architectural decisions to .claude/agent-memory/<name>/MEMORY.md — building institutional knowledge across sessions.

Pattern: Background Worker

Set background: true for agents doing autonomous tasks (running tests, building docs) that should not block your main conversation.

Invoking Custom Subagents

Three escalating levels of control:

1. Natural language — name the agent; Claude decides whether to delegate
2. @-mention — @code-reviewer look at the auth changes — guarantees delegation
3. Session-wide — claude --agent code-reviewer — the whole session runs under that agent’s system prompt and tool restrictions

Fork Mode (Experimental)

Enable CLAUDE_CODE_FORK_SUBAGENT=1 to allow subagents that inherit the full parent conversation context rather than starting fresh. Forks are useful when the subagent would need too much background to reconstruct — they cost less (shared prompt cache) but don’t provide context isolation.

Cost Architecture

Routing tasks to cheaper models via custom subagents is the primary lever for controlling session costs:

• Exploration and search → Haiku
• Balanced analysis → Sonnet
• Complex reasoning → Opus (only when needed)

Combined with the isolation benefit (subagents don’t inherit parent history), this reduces per-call token cost by 60–80% for complex multi-file projects.

Synthesis

Custom subagents operationalise the principle that specialisation reduces cost and increases reliability. Each worker knows only what it needs: a focused system prompt, minimal tool surface, and the right model tier. The /agents UI makes this accessible without YAML expertise; the file format makes it version-controllable and shareable across teams.

---

See Also

Wiki Concepts

• Claude SubAgents — architecture, dispatch patterns, and the prior conceptual introduction
• Claude Code — the host environment; context window and extensibility architecture
• Claude Skills — complementary mechanism: skills run in parent context, subagents in isolated context
• Context Engineering — per-agent context scoping as a design discipline
• MCP — mcpServers field lets subagents scope MCP servers exclusively
• Plan Mode & Ultraplan — Plan subagent is a built-in used during plan mode
• Agentic Workflows — custom subagents as the execution layer of multi-agent workflows
• Agent-Native SDLC — specialist agent roles at the system level mirror custom subagent design
• LLM Observability — tracking per-subagent token spend and context health
• Custom Slash Commands — manual-invocation precursor to autonomous subagent dispatch
• Spec-Driven Development — spec tasks map to subagent invocations
• Agent Memory Systems — subagent memory field enables persistent cross-session knowledge

Related Sources

• Claude SubAgents: Solve Context & Token Cost Problems — the conceptual foundation this video builds on
• Claude Code: Building Custom Skills — skills as the parallel extensibility mechanism
• Claude Code & MCP — MCP server scoping via subagent frontmatter
• Ultraplan & Plan Mode — built-in Plan subagent context

Creator / Entity

• CampusX (Nitish Singh) — part of the Claude Code Mastery Series