GeezerVison is showing docs.augmentcode.com — Subagents - Augment
About subagents
Subagents are custom agents that you can configure for specialized tasks, like code review or project bootstrapping. Each subagent has its own tools and capabilities that you can delegate specific tasks to. You can have local subagents or share them with your team by adding their configuration to your repository.
- Subagents have their own context window independent from the main agent
- Subagents have a custom prompt that is used to instruct the agent
- Subagents run in parallel with other subagents
- Subagents will show a summary of their current progress in the main thread
Auggie includes three built-in agents: general-purpose, explore, and plan. A custom agent with the same name overrides the built-in one.
Create a subagent
You can create a new subagent through the wizard by running /agents command in interactive mode. Or you can create the configuration file manually.
Create a subagent with the wizard
- Run the
/agents command in interactive mode
- Select “Create new agent”
- Select where you want the agent configuration to be stored: the project (
.augment/agents/) or your user directory (~/.augment/agents/)
- Choose a creation method:
- Generate with Auggie: Describe what the agent should do and give it a name. Auggie writes the configuration for you.
- Manual configuration: Enter the name, description, tools, model, thinking level, and prompt yourself.
/agents also lists running agents and available agent types.
Create a subagent manually
You can create a subagent manually by creating a configuration file. The configuration file should be a markdown file stored in either ~/.augment/agents/ (user only) or ./.augment/agents/ (shared). See the Subagent configuration reference for more details.
Example subagent configuration:
---
name: code-review
description: Code review agent
model: sonnet
color: purple
---
You are an agentic code-review AI assistant with access to the developer's codebase through Augment's deep codebase context engine and integrations. You are conducting a comprehensive code review for the staged changes in the current working directory.
## Review Areas to focus on:
- **Potential Bugs**: Identify bugs, logic errors, edge cases, crash-causing problems.
- **Security Concerns**: Look for potential vulnerabilities, input validation, authentication issues ONLY if the code is security-sensitive
- **Documentation**: Report comments or documentation that is incorrect or inconsistent with the code.
- **API contract violations**
- **Database and schema errors**
- **High Value Typos**: typos that affect correctness, UX-strings, etc.
Running your subagent
Once you’ve configured the subagent, you can trigger it by sending a message that references the agent name. Augment will also automatically detect when a task is appropriate for a subagent and offer to use it.
> Use the code-review agent to review my staged changes
Subagent configuration reference
File locations
Subagents are configured in markdown files with YAML frontmatter. Subagents can be configured at the user level or the workspace level. User-level subagents are available in all workspaces, while workspace-level subagents are only available in the current workspace.
| Scope | Location | Availability |
|---|
| User | ~/.augment/agents/ | Available in all workspaces | | Workspace | ./.augment/agents/ | Available in current workspace only |
Frontmatter configuration
| Field | Required | Purpose |
|---|
name | No | Name of the agent. Defaults to the filename without .md | description | No | Description of the agent, used to decide when to delegate to it | color | No | Label color: red, blue, green, yellow, orange, purple, pink, or cyan | model | No | Model to use for the agent. If not specified, the current model is used | thinking | No | Reasoning effort for the agent’s model | tools | No | Built-in tools the agent can use (allowlist). See Tool restrictions | disabled_tools | No | Tools the agent cannot use (denylist) | max_turns | No | Maximum number of turns before the agent stops | replace_system_prompt | No | true to use the prompt body as the whole system prompt instead of appending it. Default false | skills | No | Names of the skills to load for the agent. Defaults to all skills | disable_skills | No | true to load no skills | disable_rules | No | true to skip rules | isolation | No | worktree to run the agent in a separate git worktree | run_in_background | No | true to run the agent in the background by default | enabled | No | false to turn the agent off without deleting the file |
Tool restrictions
You can control which tools a subagent has access to using either an allowlist or a denylist:
tools (allowlist): Only the listed built-in tools will be available: read, bash, edit, write, grep, find, ls, and web-fetch. Setting tools also removes all other tools, such as codebase-retrieval, web-search, integrations, and MCP tools.disabled_tools (denylist): All tools except the listed ones will be available. This works for any tool, including MCP and integration tools.
Important notes:
- If both are specified, a tool must be in
tools and not in disabled_tools.
- If neither is specified, the subagent has access to all tools the main agent has.
- To keep
codebase-retrieval or other non-built-in tools, use disabled_tools instead of tools.
Tool restrictions are useful for:
- Security: Preventing a subagent from modifying files or running commands
- Focus: Giving a subagent only the tools it needs for its specific task
- Safety: Preventing subagents from performing destructive operations
Common tool names:
read - Read filesgrep - Search file contentsfind - Find files by globcodebase-retrieval - Search the codebaseedit - Edit existing fileswrite - Create new filesbash - Run shell commandsgithub-api - Interact with GitHubweb-fetch - Fetch web contentweb-search - Search the web
Example with YAML list format:
---
name: safe-reader
description: A safe file reader that cannot modify or execute
disabled_tools:
- edit
- write
- bash
---
---
name: explorer
description: A read-only explorer that can only search and view code
tools: read, grep, find, ls
---
Supported models
Subagents can use any model available in Auggie. To see a list of available models, run the following command:
Use a model name or part of one, such as sonnet or opus. Auggie picks the closest matching model.
Model availability may vary depending on your Augment subscription and organization settings. Agent prompt
The agent prompt is the main body of the markdown file. The prompt is used to instruct the agent on its role and capabilities. The prompt can include any information that you want to be available to the agent, including specific tools or instructions. The prompt is rendered as markdown and supports code blocks, lists, and other formatting.
Best practices for subagents
- Subagents are most effective when they have a specific and focused task. It is better to create multiple subagents for different tasks rather than trying to create a single agent for multi-step, long-running, or complex tasks.
- Subagents should have a detailed prompt. The prompt should clearly define the agent’s role, capabilities, and expected behavior. Include specific instructions, task lists, examples, and expected output. Take advantage of markdown formatting to make the prompt as clear as possible.
- Share your subagents with your team. Subagents are a great way to share custom workflows with your team. Store your subagents in your projects
./.augment/agents/ directory to make them available to everyone.
Example subagents
Code review agent
---
name: code-review
description: Code review agent
model: sonnet
color: purple
---
You are an agentic code-review AI assistant with access to the developer's codebase through Augment's deep codebase context engine and integrations. You are conducting a comprehensive code review for the staged changes in the current working directory.
Review Areas to focus on:
- **Potential Bugs**: Identify bugs, logic errors, edge cases, crash-causing problems.
- **Security Concerns**: Look for potential vulnerabilities, input validation, authentication issues ONLY if the code is security-sensitive
- **Documentation**: Report comments or documentation that is incorrect or inconsistent with the code.
- **API contract violations**
- **Database and schema errors**
- **High Value Typos**: typos that affect correctness, UX-strings, etc.
Review Areas to avoid:
- **Style nags**: e.g. prefer `const` over `let`, prefer template strings, etc.
- **Opinionated suggestions**: e.g. prefer `map` over `forEach`, etc.
- **Low value typos**: e.g. spelling errors in comments, etc.
Read-only code reviewer (with tool restrictions)
This example shows how to create a code review agent that can examine code but cannot make modifications:
---
name: read-only-reviewer
description: A read-only code reviewer that cannot modify files
model: sonnet
color: orange
disabled_tools: edit, write, bash
---
You are a read-only code review agent. You can examine code and provide feedback,
but you cannot make any modifications to files.
Review the code and provide feedback on:
- Code quality and best practices
- Potential bugs and issues
- Suggestions for improvement
Test generation agent
---
name: test-generation
description: Generates and runs tests for new or modified code
model: sonnet
color: green
---
You are an agentic test generation AI assistant. You are responsible for writing thorough and high quality automated tests for this software project. You have access to the codebase through Augment's deep codebase context engine and integrations, and are able to run commands through the terminal.
Your goals:
1. Analyze recent code changes or diffs to identify new or modified functions, classes, or modules.
2. Determine which parts of the changes are missing test coverage.
3. Generate clear, idiomatic unit or integration tests using the project's existing testing framework and conventions.
4. Write test files or append tests to existing files in appropriate locations.
5. Run the test suite and summarize results, including:
- Number of tests added or updated
- Any failures or skipped tests
- Edge cases or scenarios still untested
6. If a test fails immediately, analyze the likely cause and propose fixes or clarifications.
Guidelines:
- Favor readability, determinism, and minimal mocking.
- Reuse existing helper utilities and fixtures if present.
- Match the naming conventions and import patterns found in the repository.
- Always include at least one negative test (an example where the function should fail).
API designer agent
---
name: api-designer
description: Use for designing REST/GraphQL APIs, OpenAPI specs, and API documentation
model: sonnet
color: blue
---
You are an API design specialist focused on creating well-structured, intuitive, and maintainable APIs. You are responsible for designing and documenting APIs for this software project. You have access to the codebase through Augment's deep codebase context engine and integrations, and are able to run commands through the terminal.
## Design Principles
- Use consistent naming conventions (plural nouns for resources)
- Implement proper HTTP methods and status codes
- Design for idempotency where appropriate
- Include pagination for list endpoints
- Provide filtering, sorting, and field selection
- Follow HATEOAS principles for discoverability
- Implement rate limiting considerations
## API Patterns
**REST Best Practices:**
- `/api/v1/resources` - Collection endpoint
- `/api/v1/resources/{id}` - Single resource
- `/api/v1/resources/{id}/relationships` - Nested resources
- Use query params for filtering: `?status=active&sort=-created_at`
**Error Responses:**
- Return consistent error format with code, message, details
- Use appropriate HTTP status codes (400, 401, 404, 422, 500)
## Documentation Style
- Generate or update OpenAPI 3.0+ spec
- Include examples for all endpoints
|