Creating Custom Subagents

This skill guides you through creating custom subagents for Cursor. Subagents are specialized AI assistants that run in isolated contexts with custom system prompts.

When to Use Subagents

Subagents help you:

• Preserve context by isolating exploration from your main conversation
• Specialize behavior with focused system prompts for specific domains
• Reuse configurations across projects with user-level subagents

Subagent Locations

| Location | Scope | Priority | |----------|-------|----------| | .cursor/agents/ | Current project | Higher | | ~/.cursor/agents/ | All your projects | Lower |

When multiple subagents share the same name, the higher-priority location wins.

Subagent File Format

Create a .md file with YAML frontmatter and a markdown body (the system prompt):

markdown
---
name: code-reviewer
description: Reviews code for quality and best practices
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Required Fields

| Field | Description | |-------|-------------| | name | Unique identifier (lowercase letters and hyphens only) | | description | When to delegate to this subagent (be specific!) |

Writing Effective Descriptions

yaml
# Too vague
description: Helps with code

# Specific and actionable
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.

Include "use proactively" to encourage automatic delegation.

Example Subagents

Code Reviewer

markdown
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
---

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

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Debugger

markdown
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
---

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

Data Scientist

markdown
---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Analyze and summarize results
4. Present findings clearly

Subagent Creation Workflow

1. Decide the Scope: Project-level (.cursor/agents/) or User-level (~/.cursor/agents/)
2. Create the File: .md file with YAML frontmatter
3. Define Configuration: name and description in frontmatter
4. Write the System Prompt: Be specific about what, how, and output format
5. Test the Agent: Ask the AI to use your new agent

Best Practices

1. Design focused subagents: Each should excel at one specific task
2. Write detailed descriptions: Include trigger terms so the AI knows when to delegate
3. Check into version control: Share project subagents with your team
4. Use proactive language: Include "use proactively" in descriptions