Creating Custom AI Modes in Cursor for Specialized Tasks

Cursor v0.48+ introduced Custom Modes, allowing you to create specialized AI configurations for different tasks. Instead of using the same AI behavior for everything, you can define modes with specific tools, models, prompts, and settings. This guide shows you how to create and use custom modes effectively.

What are Custom Modes?

Custom Modes let you:

• Define specialized behaviors for different tasks (coding, debugging, reviewing)
• Restrict tool access per mode (e.g., review mode = read-only)
• Set default models per mode (e.g., Claude for analysis, GPT for speed)
• Configure system prompts tailored to specific workflows
• Switch contexts instantly without rewriting instructions

Built-in Modes

Cursor comes with several built-in modes:

Mode	Purpose	Default Model
Ask	Q&A about code	Claude 3.5 Sonnet
Edit	Code modifications	GPT-4o
Agent	Autonomous task execution	Claude 3.5 Sonnet
Composer	Multi-file editing	Claude 3.5 Sonnet

Creating Your First Custom Mode

Step 1: Open Mode Settings

1. Press Cmd/Ctrl + K to open Composer
2. Click the mode selector (top of Composer)
3. Select "Manage Modes" or go to Settings

Step 2: Create a New Mode

{
  "name": "Code Reviewer",
  "description": "Read-only code review mode with security focus",
  "systemPrompt": "You are a senior code reviewer. Your job is to review code for quality, security, and best practices. You can READ files but NEVER modify them. Focus on: 1) Security vulnerabilities, 2) Performance issues, 3) Code smells, 4) Missing tests, 5) Documentation gaps. Provide specific, actionable feedback with line references.",
  "model": "claude-3-5-sonnet",
  "temperature": 0.1,
  "tools": {
    "read": true,
    "write": false,
    "edit": false,
    "shell": false,
    "grep": true,
    "search": true
  },
  "contextWindow": 200000
}

Step 3: Save and Use

1. Click Save Mode
2. The mode appears in your mode selector
3. Switch to it anytime from Composer

Example Custom Modes

1. Security Auditor Mode

{
  "name": "Security Auditor",
  "description": "Focused on finding security vulnerabilities",
  "systemPrompt": "You are a security auditor specializing in web application security. Analyze code for: SQL injection, XSS, CSRF, authentication flaws, insecure dependencies, hardcoded secrets, improper input validation, and privilege escalation. Rate each finding as Critical, High, Medium, or Low. Suggest specific fixes with code examples.",
  "model": "claude-3-opus",
  "temperature": 0.0,
  "tools": {
    "read": true,
    "write": false,
    "edit": false,
    "shell": false,
    "grep": true,
    "search": true
  }
}

Use case: Before every deployment, run a security audit:

[Security Auditor] Review all files in src/auth/ and src/api/ for security vulnerabilities. Focus on authentication and input validation.

2. Test Writer Mode

{
  "name": "Test Writer",
  "description": "Generates comprehensive test suites",
  "systemPrompt": "You are a test engineer who writes thorough, maintainable tests. Follow these principles: 1) Test behavior, not implementation, 2) Use descriptive test names, 3) Arrange-Act-Assert pattern, 4) Cover happy path, edge cases, and error cases, 5) Mock external dependencies, 6) Aim for 80%+ coverage. Generate tests in the same style as existing tests in the project.",
  "model": "gpt-4o",
  "temperature": 0.2,
  "tools": {
    "read": true,
    "write": true,
    "edit": true,
    "shell": false,
    "grep": true,
    "search": true
  }
}

Use case: Generate tests for new features:

[Test Writer] Create unit tests for the UserService class. Follow the existing test style in tests/services/.

3. Documentation Mode

{
  "name": "Documentation Writer",
  "description": "Creates clear, comprehensive documentation",
  "systemPrompt": "You are a technical writer who creates clear, comprehensive documentation. Focus on: 1) User perspective, 2) Step-by-step instructions, 3) Code examples for every feature, 4) Troubleshooting sections, 5) Clear headings and structure, 6) Cross-references where relevant. Use Markdown format. Write at a professional but accessible level.",
  "model": "claude-3-5-sonnet",
  "temperature": 0.3,
  "tools": {
    "read": true,
    "write": true,
    "edit": true,
    "shell": false,
    "grep": false,
    "search": true
  }
}

4. Refactoring Mode

{
  "name": "Refactoring Expert",
  "description": "Improves code quality through refactoring",
  "systemPrompt": "You are a refactoring expert. Your goal is to improve code without changing behavior. Apply these patterns: 1) Extract Method for long functions, 2) Replace Conditionals with Polymorphism, 3) Remove Duplication, 4) Improve Naming, 5) Reduce Cyclomatic Complexity, 6) Apply SOLID principles. Always preserve existing behavior. Run tests after refactoring.",
  "model": "gpt-4o",
  "temperature": 0.1,
  "tools": {
    "read": true,
    "write": true,
    "edit": true,
    "shell": true,
    "grep": true,
    "search": true
  }
}

5. Onboarding Mode

