Writing Subagent Prompts
Anatomy of an effective subagent: Role, Boundaries, Output Format, Tools, Model, Error Handling.
The quality of your multi-agent system is directly proportional to the quality of your subagent prompts. A well-written subagent prompt produces reliable, consistent, high-quality output every time. A vague one produces chaos that your orchestrator can't manage. This lesson is about writing subagent prompts that work.
Every subagent prompt has six sections, and boundaries is the most important one. Yes, more important than the role itself. Here's why: an AI model will try to be helpful. If you define a researcher but don't set boundaries, it will try to also write, edit, format, publish, and promote. Boundaries prevent scope creep. Explicitly state what the agent does AND what it does NOT do.
Role defines the agent's identity and expertise. Be specific. "You are a technical researcher who finds API documentation, library comparisons, and implementation examples. You specialize in JavaScript/TypeScript ecosystems." The more specific, the more focused the output.
Boundaries are the guardrails. "You ONLY research. You do not write final content. You do not make technology decisions. You present findings and let the orchestrator decide." These constraints prevent the agent from overstepping and producing work that conflicts with other subagents.
Output Format standardizes how the agent returns work. "Return findings as: Summary (3 sentences), Sources (linked list), Key Data Points (bulleted), Recommendation (1 paragraph)." When every subagent returns structured output, the orchestrator can reliably parse and compile results.
Tools specifies which tools this agent can use. A researcher might get web search and file read. A writer might get file write only. A code reviewer might get file read and bash (for running tests). Restrict tools to what the role requires.
Error Handling defines what happens when things go wrong. "If you cannot find information on the topic, say 'INSUFFICIENT DATA: [reason]' instead of guessing." This prevents the agent from hallucinating when it should be raising a flag.
Walkthrough
- 1Open one of your subagent files from the previous lesson
- 2Add a clear Role section: 2-3 sentences defining identity and expertise area
- 3Add a Boundaries section: list at least 5 things this agent does NOT do
- 4Add an Output Format section: define the exact structure of every response
- 5Add a Tools section: list which tools this agent should use and when
- 6Add an Error Handling section: define the agent's behavior when it can't complete a task
- 7Optional — add a Model section: specify which AI model this agent should use (enables cost optimization later)
- 8Test the subagent by running it with a sample task and verifying the output matches your format spec
Checkpoint
Your subagent prompts include all six sections (Role, Boundaries, Output Format, Tools, Model, Error Handling). Boundaries explicitly state what the agent does NOT do. Output format is structured and consistent.