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
.kilocode/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, task, webfetch, websearch, todowrite, todoread, and more.

model

Pin a specific model using the provider/model format:

model: anthropic/claude-sonnet-4-20250514

The model selector also remembers the last model you picked for each agent across sessions. A config-pinned model acts as the default when no manual pick exists. To reset a pick and let the config take over, use the reset button in the model selector (visible when your active model differs from what the config specifies).

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/ / legacy .kilocode/ 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).

Legacy File Locations

The current VSCode extension reads the legacy custom_modes.yaml file from its own global storage directory. Helpful for inspecting or fixing the file before the one-time migration runs:

Project-level .kilocodemodes and workspace-scoped files are handled by the CLI backend that the extension delegates to — see the CLI tab for the full load-order table. After the extension migrates on startup, the legacy file is no longer consulted; remove new modes through the extension UI instead of editing custom_modes.yaml directly.

Basic Documentation Writer (.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 writer specializing in clear documentation.
Focus on clear explanations and examples.

Test Engineer (.kilo/agents/test-engineer.md)

---
description: Focused on writing and maintaining test suites
mode: primary
color: "#F59E0B"
permission:
  edit:
    "*.{test,spec}.{js,ts}": "allow"
    "*": "deny"
---

You are a test engineer focused on code quality.
Use for writing tests, debugging test failures, and improving test coverage.

Security Reviewer (.kilo/agents/security-review.md)

---
description: Read-only security analysis and vulnerability assessment
mode: primary
color: "#EF4444"
permission:
  edit: deny
  bash: deny
---

You are a security specialist reviewing code for vulnerabilities.

Focus on:

- Input validation issues
- Authentication and authorization flaws
- Data exposure risks
- Injection vulnerabilities

Config File Example (kilo.jsonc)

{
  "agent": {
    "docs-writer": {
      "description": "Specialized for writing and editing technical documentation",
      "mode": "primary",
      "color": "#10B981",
      "prompt": "You are a technical writer specializing in clear documentation.",
      "permission": {
        "edit": { "*.md": "allow", "*": "deny" },
        "bash": "deny",
      },
    },
    "test-engineer": {
      "description": "Focused on writing and maintaining test suites",
      "mode": "primary",
      "prompt": "You are a test engineer focused on code quality.",
      "permission": {
        "edit": { "*.{test,spec}.{js,ts}": "allow", "*": "deny" },
      },
    },
  },
}

Common Issues

• Agent not appearing: Ensure the .md file is in a recognized directory (.kilo/agents/, .kilo/agent/, .kilocode/agents/). Check that the mode property is primary or all if you expect it in the agent picker.
• Permission errors: Permission rules are evaluated last-match-wins. If an agent can't use a tool you expect, check that an allow rule appears after any deny rules for that permission.
• YAML frontmatter parse errors: Ensure the frontmatter block starts and ends with --- on its own line. Validate that YAML keys match expected property names (e.g., top_p not topP).
• Agent overrides not working: Config merges from global to project level. If a global config sets a property, your project config can override it, but both must use the same agent name.

Tips for Agent Definitions

• Keep prompts focused: The markdown body is your system prompt — write it as if briefing a colleague
• Use mode: subagent for helper agents that shouldn't be directly selectable by users
• Use the Settings UI to view and edit agents through the Settings → Agent Behaviour → Agents subtab
• Legacy modes are auto-migrated: If you have .kilocodemodes files, they'll be converted on startup — no manual migration needed