packages/kilo-docs/pages/customize/agents-md.md
AGENTS.md files provide a standardized way to configure AI agent behavior across different AI coding tools. They allow you to define project-specific instructions, coding standards, and guidelines that AI agents should follow when working with your codebase.
{% callout type="note" title="Memory Bank Deprecation" %} The Kilo Code memory bank feature has been deprecated in favor of AGENTS.md.
Existing memory bank rules will continue to work.
Legacy Memory Bank status indicators such as [Memory Bank: Active] and [Memory Bank: Missing] can still appear, but they are not guaranteed across all clients or modes.
If you'd like to migrate your memory bank content to AGENTS.md:
.kilocode/rules/memory-bank/AGENTS.md file (or ask Kilo to do it for you)
{% /callout %}AGENTS.md is an open standard for configuring AI agent behavior in software projects. It's a simple Markdown file placed at the root of your project that contains instructions for AI coding assistants. The standard is supported by multiple AI coding tools, including Kilo Code, Cursor, and Windsurf.
Think of AGENTS.md as a "README for AI agents" - it tells the AI how to work with your specific project, what conventions to follow, and what constraints to respect.
Place your AGENTS.md file at the root of your project:
my-project/
├── AGENTS.md # Primary filename (recommended)
├── src/
├── package.json
└── README.md
Supported filenames (in order of precedence):
AGENTS.md (uppercase, plural - recommended)AGENT.md (uppercase, singular - fallback){% callout type="warning" title="Case Sensitivity" %}
The filename must be uppercase (AGENTS.md), not lowercase (agents.md). This ensures consistency across different operating systems and tools.
{% /callout %}
You can also place AGENTS.md files in subdirectories to provide context-specific instructions:
my-project/
├── AGENTS.md # Root-level instructions
├── src/
│ └── backend/
│ └── AGENTS.md # Backend-specific instructions
└── docs/
└── AGENTS.md # Documentation-specific instructions
When working in a subdirectory, Kilo Code will load both the root AGENTS.md and any subdirectory AGENTS.md files, with subdirectory files taking precedence for conflicting instructions.
Both AGENTS.md and AGENT.md are write-protected files in Kilo Code. This means:
AGENTS.md files use standard Markdown syntax. There's no required structure, but organizing your content with headers and lists makes it easier for AI models to parse and understand.
# Project Name
Brief description of the project and its purpose.
## Code Style
- Use TypeScript for all new files
- Follow ESLint configuration
- Use 2 spaces for indentation
## Architecture
- Follow MVC pattern
- Keep components under 200 lines
- Use dependency injection
## Testing
- Write unit tests for all business logic
- Maintain >80% code coverage
- Use Jest for testing
## Security
- Never commit API keys or secrets
- Validate all user inputs
- Use parameterized queries for database access
When you start a task in Kilo Code:
AGENTS.md or AGENT.md at the project root{% tabs %} {% tab label="VSCode" %}
In the new platform, AGENTS.md is loaded alongside other instruction sources. The CLI also supports .claude/ and .agents/ directories for compatibility with other tools.
| Source | Scope | Location | Priority |
|---|---|---|---|
| Agent prompt | Per-agent | agent.<name>.prompt in config | 1 (Highest) |
| Instructions | Project | instructions key in project kilo.jsonc | 2 |
| AGENTS.md | Project | AGENTS.md at project root | 3 |
| Instructions | Global | instructions key in global kilo.jsonc | 4 |
| Skills | Both | .kilo/skills/, config skills key | Loaded on demand |
{% /tab %} {% tab label="CLI" %}
In the new platform, AGENTS.md is loaded alongside other instruction sources. The CLI also supports .claude/ and .agents/ directories for compatibility with other tools.
| Source | Scope | Location | Priority |
|---|---|---|---|
| Agent prompt | Per-agent | agent.<name>.prompt in config | 1 (Highest) |
| Instructions | Project | instructions key in project kilo.jsonc | 2 |
| AGENTS.md | Project | AGENTS.md at project root | 3 |
| Instructions | Global | instructions key in global kilo.jsonc | 4 |
| Skills | Both | .kilo/skills/, config skills key | Loaded on demand |
{% /tab %} {% tab label="VSCode (Legacy)" %}
AGENTS.md works alongside Kilo Code's other configuration systems:
| Feature | Scope | Location | Purpose | Priority |
|---|---|---|---|---|
| Mode-specific Custom Rules | Project | .kilocode/rules-{mode}/ | Mode-specific rules and constraints | 1 (Highest) |
| Custom Rules | Project | .kilocode/rules/ | Kilo Code-specific rules and constraints | 2 |
| AGENTS.md | Project | AGENTS.md | Universal standard for any AI coding tool | 3 |
| Global Custom Rules | Global | ~/.kilocode/rules/ | Global Kilo Code rules | 4 |
| Custom Instructions | Global | IDE settings | Personal preferences across all projects | 5 (Lowest) |
{% /tab %} {% /tabs %}
{% tabs %} {% tab label="VSCode" %}
AGENTS.md is loaded automatically. To disable external skill directories (.claude/skills/, .agents/skills/), set the environment variable:
export KILO_DISABLE_EXTERNAL_SKILLS=true
AGENTS.md itself cannot be individually disabled — it is always loaded if present. To override its instructions, use higher-priority sources like the instructions config key or agent-specific prompts.
{% /tab %} {% tab label="CLI" %}
AGENTS.md is loaded automatically. To disable external skill directories (.claude/skills/, .agents/skills/), set the environment variable:
export KILO_DISABLE_EXTERNAL_SKILLS=true
AGENTS.md itself cannot be individually disabled — it is always loaded if present. To override its instructions, use higher-priority sources like the instructions config key or agent-specific prompts.
{% /tab %} {% tab label="VSCode (Legacy)" %}
AGENTS.md support is enabled by default. To disable it, edit settings.json:
{
"kilocode.useAgentRules": false
}
{% /tab %} {% /tabs %}