- Carefully define a sub-agent's name and description to precisely control when the main agent launches it and how it instructs the sub-agent.
- Specifying an explicit output format for sub-agents in their system prompt creates natural stopping points and improves efficiency.
- Restrict sub-agent tool access to only what is necessary for its function, such as
read-onlyfor research tasks, to prevent unintended side effects and clarify its role.
Designing effective subagents
- Modify a sub-agent's name and description to better control when the main agent automatically launches it.
- Use the sub-agent's description to guide the main agent in writing more precise input prompts for the sub-agent.
- Define an output format in the sub-agent's system prompt to give it clear stopping points and prevent it from running longer than necessary.
- Include explicit requests for obstacle reporting in the output format to surface workarounds, setup issues, or special command flags discovered by sub-agents.
- Make sub-agents
read-only(e.g., usingglob,grep,read) if their role is solely research, preventing accidental file modifications. - Only grant
editandwritepermissions to sub-agents that are specifically designed to modify code, such as a styling agent.
sub-agent — A specialized, subordinate agent that performs specific tasks under the direction of a main agent.
main context window agent — The primary, orchestrating agent that manages the overall task, delegates to sub-agents, and maintains the conversation context.
system prompt — Initial instructions given to an AI model that define its role, constraints, and often its expected output format.
input prompt — The specific instruction or query provided to an agent (or sub-agent) to initiate a particular action or task.
output format — A predefined structure or schema that an agent is instructed to use when presenting its results or findings.
glob — A pattern used to match multiple filenames or paths, often in shell commands (e.g., *.txt).
grep — A command-line utility used to search for specific patterns of text within files.
read-only — A permission level that allows an entity (like an agent) to view or access data but not modify, delete, or create new data.
bash access — The capability for an agent to execute commands directly within a Bash shell environment.
Now that you know how to create sub aents, let's look at patterns that lead to effective sub aents. First, let's get a better idea of how subit data in the sub aent config file is used. Whenever you send a message to the main context window agent, the name and description of each sub aent is included in the system prompt. So, if you want to better control when the main agent launches a sub agent automatically, you should modify the name and description. Next, remember that when a sub agent is launched, the main agent writes an input prompt. When writing this input prompt, it uses the description as guidance. So, if you want to better control when the main agent launches a sub agent automatically, you should modify the name and description. Let's consider our review sub aent again. Right now, when the main agent runs this sub agent, the sub aent is given an input prompt telling it to use get diff to find the current changes. If we wanted the main agent to more reliably tell the sub agent exactly which files to review, we would update the description. You must tell the agent precisely which files you want it to review. Now, if we ask claw to run the code reviewer agent, we'll see a different input. You can also influence what the main thread tells a sub agent through the description. So adding return sources that can be cited to a web search sub aents description causes the main thread to include that instruction when delegating the task. The most important improvement that you can make is defining an output format in the system prompt. This creates natural stopping points for the sub aent. Without a defined output format, sub aents struggle to decide when enough research has been done and they tend to run much much longer than sub agents that are given an output format. When a sub agent discovers a workaround to some issue like solving a dependency issue or finding that a certain command needs particular flags, these details should appear in the summary. Otherwise, the main thread has to rediscover the same solutions, obstacles encountered, any setup issues, workarounds discovered or environment quirks, commands that needed special flags or configuration, dependencies or imports that cause problems. Explicitly asking for obstacle reporting in the output format surfaces this information. A readonly sub aent using just glob grap read cannot accidentally modify files. This constraint clarifies that the sub aents role and prevents unintended side effects. So think about what sub aents actually needs to do. If it's just researching it only needs to read files. So keep it read only. That way it can't accidentally modify anything while exploring. A reviewer needs to run get diff to see what changed. So give it bash access, but it still doesn't need to edit files. Only give edit and write to sub aents that should actually change your code, like a styling agent applying CSS updates. This also helps clarify what each sub aent is for when you have several of them. So effective sub aents use structured output report obstacles have specific descriptions and limit tool access.
TL;DR
- Carefully define a sub-agent's name and description to precisely control when the main agent launches it and how it instructs the sub-agent.
- Specifying an explicit output format for sub-agents in their system prompt creates natural stopping points and improves efficiency.
- Restrict sub-agent tool access to only what is necessary for its function, such as
read-onlyfor research tasks, to prevent unintended side effects and clarify its role.
Takeaways
- Modify a sub-agent's name and description to better control when the main agent automatically launches it.
- Use the sub-agent's description to guide the main agent in writing more precise input prompts for the sub-agent.
- Define an output format in the sub-agent's system prompt to give it clear stopping points and prevent it from running longer than necessary.
- Include explicit requests for obstacle reporting in the output format to surface workarounds, setup issues, or special command flags discovered by sub-agents.
- Make sub-agents
read-only(e.g., usingglob,grep,read) if their role is solely research, preventing accidental file modifications. - Only grant
editandwritepermissions to sub-agents that are specifically designed to modify code, such as a styling agent.
Vocabulary
sub-agent — A specialized, subordinate agent that performs specific tasks under the direction of a main agent.
main context window agent — The primary, orchestrating agent that manages the overall task, delegates to sub-agents, and maintains the conversation context.
system prompt — Initial instructions given to an AI model that define its role, constraints, and often its expected output format.
input prompt — The specific instruction or query provided to an agent (or sub-agent) to initiate a particular action or task.
output format — A predefined structure or schema that an agent is instructed to use when presenting its results or findings.
glob — A pattern used to match multiple filenames or paths, often in shell commands (e.g., *.txt).
grep — A command-line utility used to search for specific patterns of text within files.
read-only — A permission level that allows an entity (like an agent) to view or access data but not modify, delete, or create new data.
bash access — The capability for an agent to execute commands directly within a Bash shell environment.
Transcript
Now that you know how to create sub aents, let's look at patterns that lead to effective sub aents. First, let's get a better idea of how subit data in the sub aent config file is used. Whenever you send a message to the main context window agent, the name and description of each sub aent is included in the system prompt. So, if you want to better control when the main agent launches a sub agent automatically, you should modify the name and description. Next, remember that when a sub agent is launched, the main agent writes an input prompt. When writing this input prompt, it uses the description as guidance. So, if you want to better control when the main agent launches a sub agent automatically, you should modify the name and description. Let's consider our review sub aent again. Right now, when the main agent runs this sub agent, the sub aent is given an input prompt telling it to use get diff to find the current changes. If we wanted the main agent to more reliably tell the sub agent exactly which files to review, we would update the description. You must tell the agent precisely which files you want it to review. Now, if we ask claw to run the code reviewer agent, we'll see a different input. You can also influence what the main thread tells a sub agent through the description. So adding return sources that can be cited to a web search sub aents description causes the main thread to include that instruction when delegating the task. The most important improvement that you can make is defining an output format in the system prompt. This creates natural stopping points for the sub aent. Without a defined output format, sub aents struggle to decide when enough research has been done and they tend to run much much longer than sub agents that are given an output format. When a sub agent discovers a workaround to some issue like solving a dependency issue or finding that a certain command needs particular flags, these details should appear in the summary. Otherwise, the main thread has to rediscover the same solutions, obstacles encountered, any setup issues, workarounds discovered or environment quirks, commands that needed special flags or configuration, dependencies or imports that cause problems. Explicitly asking for obstacle reporting in the output format surfaces this information. A readonly sub aent using just glob grap read cannot accidentally modify files. This constraint clarifies that the sub aents role and prevents unintended side effects. So think about what sub aents actually needs to do. If it's just researching it only needs to read files. So keep it read only. That way it can't accidentally modify anything while exploring. A reviewer needs to run get diff to see what changed. So give it bash access, but it still doesn't need to edit files. Only give edit and write to sub aents that should actually change your code, like a styling agent applying CSS updates. This also helps clarify what each sub aent is for when you have several of them. So effective sub aents use structured output report obstacles have specific descriptions and limit tool access.