跪拜 Guibai
← Back to the summary

When to Delegate to Subagents: Token Savings, Parallel Red Lines, and a Three-Layer Setup

This post is compiled from the free practical guide Oil Book (book.oiloil.org) (original: https://book.oiloil.org/articles/subagent-workflow). The site offers ad-free paper-book layout, full original hand-drawn diagrams, and a complete AI engineering series index.

Hello everyone, I am Ouyou. This article will share how to make good use of sub-agents.

If you are just getting started with AI Agents, or don't yet know what a Skill is, I recommend reading the two previous basics articles: AI Agent Recommendations and Environment Configuration and Understanding Skills from 0 to 1. Once you have the basics clear, this sub-agent sharing will go more smoothly.

What is a sub-agent and the pain point of a single window

To use an everyday team analogy: suppose we go to talk to the head of a team about requirements, and this head is the one who communicates with us. Once we've clarified the requirements and are ready to start doing things, to improve efficiency, or to let others do what they're best at, he won't do all the work himself. Instead, he'll send his subordinates to do it.

The same applies to AI Agents: the one who communicates with us directly and coordinates the whole thing is the main Agent, and the subordinates it sends out to do work are sub-agents. Sub-agents generally don't talk to us directly. They only receive tasks assigned by the main Agent, execute them in their own independent environment, and then report the results back to the main Agent.

Comparison: doing a topic from start to finish vs. main Agent dispatching independent sub-agents

1. The pain point of working from start to finish in a single topic

Usually, if we keep the same Agent working from start to finish in a single topic, the biggest pain point is that its context expands very quickly.

Because when we do Vibe Coding (using natural language to let AI write code), the Agent needs both to explore the code broadly, reading many files, and also to modify code and check run logs. After a few rounds of operation, the current topic's context fills up instantly, even triggering the system's context compression. Once the context is full or compressed, it often becomes vague about the requirements and constraints we clarified at the beginning, and the quality of its answers and code modifications drops.

2. Why did I start using sub-agents?

Initially, I used sub-agents mainly to increase my coding speed.

On one hand, a main Agent working alone can only work serially, while sub-agents can execute in parallel—the main Agent sends non-conflicting subtasks to several sub-agents at once, so waiting time is much shorter. On the other hand, I don't need to manually open multiple topics and communicate with each separately. From start to finish, I only need to communicate with one main Agent in the current main topic, and it distributes tasks and aggregates results for me.

Which tasks are suitable for sub-agents

When judging which tasks fit a sub-agent, there is a simple, easy-to-remember rule:

If a task generates a large amount of intermediate process information, but ultimately only needs a concise summary or a change result, it's very suitable for a sub-agent.

Four types of tasks suitable for sub-agents and three parallel red lines

Specifically in daily development and creation, the most typical scenarios include:

1. Three types of scenarios not suitable for parallel sub-agent dispatch

Although sub-agents can speed things up in parallel, not all tasks are suitable for splitting and running in parallel. In the following three cases, parallel dispatch is not recommended:

  1. Multiple sub-agents might modify the same file: If two sub-agents modify the same file or tightly coupled modules at the same time, they can easily overwrite each other's changes, making it hard to merge later.
  2. The task must proceed serially: If the next step completely depends on the previous step's result (for example, you must first modify the database table structure before you can write the corresponding API logic), it's impossible to dispatch in parallel.
  3. High-risk actions involving permissions, releases, or deletions: Operations like online deployment, deleting data, or modifying core configuration are complex or risky. They should stay in the main topic with the main Agent executing carefully, not be delegated to sub-agents.

2. Who decides whether to dispatch a sub-agent?

After seeing which tasks fit and which don't, many newcomers to sub-agents ask: in everyday coding, how do I decide whether this step should be done by the main Agent itself, or should I order it to dispatch a sub-agent?

To be honest, whether to do it with the main Agent or dispatch it to a sub-agent isn't usually something I decide. Generally, the main Agent decides itself.

My daily practice is: I pre-assign several sub-agent roles to the main Agent (or use its built-in sub-agent mechanism), then set up dispatch rules. The main Agent decides whether to dispatch sub-agents based on the complexity of the current task. I rarely explicitly command, "You must dispatch a sub-agent now," except when a main Agent never initiates dispatch and I really need to improve efficiency or explicitly parallelize multiple tasks. Only then do I actively remind it to call sub-agents.

Three-layer configuration for custom sub-agents

Since daily work relies mainly on pre-configured roles and rules for the main Agent to auto-dispatch, and many mainstream tools (like Claude Code, Codex, etc.) already have built-in default sub-agent mechanisms, why aren't the built-in ones enough? Why do we often need to customize sub-agents?

1. Why customize your own sub-agent?

There are two core reasons:

First, different main Agents have different default dispatch capabilities

Some main Agents have strong autonomous dispatch abilities. For example, Claude Code actively and reasonably calls sub-agents when exploring code. But Codex's built-in sub-agent dispatch is weaker; by default it often doesn't actively call them, or it doesn't assign tasks very well.

In that case, we can preset rules and roles: explicitly specify which sub-agents are for exploring code, which for executing tasks, which for Review, and which for copywriting.

Second, specialized scenarios can get tailored prompts and cheaper models, saving context and money

Sub-agents can have their own system prompt (System Prompt) and model configured separately. So customizing sub-agents has a very practical value: configure cheap, sufficient lightweight models for specialized scenarios like retrieval or errands that require low reasoning. This saves the main Agent's context space and reduces overall model costs.

2. How to create custom sub-agents in tools

Many people may worry when hearing "custom sub-agent": different tools have different config file formats (some are Markdown, some .toml). What if I don't know how to write them?

Actually, configuring custom sub-agents in Claude Code or Codex is very simple: you don't need to hand-write config files; just let the main Agent configure itself.

You only need to tell the main Agent three things in the dialog:

  1. A name for the sub-agent you want to create;
  2. What it is specifically responsible for (duties and standard requirements);
  3. What model and thinking level it should use.

For example, you can directly send a message like this to the main Agent:

Create a custom sub-agent named explorer, set permissions to read-only, specifically for quickly locating relevant files and line numbers in the code repository and summarizing into a short report. Configure the model to the cheapest lightweight tier you support.

Upon receiving this, the main Agent will look up its built-in configuration documentation and automatically generate the config file in the corresponding directory (like ~/.codex/agents/ or ~/.claude/agents/ under the home directory ~). After creation, typing @ in the input box will show the sub-agent you just created. You can also directly tell the main Agent, "Use the just-created explorer sub-agent to check the project directory structure," to verify it works.

3. The "three-layer configuration architecture" that applies to any tool

Once you know how easy it is to create a single sub-agent, managing and stably using a whole set of custom sub-agents—regardless of the tool you're using—boils down to the same three-layer configuration architecture:

Anatomy of the three-layer configuration architecture for custom sub-agents

Layer 1: Global configuration (controls run boundaries)

The outermost layer is the tool's global settings (like in the Configuration panel or global config files under the home directory). It mainly controls the default model for sub-agents, plus two parameters related to run boundaries: maximum number of concurrent sub-agents (e.g., default up to 6 sub-agents at once) and maximum nesting depth (i.e., whether sub-agents can recursively call another layer of sub-agents).

In practice, these two parameters can generally stay at defaults. In particular, nesting depth should stay at at most one layer—that is, only the main Agent dispatches sub-agents, and sub-agents are forbidden from recursively dispatching another layer. More layers don't actually work better; they're more likely to go out of control and waste quota. Even if you want to adjust global config, you can simply ask the main Agent to modify it; no need to manually flip through config files.

Layer 2: Custom sub-agent role configuration (holds role-specific knowledge and models)

The middle layer consists of individual config files for each sub-agent created earlier (like files in ~/.codex/agents/ or ~/.claude/agents/). They define the role's name, model, thinking intensity, and built-in system prompt (e.g., a frontend sub-agent with frontend standards, a review sub-agent with a code review checklist).

Layer 3: Dispatch Skill (manages when to dispatch whom)

The innermost layer is a Skill that constrains the main Agent's dispatch behavior. It tells the main Agent: what scale of task should dispatch which type of sub-agent, when to pass the current conversation's history context to sub-agents, and when to reuse an already-started sub-agent. The reason for making this an on-demand Skill, rather than stuffing it into the always-read global rule file AGENTS.md (or CLAUDE.md), is that daily simple conversations don't need to start a whole development team every time. Only when truly entering multi-module programming tasks should it be triggered on demand.

After understanding Layer 2 and Layer 3, there's a critical division-of-labor principle: write the specific execution specifications for "how to do the work" in the Layer 2 sub-agent's own config file, while Layer 3 Skill only handles dispatch.

This is because the Skill is read by the main Agent. If you write a big chunk of frontend standards or review checklists into the Skill, the main Agent will re-output that whole prompt every time it dispatches a task, wasting output tokens and context. Conversely, putting role-specific standards directly into the sub-agent's own config file means the main Agent only needs to say a short sentence like, "Go check the code in a certain place," and the sub-agent's built-in prompt will guide it to follow the standards. To summarize: Skill manages dispatch, sub-agent config file manages execution.

Four core roles and a collaboration loop

When assigning subordinates to the main Agent, I don't split into a bunch of tiny roles based on task difficulty. Instead, I divide by specialized responsibility and model strengths.

Note: the specific model names I mention below (like Codex's lightweight tier GPT Luna, high-end tier GPT-6 Astra, or Gemini) are just examples from my daily usage. No matter how models are upgraded or renamed across vendors, what we need to grasp is the overall sub-agent division-of-labor philosophy, which applies to any Agent tool and any LLM.

1. Explorer: cheap model for large-scale code retrieval

I generally plan an Explorer role first. It's a read-only sub-agent for exploring code locations in complex repositories, or doing research before diving in.

Explorer: cheap lightweight models scan code in parallel and summarize into a short report

Because exploration only needs to generate search keywords, locate files and line numbers, and organize large-scale input information into a short report for the main Agent, the reasoning requirement is low. So I configure it with the cheapest, fastest-response tier. In Codex, I use GPT Luna (cheapest lightweight tier) with quick mode for code exploration. In Claude Code, the corresponding lightest tier is Haiku. This way, it can safely scan dozens of files in parallel, saving the main Agent lots of context and barely consuming quota.

2. Executor: execution-oriented model, avoiding weak recall

The second always-ready role is Executor, responsible for execution tasks with clear boundaries, like modifying code. For an Executor, a model oriented toward execution is enough. It doesn't need strong product design, strong global planning, or strong conversational feel.

Executor: modifies code according to explicit boundaries and standards set by main Agent

Here's an interesting practical experience: some cheap lightweight models are unstable when used alone as the main Agent, but work very well as executor sub-agents.

Why? When a project has accumulated many standard documents or Skills, a lightweight model used alone as the main Agent often forgets to proactively read the relevant standard files if we don't explicitly name the file (i.e., its autonomous recall is weak). But when it runs as an executor sub-agent, the stronger main Agent has already clearly specified before dispatch: "which standards to read, which files to modify, where the boundaries are." This sidesteps the lightweight model's weak recall, while enjoying its very low call cost.

3. Reviewer: independent perspective without history context for precise review

The third core role is Reviewer, dedicated to code review. Why do we need a separate sub-agent for review instead of letting the agent that just wrote the code check itself? The core reason is that sub-agent and main Agent contexts are independent.

Reviewer: independently reviews code changes with a context-free, fresh perspective

When the main Agent has chatted with us in the same topic for a long time, learning lots of historical business info and implementation process, asking it to review the code it just wrote can easily follow its previous thinking inertia, making the review less accurate.

In contrast, a review sub-agent starts without that historical context interference. It can objectively and precisely review only the current code changes (e.g., checking for over-complication, extra defensive branches, unreasonable component splits, or reinventing wheels when existing libraries are available). And once the review sub-agent produces a problem list, the main Agent can use that feedback to directly fix the issues.

4. Specialized strength roles and Expert Advisor (copywriting and hard problem solving)

Besides the three core roles around code reading/writing, we can also configure two kinds of specialized sub-roles based on unique model strengths:

Specialized roles and Expert Advisor: strong copywriting, top reasoning models for hard architecture problems

5. Stringing roles together: "Explore before development + Simplify after completion" collaboration loop

After configuring all these roles, when handling complex tasks daily, the main Agent can string together Explorer, Executor, and Reviewer to naturally run a loop of "Exploration before development (Explore) + Review and simplify after completion (Simplify)" (this flow is also integrated into my open-source codex-team-mode):

Four-step collaboration loop of Explore before and Simplify after

  1. Before development, dispatch Explorer to Explore: For cross-directory or multi-module complex requirements, the main Agent first sends Explorer sub-agents in parallel to map out relevant code paths, bringing only key file locations and structural summaries back to the main context. Then the main Agent formulates a plan and hands it to Executor to implement.
  2. After completion, dispatch Reviewer to Simplify: Before committing, the main Agent automatically spawns a Reviewer sub-agent to independently check implementation quality and code reuse, cutting redundant branches and redundant code, only handing over the final result after confirming it's clean.

Dispatching other Agents as sub-agents

The three-layer config and role division we discussed mainly use the built-in native sub-agent mechanism of tools like Claude Code or Codex. But native sub-agents can usually only call models from their own vendor. If we want to directly dispatch another independent AI Agent as a sub-agent within one agent (e.g., in Claude Code, dispatch Codex to write code, or simultaneously schedule agents from different vendors), what's the simplest way?

Actually, the simplest way is to exploit the fact that AI Agents can execute commands: let it directly call another AI Agent's command-line tool (CLI), then wrap the calling rules and complex parameters in a Skill with built-in scripts:

Diagram: wrapping external Agent CLI as a sub-agent via Skill and built-in scripts

Specifically, this design concept has three progressive layers:

  1. Directly call the target Agent's CLI: Mainstream AI Agents (like Claude Code, Codex, Kimi CLI, etc.) basically provide command-line tools that accept a prompt in the terminal and execute the task. As long as a certain Agent has a CLI and the current main Agent can execute commands, the main Agent just runs one command in the terminal to delegate the task to another Agent.
  2. Wrap into a Skill so the main Agent remembers the calling rules: If we have to manually tell the main Agent how to type another Agent's command every time, it's too cumbersome. To make it more convenient, we can wrap this calling method into a Skill. In the description file SKILL.md, we write the target Agent CLI's calling format and trigger scenarios. Next time we trigger this Skill, the AI Agent will naturally know how to construct the command.
  3. Wrap scripts in the Skill to shield underlying call complexity: If we only rely on SKILL.md to have the main Agent assemble raw CLI commands on the spot, real calls to Codex or other AI Agents still have quite a bit of complexity. On one hand, different CLI tools have different read-only/permission parameters, working directories, and session continuation (session_id) syntax; the main Agent easily makes mistakes when assembling commands on the fly. On the other hand, during command-line execution, a lot of intermediate records like read file logs and JSON event streams get printed, and returning them directly would quickly fill the main topic's context.

Therefore, we can further wrap a script layer under the Skill's scripts/ directory to absorb all this complexity inside the script.

If you also want to use this mechanism directly in your workflow, or see how it's implemented, refer to my open-source oil-oil/oil-delegate on GitHub. It follows the design above, unifying CLI tools of multiple mainstream Agents including Claude Code, Codex, Antigravity, and Kimi Code:

Normally you don't need to memorize each vendor's command line. You just say something like "use cc to check the login flow in this repo" or "let codex fix this test" in the main Agent, and it will call the script to delegate the task to the corresponding Agent. Following the same idea, as long as an AI Agent provides a command line, you can turn it into a sub-agent under the main topic.

Practical pitfalls to avoid with sub-agents

Finally, based on my daily high-intensity use of sub-agents and the pitfalls I've stepped into, here are three most practical avoidance tips:

Three avoidance tips: Explorer with lightweight models, offset sub-thread overhead with model price gaps, simple small tasks done directly by main Agent

1. Explicitly specify the model when creating sub-agents to prevent inheriting the main thread's high-price model

I stepped on this pitfall myself early on: I forgot to check the model field when creating custom sub-agents. Many tools, when no model is explicitly specified, default to inheriting the high-price workhorse model currently used in the main topic.

This does nothing to save money—it only slightly slows down the main Agent's context expansion. The sub-agents are still using the high-price model to read dozens of files' tokens. So when creating retrieval or errand sub-agents, you must explicitly pin the cheapest sufficient lightweight tier in the config.

2. Sub-agents aren't necessarily money-saving; dispatching itself has extra token overhead

You should have a clear expectation: starting a sub-agent doesn't inherently equal saving money.

Because once you dispatch a sub-agent, your total token overhead will typically be higher than having a single Agent execute directly. The project standards and background info the main Agent already read often must be re-read by each newly started sub-agent. The main Agent outputs a prompt when dispatching, and the sub-agent outputs a summary report after execution. If you start three sub-agents simultaneously, those basic reads stack three times.

This extra token consumption is worth it only if you've configured a much cheaper model for the sub-agent, using the large price gap to offset the increased token count.

3. Simple tasks don't need sub-agents; a single main Agent doing it directly is better

Some tasks are very simple and clear (like changing copy or styles in one or two known files). In that case, let the current main Agent modify them directly.

If a simple small job that can be done in one or two steps still gets a sub-agent, the main Agent wastes time organizing dispatch prompts, spinning up the sub-agent, waiting for it to read files, and then returning results. Reserve sub-agents for tasks that truly generate lots of intermediate information, or genuinely need multi-path parallelism and independent review. That's the most comfortable usage.


Further reading and Oil Book free catalog

More AI Agent practical guides, model tests, and free engineering chapters are collected in Oil Book (book.oiloil.org). Original web version of this article: https://book.oiloil.org/articles/subagent-workflow.