subagent-best-practices

To define a SubAgent, you create an agents/*.md file with strict YAML frontmatter conventions, specifying tools, name, and description. This skill provides templates and rules to ensure your SubAgent definitions are robust, safe, and auditable.

The 3-Phase workflow structure is a standardized design pattern for SubAgent definitions that separates tasks into distinct phases. This skill guides you through structuring prompts, handling edge cases, and managing failures within this framework to ensure reliable agent behavior.

Common SubAgent anti-patterns include improper context passing, incorrect tool selection, and poorly structured prompts. This skill identifies these anti-patterns and provides best practices and checklists to avoid them and ensure safe, auditable agent definitions.

Context passing between agents requires following specific patterns to ensure the SubAgent receives the necessary information. This skill provides recommended context-handling patterns and workarounds for MCP considerations to maintain data integrity.

Tool selection for a SubAgent involves choosing the specific tools the agent needs to perform its task safely. This skill covers best practices for tool selection within the YAML frontmatter, ensuring the agent has appropriate permissions without being overly broad.

You should avoid using a SubAgent when the task does not require isolation, specialized tool access, or a distinct context window. This skill outlines limitations and helps you determine when a SubAgent is necessary versus when a simpler approach is better.