# 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.

### VSCodeCLI / VSCode (Legacy)

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.

```yaml
# 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.

## Related Features

- [Custom Modes](/content/docs/customize/custom-modes/index.html)
- [Custom Rules](/content/docs/customize/custom-rules/index.html)
- [Settings Management](/content/docs/getting-started/settings/index.html)
- [Auto-Approval Settings](/content/docs/getting-started/settings/auto-approving-actions/index.html)