| **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 Gemini in Android Studio 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. Gemini 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:** 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

    @./shared/style-guidance.md

## How`AGENTS.md`files work

Gemini 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:** If you 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:** Gemini combines rules and instructions in`AGENTS.md`files when processing your query.