Subagents

Subagents let you create specialized AI agents tailored to specific tasks in your project. Instead of working with a general-purpose AI, you can define agents with specific expertise, restrict what tools they can access, and use them to handle specialized work—like security audits, documentation, or code review.

Why Use Subagents?

Focused expertise:

• Create a security-focused agent that only reviews for vulnerabilities
• Make a documentation agent that specializes in clear, comprehensive docs
• Build a test specialist that runs tests and analyzes failures

Better control:

• Give some agents access to bash and file editing, but not others
• Create read-only agents for code review that can’t modify files
• Prevent agents from accidentally breaking things by restricting permissions

Organized workflow:

• Coordinate multiple agents working on different aspects of a task
• Have agents delegate work to other specialists
• Build workflows where agents hand off work to each other

Consistency:

• Reuse the same agent definition across multiple threads
• Keep specialized agents’ instructions consistent
• Share agents globally or keep them project-specific

Quick Start

Create a Simple Agent

In your thread, create a new agent file at .agents/agents/code-reviewer/AGENT.md:

---
name: code-reviewer
description: Review code for quality and best practices
---

You are an expert code reviewer. When reviewing code:
- Look for readability and maintainability issues
- Check for potential bugs and edge cases
- Suggest improvements to performance or clarity
- Point out violations of best practices
- Be constructive and specific with feedback

That’s it! You now have a code-reviewer agent.

Use Your Agent

In a conversation, ask the AI to use your agent:

Please use the code-reviewer agent to review the authentication module.

Or invoke it directly:

agent({
  prompt: "Review the authentication module for security and quality issues",
  agentName: "code-reviewer"
})

The agent will analyze your code using its specialized instructions and provide focused feedback.

Creating Agents

Agent Files

Agents live in your project at .agents/agents/{name}/AGENT.md. Each agent file has two parts:

Configuration (frontmatter):

---
name: my-agent
description: What this agent does
---

Instructions (everything after ---):

You are a specialized expert. Your job is to...

Configuration Options

Option	What It Does	Example
name	Agent identifier	code-reviewer, security-auditor, doc-writer
description	Brief description (shown in agent picker)	Review code for quality and best practices
tools	Which tools the agent can use (space-separated)	read grep bash
agents	Which other agents this agent can spawn	[code-reviewer, test-runner]
disable-model-invocation	Hide from agent picker (internal helper)	true or false

Most of the time you only need name and description.

Common Agent Types

Code Reviewer

• Tools: read grep (can read files but not modify)
• Good for: Providing feedback without making changes
• Instructions: Focus on code quality, maintainability, bugs

Security Auditor

• Tools: read grep bash (can run commands to test)
• Good for: Checking for vulnerabilities
• Instructions: Look for auth issues, injection vulnerabilities, credential handling

Documentation Writer

• Tools: read grep (read code to document it)
• Good for: Generating docs from code
• Instructions: Create clear, comprehensive documentation with examples

Test Runner

• Tools: bash read (run tests but don’t modify code)
• Good for: Running tests and analyzing results
• Instructions: Run the test suite, analyze failures, suggest fixes

Using Your Agents

Invoke in Chat

Simply mention using the agent:

Can you use the security-auditor agent to review the login flow for vulnerabilities?

Use the Agent Tool

Call the agent directly:

agent({
  prompt: "Audit the database connection pool for security issues",
  agentName: "security-auditor"
})

Chain Agents Together

Create an orchestrator agent that delegates work:

---
name: project-lead
description: Coordinate multiple specialist agents
agents: [code-reviewer, security-auditor, test-runner]
---

You coordinate a team of specialist agents:
- code-reviewer: Reviews code quality
- security-auditor: Checks for security issues
- test-runner: Runs tests and analyzes failures

When given a task, delegate to the appropriate agents and synthesize their findings.

Restricting Tool Access

By default, agents get all available tools. Restrict what they can do by listing allowed tools:

Read-only agent (can’t modify):

---
name: code-reviewer
description: Review code for quality
tools: read grep
---

Command-only agent (can run bash but not edit):

---
name: test-runner
description: Run tests and report results
tools: bash read
---

Edit-only agent (very restricted):

---
name: formatter
description: Format code according to style guide
tools: read edit bash
---

Managing Agents

View Your Agents

All agents in .agents/agents/ are available. You’ll see them:

• In the agent picker when you ask the AI to use one
• In your project’s thread directory

Edit an Agent

Open .agents/agents/{agent-name}/AGENT.md and update:

• The instructions (everything after frontmatter)
• The configuration fields

Changes take effect immediately.

Delete an Agent

Delete the .agents/agents/{agent-name}/ directory, and the agent disappears from the picker.

Share Agents Across Projects

Put agents in ~/.agents/agents/{name}/AGENT.md to make them available globally. Project-specific agents in .agents/agents/ override global ones with the same name.

Practical Examples

Security Audit Agent

---
name: security-auditor
description: Security-focused code review
tools: read grep bash
---

You are a security expert. When analyzing code, focus on:

- **Authentication & Authorization:** Session handling, token validation, permission checks
- **Data Validation:** Input sanitization, type checking, bounds validation
- **Injection Attacks:** SQL injection, command injection, XSS, template injection
- **Secrets Management:** Hardcoded credentials, key storage, environment variables
- **Cryptography:** Weak algorithms, insecure random number generation
- **Error Handling:** Information leakage through error messages

Be thorough, specific, and explain the security impact of each issue.

API Documentation Agent

---
name: api-documenter
description: Generate API documentation
tools: read grep
---

You are a technical writer specializing in API documentation.

Generate comprehensive documentation including:
1. **Overview** - High-level purpose and use cases
2. **Endpoints** - List all endpoints with HTTP method and path
3. **Request/Response** - Show examples for each endpoint
4. **Error Codes** - Document status codes and error messages
5. **Authentication** - Explain how to authenticate
6. **Rate Limiting** - Note any limits
7. **Examples** - Provide curl and code examples

Use clear language and structure with proper formatting.

Code Quality Orchestrator

---
name: quality-lead
description: Coordinate code quality checks
agents: [code-reviewer, security-auditor, test-runner]
---

You oversee code quality across multiple dimensions.

When reviewing code, coordinate with your specialist agents:
1. Ask code-reviewer to assess code quality and maintainability
2. Ask security-auditor to check for vulnerabilities
3. Ask test-runner to verify tests pass

Compile their findings into a comprehensive quality report.

Best Practices

Create agents for recurring needs:

• If you frequently need security reviews, create a security-auditor
• If you often write documentation, create a doc-writer
• If tests are important, create a test-runner

Use focused instructions:

• Give agents clear, specific guidance on what to focus on
• Avoid vague instructions like “review the code”
• Be specific: “Check for SQL injection vulnerabilities and authentication issues”

Restrict tools appropriately:

• Review agents don’t need edit or bash (use read grep)
• Test runners don’t need edit (use bash read)
• Give agents only the tools they actually need

Start simple:

• Create agents for one specific purpose
• Expand to more complex agents once you understand the pattern
• You can always modify an agent’s instructions later

Document your agents:

• Use clear names: security-auditor not agent2
• Provide helpful descriptions in the description field
• These show up in the agent picker to help you choose the right agent

Limitations

• Max 2 levels of nesting: A main agent can invoke subagents, and those subagents can invoke others, but it stops there (prevents infinite loops)
• Agent availability: Agents only exist in the project where they’re defined, unless you move them to your global agents folder