> [!NOTE]
> **Note:** Agent files titled `AGENTS.md` are compatible with Android Studio Narwhal 4 Feature Drop Canary 4 and higher. To use agent files with Android Studio Narwhal 3 Feature Drop, use the name `AGENT.md` instead of `AGENTS.md`.

Give the agent customized instructions to follow using one or
more `AGENTS.md` files. `AGENTS.md` files are placed alongside the other files
in your codebase, so it's straightforward to check them in to your version
control system (VCS) and share project-specific instructions, coding style
rules, and other guidance with your entire team.

To get started, follow these steps:

1. Create an `AGENTS.md` file anywhere in your project's file system. The agent
   scans the current directory and all parent directories for `AGENTS.md` files
   when you submit a query. For more details, see [How `AGENTS.md` files
   work](https://developer.android.com/studio/gemini/agent-files#how-agent-files-work).

   > [!TIP]
   > **Tip:** Use multiple instruction files across different directories for more granular control over different parts of your codebase. For example, you can have a global `AGENTS.md` file at the project root and more specific `AGENTS.md` files in subdirectories for different modules.

2. Add your instructions. Write your instructions using Markdown. For
   readability, consider using headings and bullet points for different rules.
   [See example instructions](https://developer.android.com/studio/gemini/agent-files#example-instructions).

3. Save and commit the file to your VCS to share it with your team.

## Manage `AGENTS.md` files as context

You can apply or remove `AGENTS.md` files as context for a particular query
using the **Context** drawer in the chat panel. The **`AGENTS.md` Files**
options includes all `AGENTS.md` files in the current directory and its parent
directories.
![Manage AGENTS.md files as context](https://developer.android.com/static/studio/gemini/images/context-menu-agent-md.png) **Figure 1.** Manage `AGENTS.md` files as context.

## Example instructions

You can use the `AGENTS.md` file to give instructions to the agent. The
following are some examples, but the instructions that you provide should be
specific to your project.

- "The main activity is `/path/to/MainActivity.kt`."
- "The code to support navigating between screens is `path/to/navigation/UiNavigation.kt`"
- "The code handling HTTP requests is at `<path>`."
- Project architecture
  - "Place all business logic in ViewModels."
  - "Always follow official architecture recommendations, including use of a layered architecture. Use a unidirectional data flow (UDF), ViewModels, lifecycle-aware UI state collection, and other recommendations."
- Preferred libraries: "Use the \<library name\> library for navigation."
- Defining placeholder names for common API services or internal terminology: "The primary backend service is referred to as 'PhotoSift-API'."
- Company style guides: "All new UI components must be built with Jetpack Compose. Don't suggest XML-based layouts."

## Modularize your `AGENTS.md` files

You can break down large `AGENTS.md` files into smaller files that can be reused
in different contexts:

1. Separate out a set of instructions and save them in another Markdown file,
   such as `style-guidance.md`.

2. Reference the smaller Markdown files in an `AGENTS.md` file by using the `@`
   symbol followed by the path to the file you want to import. The following path
   formats are supported:

   - Relative paths:
     - `@./file.md` - Import from the same directory
     - `@../file.md` - Import from the parent directory
     - `@./subdirectory/file.md` - Import from a subdirectory
   - Absolute paths: `@/absolute/path/to/file.md`

For example, the following `AGENTS.md` file references two other instruction
files:

    # My AGENTS.md

    You are an experienced Android app developer.

    @./get-started.md

    ## Coding style {:#coding-style}

    @./shared/style-guidance.md

## How `AGENTS.md` files work

The agent automatically scans the current directory and parent directories for
`AGENTS.md` files and adds their content to the beginning of every prompt as a
preamble. If you don't have a file open when you submit a query, then the
`AGENTS.md` file at the project root (if there is one) is included by default.

> [!NOTE]
> **Note:** If you're using Gemini and have a `GEMINI.md` file and `AGENTS.md` file in the same directory, the `GEMINI.md` file takes precedence.

## What's the difference between `AGENTS.md` files and Rules?

[Rules](https://developer.android.com/studio/gemini/rules) also let you define instructions and preferences
that apply to all prompts. However, rules are defined in the IntelliJ file
`/.idea/project.prompts.xml`, whereas `AGENTS.md` files are saved next to your
source code and are IDE-neutral. We recommend using `AGENTS.md` files if one of
the primary purposes is to share the instructions with your team.

> [!NOTE]
> **Note:** The agent combines rules and instructions in `AGENTS.md` files when processing your query.

## What's the difference between `AGENTS.md` files and skills?

Skills represent on-demand expertise that are invoked when your request
matches a skills description, whereas content in `AGENTS.md` is added to the
beginning of every prompt. We recommend using skills for specific tasks and
`AGENTS.md` files to influence the agent's general behavior. To learn more
about skills, see the [Android skills overview](https://developer.android.com/tools/agents/android-skills).