jenchan.biz / cursorrules
[READ-ONLY] Mirror of https://github.com/usrrname/cursorrules. A wicked npx-able lib of Cursor rules with Otaku AI agents, optional lean workflow 馃巰 usrrname.github.io/cursorrules
agent cursor cursor-ai cursorrules
Star
Fork 0
Watch
cursorrules docs modes-format.md
6.0 kB
Markdown
at main

Cursor Custom Modes Format Documentation #

This is straight-up copied from bmad's docs as it's just so awesome!

This document describes the format for defining custom modes in the .cursor/modes.json file.

File Structure #

The modes.json file contains a JSON object with two main fields:

  • modes: An array of mode configuration objects

Mode Configuration Schema #

{
  "commentFromBMad": "string",
  "modes": [
    {
      "name": "string",
      "description": "string",
      "comment": "string",
      "model": "string",
      "customPrompt": "string",
      "allowedCursorTools": "string[]",
      "allowedMcpTools": "string[]",
      "autoApplyEdits": "boolean",
      "autoRun": "boolean",
      "autoFixErrors": "boolean"
    }
  ]
}

Field Descriptions #

Root Level Fields #

Field Type Description
modes array Array of mode configuration objects

Mode Configuration Fields #

Field Type Required Default Description
name string Yes - Display in tab Short CapCase but easy to remember. The full name will be in the description field - such as PicardPm or RikerArch, or FooFEDev
description string Yes - Not used in actual configuration, but easy for user to know what character it is briefly
comment string No - Reference note for documentation purposes
model string Yes - The AI model to use for this mode
customPrompt string No - Detailed prompt defining the agent's persona and behavior
allowedCursorTools string[] or "all" No - Array of Cursor tools this mode can access, or "all" to grant access to all available Cursor tools
allowedMcpTools string[] or "all" No - Array or comma-separated list of allowed MCP tool names, or "all" to grant access to all available MCP tools
autoApplyEdits boolean No false Automatically apply edits without confirmation
autoRun boolean No false Automatically run commands without confirmation
autoFixErrors boolean No false Automatically attempt to fix detected errors
autoRunLint boolean No false Automatically run linting tools

See Cursor's Models documentation.

Supported Cursor Tools #

The following tools can be specified in the allowedCursorTools array:

Search Tools #

  • codebase_search - Semantic search across the codebase
  • web - Web search capabilities
  • grep - Pattern-based code search
  • list_directory - List contents of directories
  • search_files - Search for files by name
  • read_file - Read file contents
  • fetch_rules - Fetch custom codebase rules
  • `

Edit Tools #

  • edit_file - Edit file contents
  • edit_and_reapply - Edit with smart reapplication
  • delete_file - Delete files

Run Tools #

  • terminal - Execute terminal commands

Example Configuration #

{
  "commentFromBMad": "Example custom mode configuration",
  "modes": [
    {
      "name": "PiPyDev",
      "description": "Pirate Python Dev",
      "comment": "Specialized mode for Python development with auto-fixes enabled",
      "model": "claude-4-sonnet",
      "customPrompt": "You are an expert Python developer that always speaks like a pirate in conversation, but never injects the personality into files being created or updated...",
      "allowedCursorTools": [
        "codebase_search",
        "web",
        "grep",
        "list_directory",
        "search_files",
        "read_file",
        "fetch_rules",
        "edit_file",
        "edit_and_reapply",
        "delete_file",
        "terminal"
      ],
      "allowedMcpTools": ["python_linter", "python_formatter", "pytest"],
      "autoApplyEdits": true,
      "autoRun": false,
      "autoFixErrors": true
    }
  ]
}

MCP Tools #

The allowedMcpTools field can contain any custom tool names that have been configured in your MCP configuration. These should match the exact names given to the tools in your MCP setup.

Best Practices #

  1. Choose descriptive names for your custom modes
  2. Provide detailed custom prompts that clearly define the agent's role
  3. Limit tool access to only what's necessary for the mode's purpose
  4. Document any special requirements or dependencies in the comment field
  5. Use consistent naming conventions for MCP tools 馃敡