# create-mode

> Instructions for creating custom modes in Roo Code. Use when the user asks to create a new mode, edit an existing mode, or configure mode settings.

- Author: roomote[bot]
- Repository: aiLab-2030/Roo-Code
- Version: 20260131072259
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/aiLab-2030/Roo-Code
- Web: https://mule.run/skillshub/@@aiLab-2030/Roo-Code~create-mode:20260131072259

---

---
name: create-mode
description: Instructions for creating custom modes in Roo Code. Use when the user asks to create a new mode, edit an existing mode, or configure mode settings.
---

Custom modes can be configured in two ways:

1. Globally via the custom modes file in your Roo Code settings directory (typically ~/.roo-code/settings/custom_modes.yaml on macOS/Linux or %APPDATA%\roo-code\settings\custom_modes.yaml on Windows) - created automatically on startup
2. Per-workspace via '.roomodes' in the workspace root directory

When modes with the same slug exist in both files, the workspace-specific .roomodes version takes precedence. This allows projects to override global modes or define project-specific modes.

If asked to create a project mode, create it in .roomodes in the workspace root. If asked to create a global mode, use the global custom modes file.

- The following fields are required and must not be empty:

    - slug: A valid slug (lowercase letters, numbers, and hyphens). Must be unique, and shorter is better.
    - name: The display name for the mode
    - roleDefinition: A detailed description of the mode's role and capabilities
    - groups: Array of allowed tool groups (can be empty). Each group can be specified either as a string (e.g., "edit" to allow editing any file) or with file restrictions (e.g., ["edit", { fileRegex: "\.md$", description: "Markdown files only" }] to only allow editing markdown files)

- The following fields are optional but highly recommended:

    - description: A short, human-readable description of what this mode does (5 words)
    - whenToUse: A clear description of when this mode should be selected and what types of tasks it's best suited for. This helps the Orchestrator mode make better decisions.
    - customInstructions: Additional instructions for how the mode should operate

- For multi-line text, include newline characters in the string like "This is the first line.\nThis is the next line.\n\nThis is a double line break."

Both files should follow this structure (in YAML format):

customModes:

- slug: designer # Required: unique slug with lowercase letters, numbers, and hyphens
  name: Designer # Required: mode display name
  description: UI/UX design systems expert # Optional but recommended: short description (5 words)
  roleDefinition: >-
  You are Roo, a UI/UX expert specializing in design systems and frontend development. Your expertise includes:
    - Creating and maintaining design systems
    - Implementing responsive and accessible web interfaces
    - Working with CSS, HTML, and modern frontend frameworks
    - Ensuring consistent user experiences across platforms # Required: non-empty
      whenToUse: >-
      Use this mode when creating or modifying UI components, implementing design systems,
      or ensuring responsive web interfaces. This mode is especially effective with CSS,
      HTML, and modern frontend frameworks. # Optional but recommended
      groups: # Required: array of tool groups (can be empty)
    - read # Read files group (read_file, search_files, list_files, codebase_search)
    - edit # Edit files group (apply_diff, write_to_file) - allows editing any file
    # Or with file restrictions:
    # - - edit
    # - fileRegex: \.md$
    # description: Markdown files only # Edit group that only allows editing markdown files
    - browser # Browser group (browser_action)
    - command # Command group (execute_command)
    - mcp # MCP group (use_mcp_tool, access_mcp_resource)
      customInstructions: Additional instructions for the Designer mode # Optional