Custom Instructions

Custom Instructions allow you to personalize how Kilo Code behaves, providing specific guidance that shapes responses, coding style, and decision-making processes. Both the VSCode and CLI versions support custom instructions, though the mechanisms differ.

What Are Custom Instructions?

Custom Instructions define specific Extension behaviors, preferences, and constraints beyond Kilo's basic role definition. Examples include coding style, documentation standards, testing requirements, and workflow guidelines.

The extension provides multiple layers of instruction configuration — from per-agent prompts in the Settings UI to auto-discovered files in your project and global config.

Per-Agent Prompts

Each agent can have its own custom prompt configured through the settings UI:

  1. Open Settings → Agent Behaviour → Agents subtab
  2. Select the agent you want to customize
  3. Enter your instructions in the markdown text area under the agent's prompt field
  4. Save your changes

These prompts are injected into the agent's system prompt and apply across all sessions using that agent.

Instruction Files

Kilo automatically discovers instruction files at your project root and in parent directories (via findUp). The following filenames are recognized:

  • AGENTS.md — The primary instruction file for Kilo
  • CLAUDE.md — Also supported for compatibility
  • CONTEXT.md — Additional project context

Place any of these files at your project root to provide project-wide instructions to the agent.

Global Instructions

For instructions that apply across all your projects, place an AGENTS.md file in your global config directory:

  • Kilo: ~/.config/kilo/AGENTS.md
  • Claude-compatible: ~/.claude/CLAUDE.md

Project-level instructions are loaded before global instructions and apply to every session.

Per-Directory Instructions

You can place AGENTS.md files in any subdirectory of your project. These are loaded dynamically — when the agent's Read tool accesses a file in that directory, the corresponding AGENTS.md is discovered and its contents are injected into the conversation as <system-reminder> tags.

This is useful for providing context-specific guidance for different parts of a monorepo or project.

Additional Instruction Sources

The instructions key in kilo.jsonc accepts an array of paths, globs, or URLs pointing to additional instruction files. You can manage these in Settings → Agent Behaviour → Rules subtab.

# Examples of instruction sources
instructions:
  - ./docs/coding-standards.md
  - ./teams/frontend-rules.md
  - https://example.com/team-instructions.md
ℹī¸URL-Based Instructions

URL-based instruction sources are fetched at session start with a 5-second timeout. If the URL is unreachable, the instruction source is silently skipped.

Legacy .kilocoderules Support

If your project contains .kilocoderules files from the VSCode extension, these are still loaded via auto-migration. However, migrating to AGENTS.md is recommended for new projects.