Docs / Field guide / What is a custom agent, and how do you make one?

What is a custom agent, and how do you make one?

Published 29/10/2026

A custom agent is a named worker you define once: its own instructions, its own tools, often its own model. The main session hands it a job, it works in its own context window, and only its answer comes back. Think of a specialist you can call in: you brief them once, and every later call is "the usual, on this file".

When one is worth having#

You keep giving the same instructions to the same kind of helper, such as a reviewer or a test writer.
A side job would flood your main session with search results or logs you won't need again.
A job should have fewer powers than the main session, such as a reviewer that can't edit files.

In Claude Code#

A markdown file in .claude/agents/ (this project) or ~/.claude/agents/ (every project). Only name and description are required:

MARKDOWN

---
name: reviewer
description: Reviews a change for correctness and missing tests. Use after code changes.
tools: Read, Grep, Glob
model: sonnet
---

Review like an owner. Lead with concrete findings. Do not edit files.

Claude decides when to delegate from the description. To be sure, ask for it by name or @-mention it.

In Codex#

A TOML file in .codex/agents/ or ~/.codex/agents/, with name, description and developer_instructions:

TOML

name = "reviewer"
description = "Reviews a change for correctness and missing tests."
developer_instructions = """
Review like an owner. Lead with concrete findings. Do not edit files.
"""

Codex spawns it when you ask for it by name, or when an instruction file or skill tells it to. It keeps the parent session's sandbox and approval settings.

What it costs#

Each agent works in its own context, so it starts cold: it rereads what it needs, and its cache is separate from yours. Agents that run side by side spend tokens side by side. Keep each one narrow, give it only the tools its job needs, and keep descriptions short, because every description is loaded into the main session.

Where ADE fits#

ADE keeps one roster of roles in ade.toml (pilot, builder, reviewer) with a model for each engine, and ade init writes both the Claude Code agent files and AGENTS.md from it. Each role is briefed by the same generated handover, so a builder on either engine starts from the same picture. See How it flies.