diff --git a/openhands/resolver/README.md b/openhands/resolver/README.md
index 4f955314e2fb..19f60a5d4fc2 100644
--- a/openhands/resolver/README.md
+++ b/openhands/resolver/README.md
@@ -180,7 +180,29 @@ python -m openhands.resolver.send_pull_request --issue-number ISSUE_NUMBER --git
 
 ## Providing Custom Instructions
 
-You can customize how the AI agent approaches issue resolution by adding a `.openhands_instructions` file to the root of your repository. If present, this file's contents will be injected into the prompt for openhands edits.
+You can customize how the AI agent approaches issue resolution by adding repository instructions in `.openhands/microagents/repo.md` file. This file should contain repository-specific information and guidelines that will be injected into the prompt for OpenHands edits.
+
+Example structure for `.openhands/microagents/repo.md`:
+```markdown
+---
+name: repo
+agent: CodeActAgent
+---
+# Repository Instructions
+
+This repository contains [brief description of your project].
+
+## Directory Structure
+- src/: [description]
+- tests/: [description]
+...
+
+## Development Guidelines
+[Your specific coding standards and practices]
+
+## Testing Requirements
+[How to run tests and what types of tests are required]
+```
 
 ## Troubleshooting
 
diff --git a/openhands/resolver/resolve_all_issues.py b/openhands/resolver/resolve_all_issues.py
index 9c44855a2dd4..c575cf4a30a1 100644
--- a/openhands/resolver/resolve_all_issues.py
+++ b/openhands/resolver/resolve_all_issues.py
@@ -123,10 +123,10 @@ async def resolve_issues(
     logger.info(f'Base commit: {base_commit}')
 
     if repo_instruction is None:
-        # Check for .openhands_instructions file in the workspace directory
-        openhands_instructions_path = os.path.join(repo_dir, '.openhands_instructions')
-        if os.path.exists(openhands_instructions_path):
-            with open(openhands_instructions_path, 'r') as f:
+        # Check for repository instructions in .openhands/microagents/repo.md
+        repo_instructions_path = os.path.join(repo_dir, '.openhands/microagents/repo.md')
+        if os.path.exists(repo_instructions_path):
+            with open(repo_instructions_path, 'r') as f:
                 repo_instruction = f.read()
 
     # OUTPUT FILE
diff --git a/openhands/resolver/resolve_issue.py b/openhands/resolver/resolve_issue.py
index 0eb072df6553..1bfebae15a41 100644
--- a/openhands/resolver/resolve_issue.py
+++ b/openhands/resolver/resolve_issue.py
@@ -402,10 +402,10 @@ async def resolve_issue(
     logger.info(f'Base commit: {base_commit}')
 
     if repo_instruction is None:
-        # Check for .openhands_instructions file in the workspace directory
-        openhands_instructions_path = os.path.join(repo_dir, '.openhands_instructions')
-        if os.path.exists(openhands_instructions_path):
-            with open(openhands_instructions_path, 'r') as f:
+        # Check for repository instructions in .openhands/microagents/repo.md
+        repo_instructions_path = os.path.join(repo_dir, '.openhands/microagents/repo.md')
+        if os.path.exists(repo_instructions_path):
+            with open(repo_instructions_path, 'r') as f:
                 repo_instruction = f.read()
 
     # OUTPUT FILE
diff --git a/openhands/runtime/base.py b/openhands/runtime/base.py
index c86cba1b055a..9305b48ea057 100644
--- a/openhands/runtime/base.py
+++ b/openhands/runtime/base.py
@@ -225,13 +225,15 @@ def get_custom_microagents(self, selected_repository: str | None) -> list[str]:
             dir_name = str(
                 Path(selected_repository.split('/')[1]) / custom_microagents_dir
             )
+        # Legacy support for .openhands_instructions
         obs = self.read(FileReadAction(path='.openhands_instructions'))
-        if isinstance(obs, ErrorObservation):
-            self.log('debug', 'openhands_instructions not present')
-        else:
+        if not isinstance(obs, ErrorObservation):
+            self.log('info', 'Found legacy .openhands_instructions file')
             openhands_instructions = obs.content
             self.log('info', f'openhands_instructions: {openhands_instructions}')
             custom_microagents_content.append(openhands_instructions)
+        else:
+            self.log('debug', '.openhands_instructions not present')
 
         files = self.list_files(dir_name)