Custom Modes

In the VSCode extension and CLI, custom behavioral profiles are called agents instead of modes. Agents are defined as Markdown files with YAML frontmatter or as entries in the agent key of your config file.

What's Included in a Custom Agent?

Methods for Creating and Configuring Agents

1. Ask Kilo! (Recommended)

Ask Kilo to create an agent for you:

Create a new agent called "docs-writer" that can only read files and edit Markdown files.

Kilo will generate the agent definition and write it to .kilo/agent/ in your project.

2. Using the Settings UI

You can manage agents through the Settings → Agent Behaviour → Agents subtab in the extension. This lets you view, create, and edit agent configurations — including the agent's prompt, model, permissions, and other properties.

3. Markdown Files with YAML Frontmatter

Create .md files in any of these directories:

.kilo/agents/my-agent.md
.kilo/agent/my-agent.md
.opencode/agents/my-agent.md

For global agents, place files in your global config directory:

~/.config/kilo/agent/my-agent.md

The filename (minus .md) becomes the agent name. Nested directories create namespaced names (e.g., agents/backend/sql.md becomes agent backend/sql).

Example agent file (.kilo/agents/docs-writer.md):

---
description: Specialized for writing and editing technical documentation
mode: primary
color: "#10B981"
permission:
  edit:
    "*.md": "allow"
    "*": "deny"
  bash: deny
---

You are a technical documentation specialist. Your expertise includes:

- Writing clear, well-structured documentation
- Following markdown best practices
- Creating helpful code examples

Focus on clarity and completeness. Only edit Markdown files.

4. Config File (kilo.jsonc)

Define agents under the agent key in your project's kilo.jsonc:

{
  "agent": {
    "docs-writer": {
      "description": "Specialized for writing and editing technical documentation",
      "mode": "primary",
      "color": "#10B981",
      "prompt": "You are a technical documentation specialist...",
      "permission": {
        "edit": {
          "*.md": "allow",
          "*": "deny",
        },
        "bash": "deny",
      },
    },
    // Override a built-in agent
    "code": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
    },
  },
}

Agent Property Reference

mode

Controls where the agent appears:

permission

An ordered set of rules controlling tool access. Permissions support three actions: allow, deny, and ask (prompt the user). You can use glob patterns to scope rules to specific files or commands:

permission:
  edit:
    "*.md": "allow"
    "*": "deny"
  bash: deny
  read: allow

Known permission types include: read, edit, bash, glob, grep, list, task, webfetch, websearch, codesearch, todowrite, todoread, and more.

model

Pin a specific model using the provider/model format:

model: anthropic/claude-sonnet-4-20250514

steps

Limits the number of agentic iterations (tool call rounds) before the agent is forced to respond with text only. Useful for preventing runaway agents:

steps: 25

Configuration Precedence

Agent configurations merge from lowest to highest priority:

1. Built-in (native) agent defaults
2. Global config (~/.config/kilo/kilo.jsonc)
3. Project config (kilo.jsonc at project root)
4. .kilo/ / .opencode/ directory configs and agent .md files
5. Environment variable overrides (KILO_CONFIG_CONTENT)

When the same agent name appears at multiple levels, properties are merged (not replaced wholesale), so you can override just a model or temperature without redefining the entire agent.

Overriding Built-in Agents

Override any built-in agent (code, plan, debug, ask, orchestrator, explore, general) by defining an agent with the same name:

// kilo.jsonc — override the built-in "code" agent
{
  "agent": {
    "code": {
      "model": "openai/gpt-4o",
      "temperature": 0.2,
      "permission": {
        "edit": {
          "*.py": "allow",
          "*": "deny",
        },
      },
    },
  },
}

Or as a .md file (.kilo/agents/code.md):

---
model: openai/gpt-4o
temperature: 0.2
permission:
  edit:
    "*.py": "allow"
    "*": "deny"
---

You are a Python specialist. Only edit Python files.

Migration from VSCode Extension Modes

If you have existing .kilocodemodes or custom_modes.yaml files from the VSCode extension, the extension automatically migrates them on startup. The migration converts:

• slug to the agent name (key)
• roleDefinition + customInstructions to prompt
• groups (e.g., ["read", "edit", "browser"]) to permission rules
• whenToUse / description to description
• Mode is set to primary

Default legacy mode slugs (code, build, architect, ask, debug, orchestrator) are skipped during migration since they map to built-in agents (build → code, architect → plan).