From 5de119dc2eddb9828860608dbff21312c4717012 Mon Sep 17 00:00:00 2001
From: Graham Neubig <neubig@gmail.com>
Date: Sat, 7 Jun 2025 11:18:54 -0400
Subject: [PATCH] Improve repo.md documentation to instruct OpenHands on
 capturing repository context efficiently (#8977)

Co-authored-by: openhands <openhands@all-hands.dev>
---
 docs/usage/prompting/microagents-overview.mdx |  2 +-
 docs/usage/prompting/microagents-repo.mdx     | 36 +++++++++++++++++--
 microagents/README.md                         |  3 ++
 3 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/docs/usage/prompting/microagents-overview.mdx b/docs/usage/prompting/microagents-overview.mdx
index c38d221a31..abc13c2b8d 100644
--- a/docs/usage/prompting/microagents-overview.mdx
+++ b/docs/usage/prompting/microagents-overview.mdx
@@ -11,7 +11,7 @@ Currently OpenHands supports the following types of microagents:
 - [Keyword-Triggered Microagents](./microagents-keyword): Guidelines activated by specific keywords in prompts.
 
 To customize OpenHands' behavior, create a .openhands/microagents/ directory in the root of your repository and
-add `<microagent_name>.md` files inside.
+add `<microagent_name>.md` files inside. For repository-specific guidelines, you can ask OpenHands to analyze your repository and create a comprehensive `repo.md` file (see [General Microagents](./microagents-repo) for details).
 
 <Note>
 Loaded microagents take up space in the context window.
diff --git a/docs/usage/prompting/microagents-repo.mdx b/docs/usage/prompting/microagents-repo.mdx
index e07923bffc..e5c3943d5b 100644
--- a/docs/usage/prompting/microagents-repo.mdx
+++ b/docs/usage/prompting/microagents-repo.mdx
@@ -17,13 +17,45 @@ Frontmatter should be enclosed in triple dashes (---) and may include the follow
 |-----------|-----------------------------------------|----------|----------------|
 | `agent`   | The agent this microagent applies to    | No       | 'CodeActAgent' |
 
-## Example
+## Creating a Comprehensive Repository Agent
+
+To create an effective repository agent, you can ask OpenHands to analyze your repository with a prompt like:
 
-General microagent file example located at `.openhands/microagents/repo.md`:
 ```
+Please browse the repository, look at the documentation and relevant code, and understand the purpose of this repository.
+
+Specifically, I want you to create a `.openhands/microagents/repo.md` file. This file should contain succinct information that summarizes:
+1. The purpose of this repository
+2. The general setup of this repo
+3. A brief description of the structure of this repo
+
+Read all the GitHub workflows under .github/ of the repository (if this folder exists) to understand the CI checks (e.g., linter, pre-commit), and include those in the repo.md file.
+```
+
+This approach helps OpenHands capture repository context efficiently, reducing the need for repeated searches during conversations and ensuring more accurate solutions.
+
+## Example Content
+
+A comprehensive repository agent file (`.openhands/microagents/repo.md`) should include:
+
+```
+# Repository Purpose
 This project is a TODO application that allows users to track TODO items.
 
+# Setup Instructions
 To set it up, you can run `npm run build`.
+
+# Repository Structure
+- `/src`: Core application code
+- `/tests`: Test suite
+- `/docs`: Documentation
+- `/.github`: CI/CD workflows
+
+# CI/CD Workflows
+- `lint.yml`: Runs ESLint on all JavaScript files
+- `test.yml`: Runs the test suite on pull requests
+
+# Development Guidelines
 Always make sure the tests are passing before committing changes. You can run the tests by running `npm run test`.
 ```
 
diff --git a/microagents/README.md b/microagents/README.md
index f3d8da8b12..33a4193a08 100644
--- a/microagents/README.md
+++ b/microagents/README.md
@@ -117,7 +117,10 @@ You can see an example of a repo agent in [the agent for the OpenHands repo itse
    - Include repository structure details
    - Specify testing and build procedures
    - List environment requirements
+   - Document CI workflows and checks
+   - Include information about code quality standards
    - Maintain up-to-date team practices
+   - Consider using OpenHands to generate a comprehensive repo.md (see [Creating a Repository Agent](#creating-a-repository-agent))
    - YAML frontmatter is optional - files without frontmatter will be loaded with default settings
 
 ### Submission Process