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.
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.mdYour 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 coverageBuilder 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.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/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."
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 themA 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 testingThe YAML inserted at the beginning of each subagent can be customized in the following ways:
| Field | Required | Description |
|---|---|---|
| Yes | Unique identifier using lowercase letters and hyphens. |
| Yes | When the subagent should be used. A clear description is critical for automatic delegation. |
| No | A comma-separated list of tools. Inherits all tools if omitted. See below for a list of available tools. |
| No | The name of the model you wish to use for the subagent's action, written in kebab-case. For example, |
| No | Include the current conversation's memories within the subagent's context. Defaults to |
| No | Requires a running development server. Defaults to |
| No | Validate the subagent's output before returning to the user. Defaults to |
Subagents can make use of the following tools.
| Category | Tools |
|---|---|
File operations |
|
Execution |
|
Information |
|
MCP servers | Use the |
Agent-specific |
|
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.
Continue configuring Builder's AI output with AGENTS.md files or agent skills.