Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Improve repo.md documentation to instruct OpenHands on capturing repository context efficiently (#8977)

Graham Neubig5de119dc2edd
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:
+
+```
+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:
-General microagent file example located at `.openhands/microagents/repo.md`:
```
+# 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