From 62ad3f75f0a5a9624fe9df8d47da7b3cb798c035 Mon Sep 17 00:00:00 2001 From: Brendan O'Leary Date: Sat, 2 Aug 2025 19:36:26 +0200 Subject: [PATCH] Update custom modes to YAML --- docs/features/custom-modes.md | 594 +++++++++++++++++++++++----------- 1 file changed, 403 insertions(+), 191 deletions(-) diff --git a/docs/features/custom-modes.md b/docs/features/custom-modes.md index 36c826a..50f12da 100644 --- a/docs/features/custom-modes.md +++ b/docs/features/custom-modes.md @@ -2,284 +2,496 @@ Kilo Code allows you to create **custom modes** to tailor Kilo's behavior to specific tasks or workflows. Custom modes can be either **global** (available across all projects) or **project-specific** (defined within a single project). +## Sticky Models for Efficient Workflow + +Each modeβ€”including custom onesβ€”features **Sticky Models**. This means Kilo Code automatically remembers and selects the last model you used with a particular mode. This lets you assign different preferred models to different tasks without constant reconfiguration, as Kilo switches between models when you change modes. + ## Why Use Custom Modes? -* **Specialization:** Create modes optimized for specific tasks, like "Documentation Writer," "Test Engineer," or "Refactoring Expert" -* **Safety:** Restrict a mode's access to sensitive files or commands. For example, a "Review Mode" could be limited to read-only operations -* **Experimentation:** Safely experiment with different prompts and configurations without affecting other modes -* **Team Collaboration:** Share custom modes with your team to standardize workflows +- **Specialization:** Create modes optimized for specific tasks, like "Documentation Writer," "Test Engineer," or "Refactoring Expert" +- **Safety:** Restrict a mode's access to sensitive files or commands. For example, a "Review Mode" could be limited to read-only operations +- **Experimentation:** Safely experiment with different prompts and configurations without affecting other modes +- **Team Collaboration:** Share custom modes with your team to standardize workflows - Overview of custom modes interface - *Kilo Code's interface for creating and managing custom modes.* +Overview of custom modes interface + +_Kilo Code's interface for creating and managing custom modes._ ## What's Included in a Custom Mode? -Custom modes allow you to define: +Custom modes are defined by several key properties. Understanding these concepts will help you tailor Kilo's behavior effectively. + +| UI Field / YAML Property | Conceptual Description | +| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Slug** (`slug`) | A unique internal identifier for the mode. Used by Kilo Code to reference the mode, especially for associating mode-specific instruction files. | +| **Name** (`name`) | The display name for the mode as it appears in the Kilo Code user interface. Should be human-readable and descriptive. | +| **Description** (`description`) | A short, user-friendly summary of the mode's purpose displayed in the mode selector UI. Keep this concise and focused on what the mode does for the user. | +| **Role Definition** (`roleDefinition`) | Defines the core identity and expertise of the mode. This text is placed at the beginning of the system prompt and defines Kilo's personality and behavior when this mode is active. | +| **Available Tools** (`groups`) | Defines the allowed toolsets and file access permissions for the mode. Corresponds to selecting which general categories of tools the mode can use. | +| **When to Use** (`whenToUse`) | _(Optional)_ Provides guidance for Kilo's automated decision-making, particularly for mode selection and task orchestration. Used by the Orchestrator mode for task coordination. | +| **Custom Instructions** (`customInstructions`) | _(Optional)_ Specific behavioral guidelines or rules for the mode. Added near the end of the system prompt to further refine Kilo's behavior. | + +## Import/Export Modes + +Easily share, back up, and template your custom modes. This feature lets you export any modeβ€”and its associated rulesβ€”into a single, portable YAML file that you can import into any project. + +### Key Features + +- **Shareable Setups:** Package a mode and its rules into one file to easily share with your team +- **Easy Backups:** Save your custom mode configurations so you never lose them +- **Project Templates:** Create standardized mode templates for different types of projects +- **Simple Migration:** Move modes between your global settings and specific projects effortlessly +- **Flexible Slug Changes:** Change mode slugs in exported files without manual path editing + +### How it Works + +**Exporting a Mode:** + +1. Navigate to the Modes view +2. Select the mode you wish to export +3. Click the Export Mode button (download icon) +4. Choose a location to save the `.yaml` file +5. Kilo packages the mode's configuration and any rules into the YAML file + +**Importing a Mode:** + +1. Click the Import Mode button (upload icon) in the Modes view +2. Select the mode's YAML file +3. Choose the import level: + - **Project:** Available only in current workspace (saved to `.kilocodemodes` file) + - **Global:** Available in all projects (saved to global settings) + +### Changing Slugs on Import + +When importing modes, you can change the slug in the exported YAML file before importing: + +1. Export a mode with slug `original-mode` +2. Edit the YAML file and change the slug to `new-mode` +3. Import the file - the import process will automatically update rule file paths to match the new slug + +## Methods for Creating and Configuring Custom Modes + +You can create and configure custom modes in several ways: + +### 1. Ask Kilo! (Recommended) + +You can quickly create a basic custom mode by asking Kilo Code to do it for you. For example: + +``` +Create a new mode called "Documentation Writer". It should only be able to read files and write Markdown files. +``` + +Kilo Code will guide you through the process, prompting for necessary information and creating the mode using the preferred YAML format. + +### 2. Using the Prompts Tab + +1. **Open Prompts Tab:** Click the icon in the Kilo Code top menu bar +2. **Create New Mode:** Click the button to the right of the Modes heading +3. **Fill in Fields:** + +Custom mode creation interface in the Prompts tab + +_The custom mode creation interface showing fields for name, slug, description, save location, role definition, available tools, custom instructions._ + +The interface provides fields for Name, Slug, Description, Save Location, Role Definition, When to Use (optional), Available Tools, and Custom Instructions. After filling these, click the "Create Mode" button. Kilo Code will save the new mode in YAML format. + +### 3. Manual Configuration (YAML & JSON) + +You can directly edit the configuration files to create or modify custom modes. This method offers the most control over all properties. Kilo Code now supports both YAML (preferred) and JSON formats. + +- **Global Modes:** Edit the `custom_modes.yaml` (preferred) or `custom_modes.json` file. Access it via Prompts Tab > (Settings Menu icon next to "Global Prompts") > "Edit Global Modes" +- **Project Modes:** Edit the `.kilocodemodes` file (which can be YAML or JSON) in your project root. Access it via Prompts Tab > (Settings Menu icon next to "Project Prompts") > "Edit Project Modes" + +These files define an array/list of custom modes. + +## YAML Configuration Format (Preferred) + +YAML is now the preferred format for defining custom modes due to better readability, comment support, and cleaner multi-line strings. -* **A unique name and slug:** For easy identification -* **A role definition:** Placed at the beginning of the system prompt, this defines Kilo's core expertise and personality for the mode. This placement is crucial as it shapes Kilo's fundamental understanding and approach to tasks -* **Custom instructions:** Added at the end of the system prompt, these provide specific guidelines that modify or refine Kilo's behavior. Unlike `.clinerules` files (which only add rules at the end), this structured placement of role and instructions allows for more nuanced control over Kilo's responses -* **Allowed tools:** Which Kilo Code tools the mode can use (e.g., read files, write files, execute commands) -* **File restrictions:** (Optional) Limit file access to specific file types or patterns (e.g., only allow editing `.md` files) +### YAML Example -## Custom Mode Configuration (JSON Format) +```yaml +customModes: + - slug: docs-writer + name: πŸ“ Documentation Writer + description: A specialized mode for writing and editing technical documentation. + roleDefinition: You are a technical writer specializing in clear documentation. + whenToUse: Use this mode for writing and editing documentation. + customInstructions: Focus on clarity and completeness in documentation. + groups: + - read + - - edit # First element of tuple + - fileRegex: \.(md|mdx)$ # Second element is the options object + description: Markdown files only + - browser + - slug: another-mode + name: Another Mode + # ... other properties +``` -Both global and project-specific configurations use the same JSON format. Each configuration file contains a `customModes` array of mode definitions: +### JSON Alternative ```json { "customModes": [ { - "slug": "mode-name", - "name": "Mode Display Name", - "roleDefinition": "Mode's role and capabilities", - "groups": ["read", "edit"], - "customInstructions": "Additional guidelines" + "slug": "docs-writer", + "name": "πŸ“ Documentation Writer", + "description": "A specialized mode for writing and editing technical documentation.", + "roleDefinition": "You are a technical writer specializing in clear documentation.", + "whenToUse": "Use this mode for writing and editing documentation.", + "customInstructions": "Focus on clarity and completeness in documentation.", + "groups": [ + "read", + [ + "edit", + { "fileRegex": "\\.(md|mdx)$", "description": "Markdown files only" } + ], + "browser" + ] } ] } ``` -### Required Properties +## YAML/JSON Property Details + +### `slug` + +- **Purpose:** A unique identifier for the mode +- **Format:** Must match the pattern `/^[a-zA-Z0-9-]+$/` (only letters, numbers, and hyphens) +- **Usage:** Used internally and in file/directory names for mode-specific rules (e.g., `.kilo/rules-{slug}/`) +- **Recommendation:** Keep it short and descriptive + +**YAML Example:** `slug: docs-writer` +**JSON Example:** `"slug": "docs-writer"` + +### `name` + +- **Purpose:** The display name shown in the Kilo Code UI +- **Format:** Can include spaces and proper capitalization + +**YAML Example:** `name: πŸ“ Documentation Writer` +**JSON Example:** `"name": "Documentation Writer"` -#### `slug` -* A unique identifier for the mode -* Use lowercase letters, numbers, and hyphens -* Keep it short and descriptive -* Example: `"docs-writer"`, `"test-engineer"` +### `description` -#### `name` -* The display name shown in the UI -* Can include spaces and proper capitalization -* Example: `"Documentation Writer"`, `"Test Engineer"` +- **Purpose:** A short, user-friendly summary displayed below the mode name in the mode selector UI +- **Format:** Keep this concise and focused on what the mode does for the user +- **UI Display:** This text appears in the redesigned mode selector + +**YAML Example:** `description: A specialized mode for writing and editing technical documentation.` +**JSON Example:** `"description": "A specialized mode for writing and editing technical documentation."` + +### `roleDefinition` + +- **Purpose:** Detailed description of the mode's role, expertise, and personality +- **Placement:** This text is placed at the beginning of the system prompt when the mode is active + +**YAML Example (multi-line):** + +```yaml +roleDefinition: >- + You are a test engineer with expertise in: + - Writing comprehensive test suites + - Test-driven development +``` -#### `roleDefinition` -* Detailed description of the mode's role and capabilities -* Defines Kilo's expertise and personality for this mode -* Example: `"You are a technical writer specializing in clear documentation"` +**JSON Example:** `"roleDefinition": "You are a technical writer specializing in clear documentation."` -#### `groups` -* Array of allowed tool groups -* Available groups: `"read"`, `"edit"`, `"browser"`, `"command"`, `"mcp"` -* Can include file restrictions for the `"edit"` group +### `groups` + +- **Purpose:** Array/list defining which tool groups the mode can access and any file restrictions +- **Available Tool Groups:** `"read"`, `"edit"`, `"browser"`, `"command"`, `"mcp"` +- **Structure:** + - Simple string for unrestricted access: `"edit"` + - Tuple (two-element array) for restricted access: `["edit", { fileRegex: "pattern", description: "optional" }]` + +**File Restrictions for "edit" group:** + +- `fileRegex`: A regular expression string to control which files the mode can edit +- In YAML, typically use single backslashes for regex special characters (e.g., `\.md$`) +- In JSON, backslashes must be double-escaped (e.g., `\\.md$`) +- `description`: An optional string describing the restriction + +**YAML Example:** + +```yaml +groups: + - read + - - edit # First element of tuple + - fileRegex: \.(js|ts)$ # Second element is the options object + description: JS/TS files only + - command +``` + +**JSON Example:** -##### File Restrictions Format ```json -["edit", { - "fileRegex": "\\.md$", - "description": "Markdown files only" -}] +"groups": [ + "read", + ["edit", { "fileRegex": "\\.(js|ts)$", "description": "JS/TS files only" }], + "command" +] ``` -### Understanding File Restrictions +### `whenToUse` (Optional) -The `fileRegex` property uses regular expressions to control which files a mode can edit: +- **Purpose:** Provides guidance for Kilo's automated decision-making, particularly for mode selection and task orchestration +- **Format:** A string describing ideal scenarios or task types for this mode +- **Usage:** Used by Kilo for automated decisions and not displayed in the mode selector UI -* `\\.md$` - Match files ending in ".md" -* `\\.(test|spec)\\.(js|ts)$` - Match test files (e.g., "component.test.js") -* `\\.(js|ts)$` - Match JavaScript and TypeScript files +**YAML Example:** `whenToUse: This mode is best for refactoring Python code.` +**JSON Example:** `"whenToUse": "This mode is best for refactoring Python code."` -Common regex patterns: -* `\\.` - Match a literal dot -* `(a|b)` - Match either "a" or "b" -* `$` - Match the end of the filename +### `customInstructions` (Optional) -[Learn more about regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) +- **Purpose:** A string containing additional behavioral guidelines for the mode +- **Placement:** This text is added near the end of the system prompt -### Optional Properties +**YAML Example (multi-line):** -#### `customInstructions` -* Additional behavioral guidelines for the mode -* Example: `"Focus on explaining concepts and providing examples"` +```yaml +customInstructions: |- + When writing tests: + - Use describe/it blocks + - Include meaningful descriptions +``` -#### `apiConfiguration` -* Optional settings to customize the AI model and parameters for this mode -* Allows optimizing the model selection for specific tasks -* Example: `{"model": "gpt-4", "temperature": 0.2}` +**JSON Example:** `"customInstructions": "Focus on explaining concepts and providing examples."` -### Mode-Specific Custom Instructions Files +## Benefits of YAML Format -In addition to the `customInstructions` property in JSON, you can use a dedicated file for mode-specific instructions: +YAML is now the preferred format for defining custom modes due to several advantages: -1. Create a file named `.clinerules-{mode-slug}` in your workspace root - * Replace `{mode-slug}` with your mode's slug (e.g., `.clinerules-docs-writer`) -2. Add your custom instructions to this file -3. Kilo Code will automatically apply these instructions to the specified mode +- **Readability:** YAML's indentation-based structure is easier for humans to read and understand +- **Comments:** YAML allows for comments (lines starting with `#`), making it possible to annotate your mode definitions +- **Multi-line Strings:** YAML provides cleaner syntax for multi-line strings using `|` (literal block) or `>` (folded block) +- **Less Punctuation:** YAML generally requires less punctuation compared to JSON, reducing syntax errors +- **Editor Support:** Most modern code editors provide excellent syntax highlighting and validation for YAML files -This approach is particularly useful for: -* Keeping lengthy instructions separate from your mode configuration -* Managing instructions with version control -* Allowing non-technical team members to modify instructions without editing JSON +While JSON is still fully supported, new modes created via the UI or by asking Kilo will default to YAML. -Note: If both `.clinerules-{mode-slug}` and the `customInstructions` property exist, they will be combined, with the file contents appended after the JSON property. +## Migration to YAML Format -## Configuration Precedence +### Global Modes -Mode configurations are applied in this order: +Automatic migration from `custom_modes.json` to `custom_modes.yaml` happens when: -1. Project-level mode configurations (from `.kilocodemodes`) -2. Global mode configurations (from `custom_modes.yaml`) -3. Default mode configurations +- Kilo Code starts up +- A `custom_modes.json` file exists +- No `custom_modes.yaml` file exists yet -This means that project-specific configurations will override global configurations, which in turn override default configurations. +The migration process preserves the original JSON file for rollback purposes. -## Creating Custom Modes +### Project Modes (`.kilocodemodes`) -You have three options for creating custom modes: +- No automatic startup migration occurs for project-specific files +- Kilo Code can read `.kilocodemodes` files in either YAML or JSON format +- When editing through the UI, JSON files will be converted to YAML format +- For manual conversion, you can ask Kilo to help reformat configurations -### 1. Ask Kilo! (Recommended) +## Mode-Specific Instructions via Files/Directories + +You can provide instructions for custom modes using dedicated files or directories within your workspace, allowing for better organization and version control. + +### Preferred Method: Directory (`.kilo/rules-{mode-slug}/`) -You can quickly create a basic custom mode by asking Kilo Code to do it for you. For example: ``` -Create a new mode called "Documentation Writer". It should only be able to read files and write Markdown files. +. +β”œβ”€β”€ .kilo/ +β”‚ └── rules-docs-writer/ # Example for mode slug "docs-writer" +β”‚ β”œβ”€β”€ 01-style-guide.md +β”‚ └── 02-formatting.txt +└── ... (other project files) ``` -Kilo Code will guide you through the process. However, for fine-tuning modes or making specific adjustments, you'll want to use the Prompts tab or manual configuration methods described below. -:::info -#### Custom Mode Creation Settings -When enabled, Kilo allows you to create custom modes using prompts like 'Make me a custom mode that...'. Disabling this reduces your system prompt by about 700 tokens when this feature isn't needed. When disabled you can still manually create custom modes using the + button above or by editing the related config JSON. -Enable Custom Mode Creation Through Prompts setting -You can find this setting within the prompt settings by clicking the icon in the Kilo Code top menu bar. -::: -### 2. Using the Prompts Tab +### Fallback Method: Single File (`.kilorules-{mode-slug}`) -1. **Open Prompts Tab:** Click the icon in the Kilo Code top menu bar -2. **Create New Mode:** Click the button to the right of the Modes heading -3. **Fill in Fields:** +``` +. +β”œβ”€β”€ .kilorules-docs-writer # Example for mode slug "docs-writer" +└── ... (other project files) +``` - Custom mode creation interface in the Prompts tab - *The custom mode creation interface showing fields for name, slug, save location, role definition, available tools, and custom instructions.* +**Rules Directory Scope:** - * **Name:** Enter a display name for the mode - * **Slug:** Enter a lowercase identifier (letters, numbers, and hyphens only) - * **Save Location:** Choose Global (via `custom_modes.yaml`, available across all workspaces) or Project-specific (via `.kilocodemodes` file in project root) - * **Role Definition:** Define Kilo's expertise and personality for this mode (appears at the start of the system prompt) - * **Available Tools:** Select which tools this mode can use - * **Custom Instructions:** (Optional) Add behavioral guidelines specific to this mode (appears at the end of the system prompt) -4. **Create Mode:** Click the "Create Mode" button to save your new mode +- **Global modes:** Rules are stored in `~/.kilo/rules-{slug}/` +- **Project modes:** Rules are stored in `{workspace}/.kilo/rules-{slug}/` -Note: File type restrictions can only be added through manual configuration. +The directory method takes precedence if it exists and contains files. Files within the directory are read recursively and appended in alphabetical order. -### 3. Manual Configuration +## Configuration Precedence -You can configure custom modes by editing JSON files through the Prompts tab: +Mode configurations are applied in this order: -Both global and project-specific configurations can be edited through the Prompts tab: +1. **Project-level mode configurations** (from `.kilocodemodes` - YAML or JSON) +2. **Global mode configurations** (from `custom_modes.yaml`, then `custom_modes.json` if YAML not found) +3. **Default mode configurations** -1. **Open Prompts Tab:** Click the icon in the Kilo Code top menu bar -2. **Access Settings Menu:** Click the button to the right of the Modes heading -3. **Choose Configuration:** - * Select "Edit Global Modes" to edit `custom_modes.yaml` (available across all workspaces) - * Select "Edit Project Modes" to edit `.kilocodemodes` file (in project root) -4. **Edit Configuration:** Modify the JSON file that opens -5. **Save Changes:** Kilo Code will automatically detect the changes +**Important:** When modes with the same slug exist in both `.kilocodemodes` and global settings, the `.kilocodemodes` version completely overrides the global one for ALL properties. -## Example Configurations +## Overriding Default Modes -Each example shows different aspects of mode configuration: +You can override Kilo Code's built-in modes (like πŸ’» Code, πŸͺ² Debug, ❓ Ask, πŸ—οΈ Architect, πŸͺƒ Orchestrator) by creating a custom mode with the same slug. -### Basic Documentation Writer -```json -{ - "customModes": [{ - "slug": "docs-writer", - "name": "Documentation Writer", - "roleDefinition": "You are a technical writer specializing in clear documentation", - "groups": [ - "read", - ["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }] - ], - "customInstructions": "Focus on clear explanations and examples" - }] -} -``` +### Global Override Example -### Test Engineer with File Restrictions -```json -{ - "customModes": [{ - "slug": "test-engineer", - "name": "Test Engineer", - "roleDefinition": "You are a test engineer focused on code quality", - "groups": [ - "read", - ["edit", { "fileRegex": "\\.(test|spec)\\.(js|ts)$", "description": "Test files only" }] - ] - }] -} +```yaml +customModes: + - slug: code # Matches the default 'code' mode slug + name: πŸ’» Code (Global Override) + roleDefinition: You are a software engineer with global-specific constraints. + whenToUse: This globally overridden code mode is for JS/TS tasks. + customInstructions: Focus on project-specific JS/TS development. + groups: + - read + - - edit + - fileRegex: \.(js|ts)$ + description: JS/TS files only ``` -### Project-Specific Mode Override -```json -{ - "customModes": [{ - "slug": "code", - "name": "Code (Project-Specific)", - "roleDefinition": "You are a software engineer with project-specific constraints", - "groups": [ - "read", - ["edit", { "fileRegex": "\\.(js|ts)$", "description": "JS/TS files only" }] - ], - "customInstructions": "Focus on project-specific JS/TS development" - }] -} +### Project-Specific Override Example + +```yaml +customModes: + - slug: code # Matches the default 'code' mode slug + name: πŸ’» Code (Project-Specific) + roleDefinition: You are a software engineer with project-specific constraints for this project. + whenToUse: This project-specific code mode is for Python tasks within this project. + customInstructions: Adhere to PEP8 and use type hints. + groups: + - read + - - edit + - fileRegex: \.py$ + description: Python files only + - command ``` -By following these instructions, you can create and manage custom modes to enhance your workflow with Kilo Code. ## Understanding Regex in Custom Modes -Regex patterns in custom modes let you precisely control which files Kilo can edit: +Regular expressions (`fileRegex`) offer fine-grained control over file editing permissions. -### Basic Syntax +:::tip +**Let Kilo Build Your Regex Patterns** -When you specify `fileRegex` in a custom mode, you're creating a pattern that file paths must match: +Instead of writing complex regex manually, ask Kilo: -```json -["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }] +``` +Create a regex pattern that matches JavaScript files but excludes test files ``` -### Important Rules +Kilo will generate the pattern. Remember to adapt it for YAML (usually single backslashes) or JSON (double backslashes). +::: + +### Important Rules for `fileRegex` -- **Double Backslashes:** In JSON, backslashes must be escaped with another backslash. So `\.md$` becomes `\\.md$` -- **Path Matching:** Patterns match against the full file path, not just the filename +- **Escaping in JSON:** In JSON strings, backslashes (`\`) must be double-escaped (e.g., `\\.md$`) +- **Escaping in YAML:** In unquoted or single-quoted YAML strings, a single backslash is usually sufficient for regex special characters (e.g., `\.md$`) +- **Path Matching:** Patterns match against the full relative file path from your workspace root - **Case Sensitivity:** Regex patterns are case-sensitive by default +- **Validation:** Invalid regex patterns are rejected with an "Invalid regular expression pattern" error message ### Common Pattern Examples -| Pattern | Matches | Doesn't Match | -|---------|---------|---------------| -| `\\.md$` | `readme.md`, `docs/guide.md` | `script.js`, `readme.md.bak` | -| `^src/.*` | `src/app.js`, `src/components/button.tsx` | `lib/utils.js`, `test/src/mock.js` | -| `\\.(css\|scss)$` | `styles.css`, `theme.scss` | `styles.less`, `styles.css.map` | -| `docs/.*\\.md$` | `docs/guide.md`, `docs/api/reference.md` | `guide.md`, `src/docs/notes.md` | -| `^(?!.*(test\|spec)).*\\.js$` | `app.js`, `utils.js` | `app.test.js`, `utils.spec.js` | +| Pattern (YAML-like) | JSON fileRegex Value | Matches | Doesn't Match | +| -------------------------------- | ----------------------------------- | ----------------------------------------- | ---------------------------------- | +| `\.md$` | `"\\.md$"` | `readme.md`, `docs/guide.md` | `script.js`, `readme.md.bak` | +| `^src/.*` | `"^src/.*"` | `src/app.js`, `src/components/button.tsx` | `lib/utils.js`, `test/src/mock.js` | +| `\.(css\|scss)$` | `"\\.(css\|scss)$"` | `styles.css`, `theme.scss` | `styles.less`, `styles.css.map` | +| `docs/.*\.md$` | `"docs/.*\\.md$"` | `docs/guide.md`, `docs/api/reference.md` | `guide.md`, `src/docs/notes.md` | +| `^(?!.*(test\|spec))\.(js\|ts)$` | `"^(?!.*(test\|spec))\\.(js\|ts)$"` | `app.js`, `utils.ts` | `app.test.js`, `utils.spec.js` | -### Pattern Building Blocks +### Key Regex Building Blocks -- `\\.` - Match a literal dot (period) -- `$` - Match the end of the string -- `^` - Match the beginning of the string -- `.*` - Match any character (except newline) zero or more times -- `(a|b)` - Match either "a" or "b" -- `(?!...)` - Negative lookahead (exclude matches) +- `\.`: Matches a literal dot (YAML: `\.`, JSON: `\\.`) +- `$`: Matches the end of the string +- `^`: Matches the beginning of the string +- `.*`: Matches any character (except newline) zero or more times +- `(a|b)`: Matches either "a" or "b" +- `(?!...)`: Negative lookahead -### Testing Your Patterns +## Error Handling -Before applying a regex pattern to a custom mode: +When a mode attempts to edit a file that doesn't match its `fileRegex` pattern, you'll see a `FileRestrictionError` that includes: -1. Test it on sample file paths to ensure it matches what you expect -2. Remember that in JSON, each backslash needs to be doubled (`\d` becomes `\\d`) -3. Start with simpler patterns and build complexity gradually +- The mode name +- The allowed file pattern +- The description (if provided) +- The attempted file path +- The tool that was blocked +## Example Configurations -:::tip -### Let Kilo Build Your Regex Patterns -Instead of writing complex regex patterns manually, you can ask Kilo to create them for you! Simply describe which files you want to include or exclude: +### Basic Documentation Writer (YAML) + +```yaml +customModes: + - slug: docs-writer + name: πŸ“ Documentation Writer + description: Specialized for writing and editing technical documentation + roleDefinition: You are a technical writer specializing in clear documentation + groups: + - read + - - edit + - fileRegex: \.md$ + description: Markdown files only + customInstructions: Focus on clear explanations and examples ``` -Create a regex pattern that matches JavaScript files but excludes test files + +### Test Engineer with File Restrictions (YAML) + +```yaml +customModes: + - slug: test-engineer + name: πŸ§ͺ Test Engineer + description: Focused on writing and maintaining test suites + roleDefinition: You are a test engineer focused on code quality + whenToUse: Use for writing tests, debugging test failures, and improving test coverage + groups: + - read + - - edit + - fileRegex: \.(test|spec)\.(js|ts)$ + description: Test files only + - command +``` + +### Security Review Mode (YAML) + +```yaml +customModes: + - slug: security-review + name: πŸ”’ Security Reviewer + description: Read-only security analysis and vulnerability assessment + roleDefinition: You are a security specialist reviewing code for vulnerabilities + whenToUse: Use for security reviews and vulnerability assessments + customInstructions: |- + Focus on: + - Input validation issues + - Authentication and authorization flaws + - Data exposure risks + - Injection vulnerabilities + groups: + - read + - browser ``` -Kilo will generate the appropriate pattern with proper escaping for JSON configuration. -::: + +## Troubleshooting + +### Common Issues + +- **Mode not appearing:** After creating or importing a mode, you may need to reload the VS Code window +- **Invalid regex patterns:** Test your patterns using online regex testers before applying them +- **Precedence confusion:** Remember that project modes completely override global modes with the same slug +- **YAML syntax errors:** Use proper indentation (spaces, not tabs) and validate your YAML + +### Tips for Working with YAML + +- **Indentation is Key:** YAML uses indentation (spaces, not tabs) to define structure +- **Colons for Key-Value Pairs:** Keys must be followed by a colon and a space (e.g., `slug: my-mode`) +- **Hyphens for List Items:** List items start with a hyphen and a space (e.g., `- read`) +- **Validate Your YAML:** Use online YAML validators or your editor's built-in validation ## Community Gallery + Ready to explore more? Check out the [Show and Tell](https://github.com/Kilo-Org/kilocode/discussions/categories/show-and-tell) to discover and share custom modes created by the community!