Subagents

Subagents are specialized AI assistants that help you break down complex projects into smaller, focused tasks. Once you set up a subagent, you can reuse it across multiple projects and even share it with your team, ensuring everyone works the same way.

Add a subagent to your application

Create a subagents directory in your project.

.builder/agents/

Add a .md file to the .builder/agents/ directory, with an appropriate name for your subagent. For example, if you were creating a subagent to review code, you might make a code-reviewer.md file.

.builder/agents/code-reviewer.md

Your markdown file should include YAML frontmatter that defines your subagent. Fill in the file with instructions for how the agent should act.

--- name: code-reviewer description: Expert code reviewer. Use immediately after writing or modifying code. tools: Read, Grep, Glob, Bash model: sonnet --- You are a senior code reviewer ensuring high standards of code quality. When invoked: 1. Run git diff to see recent changes 2. Focus on modified files 3. Begin review immediately Review checklist: - Code is simple and readable - Proper error handling - No exposed secrets or API keys - Good test coverage

Builder will automatically discover and use your subagent when appropriate, or you can explicitly reference your subagent in the chat. For example:

Use the code-reviewer sub-agent to check my recent changes.

Other subagent locations

Builder will also discover and use subagents created for other popular AI tools. Subagents will be accessed from any of the following directories:

.builder/agents/ .claude/agents/ .cursor/agents/

Effectively use your subagent

Builder proactively delegates tasks based on the task description in your request and the description field in subagent configurations.

To encourage more proactive use, include phrases like "use proactively" or "use immediately after [action]" in your description field.

When explicitly invoking the subagent, use the subagent's name as part of the request. For example:

"Use the test-runner subagent to fix failing tests."
"Have the code-reviewer subagent look at my recent changes."
"Ask the debugger subagent to investigate this error."

Chain subagents

For complex workflows, you can chain multiple by referencing subagents within the main content of the subagent markdown file.

First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

Subagent examples

A few subagent examples are listed below. Use these as starting points for creating your own subagents.

--- name: code-reviewer description: Expert code review specialist. Use immediately after writing or modifying code. tools: Read, Grep, Glob, Bash model: inherit --- You are a senior code reviewer ensuring high standards of code quality and security. When invoked: 1. Run git diff to see recent changes 2. Focus on modified files 3. Begin review immediately Review checklist: - Code is simple and readable - Functions and variables are well-named - No duplicated code - Proper error handling - No exposed secrets or API keys - Good test coverage Provide feedback organized by priority: - Critical issues (must fix) - Warnings (should fix) - Suggestions (consider improving)

--- name: debugger description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues. tools: Read, Edit, Bash, Grep, Glob model: sonnet --- You are an expert debugger specializing in root cause analysis. When invoked: 1. Capture error message and stack trace 2. Identify reproduction steps 3. Isolate the failure location 4. Implement minimal fix 5. Verify solution works For each issue, provide: - Root cause explanation - Evidence supporting the diagnosis - Specific code fix - Prevention recommendations

--- name: browser-testing description: Browser automation testing for visual and functional testing tools: mcp:chrome, ServerLogs, RecordFrame model: haiku needDevServer: true needValidation: true --- You are a browser automation testing agent. Your role: 1. Navigate to pages and interact with UI elements 2. Capture screenshots and record visual states 3. Validate page content and functionality 4. Report issues found during testing

Frontmatter configuration

The YAML inserted at the beginning of each subagent can be customized in the following ways:

Field	Required	Description
`name`	Yes	Unique identifier using lowercase letters and hyphens.
`description`	Yes	When the subagent should be used. A clear description is critical for automatic delegation.
`tools`	No	A comma-separated list of tools. Inherits all tools if omitted. See below for a list of available tools.
`model`	No	The name of the model you wish to use for the subagent's action, written in kebab-case. For example, `sonnet` or `gpt5-codex`.
`includeMemories`	No	Include the current conversation's memories within the subagent's context. Defaults to `true`.
`needDevServer`	No	Requires a running development server. Defaults to `false`.
`needValidation`	No	Validate the subagent's output before returning to the user. Defaults to `false`.

Available tools

Subagents can make use of the following tools.

Category	Tools
File operations	`Read`, `Write`, `Edit`, `Glob`, `Grep`, `LS`
Execution	`Bash`
Information	`WebSearch`, `ReadRule`
MCP servers	Use the `mcp:` prefix. For example, use `mcp:chrome` for browser automation.
Agent-specific	`ServerLogs`, `RecordFrame`

Best practices

Keep in mind the following when designing and using subagents.

Design focused subagents with single, clear responsibilities rather than trying to make one subagent do everything.
Write detailed prompts with specific instructions, examples, and constraints.
Only grant tools necessary for the subagent's purpose.
Check project subagents into version control so your team can collaborate on them.
If a subagent isn't being used automatically, make the description more specific and actionable.

It's important to note that, subagents help preserve main context, enabling longer overall sessions. However, subagents start with a clean slate each time and may add latency as they gather the context they need.

What's next

Continue configuring Builder's AI output with AGENTS.md files or agent skills.

Was this article helpful?