{
  "name": "Code Explainer",
  "description": "Explains code for new team members",
  "systemPrompt": "You are a patient mentor explaining code to a new team member. For any code you review: 1) Explain WHAT it does in plain English, 2) Explain WHY it was designed this way, 3) Point out important patterns or conventions, 4) Note any non-obvious logic, 5) Suggest related files to explore. Avoid jargon. Use analogies where helpful.",
  "model": "claude-3-5-sonnet",
  "temperature": 0.4,
  "tools": {
    "read": true,
    "write": false,
    "edit": false,
    "shell": false,
    "grep": true,
    "search": true
  }
}

Mode Configuration Reference

Complete Configuration Schema

{
  "name": "Mode Name",
  "description": "Short description shown in selector",
  "systemPrompt": "Detailed instructions for the AI",
  "model": "claude-3-5-sonnet | gpt-4o | gemini-1.5-pro | ...",
  "temperature": 0.0-1.0,
  "maxTokens": 4096,
  "contextWindow": 200000,
  "tools": {
    "read": true | false,
    "write": true | false,
    "edit": true | false,
    "shell": true | false,
    "grep": true | false,
    "search": true | false,
    "mcp": true | false
  },
  "allowedCommands": ["npm", "git", "python"],
  "filePatterns": ["src/**/*.ts", "tests/**/*.ts"],
  "excludedPatterns": ["node_modules/**", ".git/**"]
}

Temperature Guide

Temperature	Best For
0.0-0.2	Code generation, refactoring, security review
0.3-0.5	Documentation, explanations, planning
0.6-0.8	Creative tasks, brainstorming, exploration
0.9-1.0	Rarely used for coding (too random)

Model Selection

Task	Recommended Model	Why
Code generation	Claude 3.5 Sonnet	Accurate, follows instructions
Complex analysis	Claude 3 Opus	Deep reasoning
Speed needed	GPT-4o	Fast responses
Long context	Gemini 1.5 Pro	1M+ token context
Cost-sensitive	DeepSeek V3	Affordable

Advanced: Mode-Specific Rules

Combine with MDC Rules

Create mode-specific rule files:

---
description: 'Security Auditor rules'
globs: ['src/**/*.ts']
alwaysApply: false
---

# Security Audit Checklist

When in Security Auditor mode:
- Check all SQL queries for injection
- Verify input validation on every endpoint
- Look for hardcoded credentials
- Review authentication logic
- Check CORS configuration
- Verify rate limiting

Activate with mode:

[Security Auditor] Review this file following the security checklist.

Mode Context Files

Create context files for each mode:

.cursor/modes/
  security-context.md
  test-context.md
  docs-context.md

Reference in system prompt:

{
  "systemPrompt": "Read .cursor/modes/security-context.md before reviewing. Focus on the OWASP Top 10 categories listed there."
}

Switching Between Modes

Keyboard Shortcuts

Action	Shortcut
Open mode selector	Cmd/Ctrl + Shift + M
Next mode	Cmd/Ctrl + ]
Previous mode	Cmd/Ctrl + [

Quick Switch

Type the mode name in chat:

[Security Auditor] Check this auth endpoint for vulnerabilities
[Test Writer] Write tests for the new UserService
[Refactoring Expert] Clean up this 200-line function

Team Sharing

Export Mode Configurations

Save modes to version control:

// .cursor/modes-config.json
{
  "modes": [
    {
      "name": "Security Auditor",
      "description": "...",
      "systemPrompt": "...",
      "model": "claude-3-opus",
      "tools": { "read": true, "write": false }
    },
    {
      "name": "Test Writer",
      "description": "...",
      "systemPrompt": "...",
      "model": "gpt-4o",
      "tools": { "read": true, "write": true }
    }
  ]
}

Share with Team

1. Commit .cursor/modes-config.json to git
2. Team members copy the file
3. Import via Settings > Modes > Import

Best Practices

Do's

• Keep system prompts under 500 tokens for faster loading
• Use specific, actionable instructions
• Test modes with small tasks first
• Document when to use each mode
• Update modes as your project evolves

Don'ts

• Don't create too many modes (3-5 is ideal)
• Don't make prompts too vague
• Don't give write access to review modes
• Don't forget to update modes when models improve

Mode Lifecycle

1. Create - Define purpose and configuration
2. Test - Try on small, safe tasks
3. Refine - Adjust prompts based on results
4. Deploy - Share with team
5. Maintain - Update as needed

Troubleshooting

Issue	Solution
Mode not appearing	Restart Cursor after creating
Prompts being ignored	Check prompt length and clarity
Wrong model loading	Verify model name is correct
Tools not working	Check tool permissions in config
Mode switching slow	Reduce system prompt length

Quick Start Template

{
  "name": "My Custom Mode",
  "description": "Brief description of what this mode does",
  "systemPrompt": "You are a [role]. Your task is to [specific goal]. Rules: 1) [Rule 1], 2) [Rule 2], 3) [Rule 3]. Always [key behavior]. Never [forbidden action].",
  "model": "claude-3-5-sonnet",
  "temperature": 0.2,
  "tools": {
    "read": true,
    "write": false,
    "edit": false,
    "shell": false,
    "grep": true,
    "search": true
  }
}

Related Resources

• Cursor Agent Mode Masterclass
• Plan vs Act Dual-Mode Workflow
• RIPER-5 Advanced Constraint Mode