Some changes to microagents docs and new micro-agents section (#6020)

CODE_OF_CONDUCT.md

@@ -18,24 +18,24 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
+* Demonstrating empathy and kindness toward other people.
-* Being respectful of differing opinions, viewpoints, and experiences
+* Being respectful of differing opinions, viewpoints, and experiences.
-* Giving and gracefully accepting constructive feedback
+* Giving and gracefully accepting constructive feedback.
 * Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
+  and learning from the experience.
 * Focusing on what is best not just for us as individuals, but for the overall
-  community
+  community.
 
 Examples of unacceptable behavior include:
 
 * The use of sexualized language or imagery, and sexual attention or advances of
-  any kind
+  any kind.
-* Trolling, insulting or derogatory comments, and personal or political attacks
+* Trolling, insulting or derogatory comments, and personal or political attacks.
-* Public or private harassment
+* Public or private harassment.
 * Publishing others' private information, such as a physical or email address,
-  without their explicit permission
+  without their explicit permission.
 * Other conduct which could reasonably be considered inappropriate in a
-  professional setting
+  professional setting.
 
 ## Enforcement Responsibilities
 
@@ -61,7 +61,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-contact@all-hands.dev
+contact@all-hands.dev.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

CONTRIBUTING.md

@@ -11,11 +11,11 @@ To understand the codebase, please refer to the README in each module:
    - [agenthub](./openhands/agenthub/README.md)
    - [server](./openhands/server/README.md)
 
-## Setting up your development environment
+## Setting up Your Development Environment
 
 We have a separate doc [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md) that tells you how to set up a development workflow.
 
-## How can I contribute?
+## How Can I Contribute?
 
 There are many ways that you can contribute:
 
@@ -23,7 +23,7 @@ There are many ways that you can contribute:
 2. **Send feedback** after each session by [clicking the thumbs-up thumbs-down buttons](https://docs.all-hands.dev/modules/usage/feedback), so we can see where things are working and failing, and also build an open dataset for training code agents.
 3. **Improve the Codebase** by sending [PRs](#sending-pull-requests-to-openhands) (see details below). In particular, we have some [good first issues](https://github.com/All-Hands-AI/OpenHands/labels/good%20first%20issue) that may be ones to start on.
 
-## What can I build?
+## What Can I Build?
 Here are a few ways you can help improve the codebase.
 
 #### UI/UX
@@ -35,7 +35,7 @@ of the application, please open an issue first, or better, join the #frontend ch
 to gather consensus from our design team first.
 
 #### Improving the agent
-Our main agent is the CodeAct agent. You can [see its prompts here](https://github.com/All-Hands-AI/OpenHands/tree/main/openhands/agenthub/codeact_agent)
+Our main agent is the CodeAct agent. You can [see its prompts here](https://github.com/All-Hands-AI/OpenHands/tree/main/openhands/agenthub/codeact_agent).
 
 Changes to these prompts, and to the underlying behavior in Python, can have a huge impact on user experience.
 You can try modifying the prompts to see how they change the behavior of the agent as you use the app
@@ -63,7 +63,7 @@ At the moment, we have two kinds of tests: [`unit`](./tests/unit) and [`integrat
 ## Sending Pull Requests to OpenHands
 
 You'll need to fork our repository to send us a Pull Request. You can learn more
-about how to fork a GitHub repo and open a PR with your changes in [this article](https://medium.com/swlh/forks-and-pull-requests-how-to-contribute-to-github-repos-8843fac34ce8)
+about how to fork a GitHub repo and open a PR with your changes in [this article](https://medium.com/swlh/forks-and-pull-requests-how-to-contribute-to-github-repos-8843fac34ce8).
 
 ### Pull Request title
 As described [here](https://github.com/commitizen/conventional-commit-types/blob/master/index.json), a valid PR title should begin with one of the following prefixes:
@@ -103,7 +103,7 @@ Further, if you see an issue you like, please leave a "thumbs-up" or a comment,
 
 ### Making Pull Requests
 
-We're generally happy to consider all [PRs](https://github.com/All-Hands-AI/OpenHands/pulls), with the evaluation process varying based on the type of change:
+We're generally happy to consider all pull requests with the evaluation process varying based on the type of change:
 
 #### For Small Improvements
 

Development.md

@@ -3,7 +3,7 @@ This guide is for people working on OpenHands and editing the source code.
 If you wish to contribute your changes, check out the [CONTRIBUTING.md](https://github.com/All-Hands-AI/OpenHands/blob/main/CONTRIBUTING.md) on how to clone and setup the project initially before moving on.
 Otherwise, you can clone the OpenHands project directly.
 
-## Start the server for development
+## Start the Server for Development
 ### 1. Requirements
 * Linux, Mac OS, or [WSL on Windows](https://learn.microsoft.com/en-us/windows/wsl/install)  [Ubuntu <= 22.04]
 * [Docker](https://docs.docker.com/engine/install/) (For those on MacOS, make sure to allow the default Docker socket to be used from advanced settings!)
@@ -58,7 +58,7 @@ See [our documentation](https://docs.all-hands.dev/modules/usage/llms) for recom
 
 ### 4. Running the application
 #### Option A: Run the Full Application
-Once the setup is complete, launching OpenHands is as simple as running a single command. This command starts both the backend and frontend servers seamlessly, allowing you to interact with OpenHands:
+Once the setup is complete, this command starts both the backend and frontend servers, allowing you to interact with OpenHands:
 ```bash
 make run
 ```
@@ -75,11 +75,11 @@ make run
     ```
 
 ### 6. LLM Debugging
-If you encounter any issues with the Language Model (LM) or you're simply curious, you can inspect the actual LLM prompts and responses. To do so, export DEBUG=1 in the environment and restart the backend.
+If you encounter any issues with the Language Model (LM) or you're simply curious, export DEBUG=1 in the environment and restart the backend.
-OpenHands will then log the prompts and responses in the logs/llm/CURRENT_DATE directory, allowing you to identify the causes.
+OpenHands will log the prompts and responses in the logs/llm/CURRENT_DATE directory, allowing you to identify the causes.
 
 ### 7. Help
-Need assistance or information on available targets and commands? The help command provides all the necessary guidance to ensure a smooth experience with OpenHands.
+Need help or info on available targets and commands? Use the help command for all the guidance you need with OpenHands.
 ```bash
 make help
  ```
@@ -93,8 +93,8 @@ poetry run pytest ./tests/unit/test_*.py
 ```
 
 ### 9. Add or update dependency
-1. Add your dependency in `pyproject.toml` or use `poetry add xxx`
+1. Add your dependency in `pyproject.toml` or use `poetry add xxx`.
-2. Update the poetry.lock file via `poetry lock --no-update`
+2. Update the poetry.lock file via `poetry lock --no-update`.
 
 ### 9. Use existing Docker image
 To reduce build time (e.g., if no changes were made to the client-runtime component), you can use an existing Docker container image by
@@ -110,7 +110,7 @@ TL;DR
 make docker-dev
 ```
 
-See more details [here](./containers/dev/README.md)
+See more details [here](./containers/dev/README.md).
 
 If you are just interested in running `OpenHands` without installing all the required tools on your host.
 

ISSUE_TRIAGE.md

@@ -2,8 +2,8 @@
 These are the procedures and guidelines on how issues are triaged in this repo by the maintainers.
 
 ## General
-* Most issues must be tagged with **enhancement** or **bug**
+* Most issues must be tagged with **enhancement** or **bug**.
-* Issues may be tagged with what it relates to (**backend**, **frontend**, **agent quality**, etc.)
+* Issues may be tagged with what it relates to (**backend**, **frontend**, **agent quality**, etc.).
 
 ## Severity
 * **Low**: Minor issues or affecting single user.
@@ -11,10 +11,10 @@ These are the procedures and guidelines on how issues are triaged in this repo b
 * **Critical**: Affecting all users or potential security issues.
 
 ## Effort
-* Issues may be estimated with effort required (**small effort**, **medium effort**, **large effort**)
+* Issues may be estimated with effort required (**small effort**, **medium effort**, **large effort**).
 
 ## Difficulty
-* Issues with low implementation difficulty may be tagged with **good first issue**
+* Issues with low implementation difficulty may be tagged with **good first issue**.
 
 ## Not Enough Information
 * User is asked to provide more information (logs, how to reproduce, etc.) when the issue is not clear.

docs/modules/usage/prompting/microagents-public.md

@@ -1,17 +1,31 @@
-# Micro-Agents
+# Public Micro-Agents
 
-OpenHands uses specialized micro-agents to handle specific tasks and contexts efficiently. These micro-agents are small, focused components that provide specialized behavior and knowledge for particular scenarios.
+OpenHands uses specialized micro-agents to handle specific tasks and contexts efficiently. These micro-agents are small,
+focused components that provide specialized behavior and knowledge for particular scenarios.
 
 ## Overview
 
-Micro-agents are defined in markdown files under the `openhands/agenthub/codeact_agent/micro/` directory. Each micro-agent is configured with:
+Public micro-agents are defined in markdown files under the
+[`microagents/knowledge/`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents/knowledge) directory.
+Each micro-agent is configured with:
 
 - A unique name.
 - The agent type (typically CodeActAgent).
 - Trigger keywords that activate the agent.
 - Specific instructions and capabilities.
 
-## Available Micro-Agents
+### Integration
+
+Public micro-agents are automatically integrated into OpenHands' workflow. They:
+- Monitor incoming commands for their trigger words.
+- Activate when relevant triggers are detected.
+- Apply their specialized knowledge and capabilities.
+- Follow their specific guidelines and restrictions.
+
+## Available Public Micro-Agents
+
+For more information about specific micro-agents, refer to their individual documentation files in
+the [`micro-agents`](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents) directory.
 
 ### GitHub Agent
 **File**: `github.md`
@@ -29,6 +43,14 @@ Key features:
 - Git configuration management
 - API-first approach for GitHub operations
 
+Usage Example:
+
+```bash
+git checkout -b feature-branch
+git commit -m "Add new feature"
+git push origin feature-branch
+```
+
 ### NPM Agent
 **File**: `npm.md`
 **Triggers**: `npm`
@@ -38,9 +60,15 @@ Specializes in handling npm package management with specific focus on:
 - Automated confirmation handling using Unix 'yes' command.
 - Package installation automation.
 
-### Custom Micro-Agents
+Usage Example:
 
-You can create your own micro-agents by adding new markdown files to the micro-agents directory.
+```bash
+yes | npm install package-name
+```
+
+### Custom Public Micro-Agents
+
+You can create your own public micro-agents by adding new markdown files to the `microagents/knowledge/` directory.
 Each file should follow this structure:
 
 ```markdown
@@ -55,43 +83,29 @@ triggers:
 Instructions and capabilities for the micro-agent...
 ```
 
-## Best Practices
+## Working With Public Micro-Agents
 
-When working with micro-agents:
+When working with public micro-agents:
 - **Use Appropriate Triggers**: Ensure your commands include the relevant trigger words to activate the correct micro-agent.
 - **Follow Agent Guidelines**: Each agent has specific instructions and limitations. Respect these for optimal results.
 - **API-First Approach**: When available, use API endpoints rather than web interfaces.
 - **Automation Friendly**: Design commands that work well in non-interactive environments.
 
-## Integration
+## Contributing a Public Micro-Agent
 
-Micro-agents are automatically integrated into OpenHands' workflow. They:
+Best practices for creating public micro-agents:
-- Monitor incoming commands for their trigger words.
-- Activate when relevant triggers are detected.
-- Apply their specialized knowledge and capabilities.
-- Follow their specific guidelines and restrictions.
 
-## Example Usage
+- **Clear Scope**: Keep the micro-agent focused on a specific domain or task.
+- **Explicit Instructions**: Provide clear, unambiguous guidelines.
+- **Useful Examples**: Include practical examples of common use cases.
+- **Safety First**: Include necessary warnings and constraints.
+- **Integration Awareness**: Consider how the micro-agent interacts with other components.
 
-```bash
+To contribute a new micro-agent to OpenHands:
-# GitHub agent example
-git checkout -b feature-branch
-git commit -m "Add new feature"
-git push origin feature-branch
 
-# NPM agent example
+### 1. Plan the Public Micro-Agent
-yes | npm install package-name
-```
 
-For more information about specific agents, refer to their individual documentation files in the micro-agents directory.
+Before creating a public micro-agent, consider:
-
-## Contributing a Micro-Agent
-
-To contribute a new micro-agent to OpenHands, follow these guidelines:
-
-### 1. Planning Your Micro-Agent
-
-Before creating a micro-agent, consider:
 - What specific problem or use case will it address?
 - What unique capabilities or knowledge should it have?
 - What trigger words make sense for activating it?
@@ -99,11 +113,11 @@ Before creating a micro-agent, consider:
 
 ### 2. File Structure
 
-Create a new markdown file in `openhands/agenthub/codeact_agent/micro/` with a descriptive name (e.g., `docker.md` for a Docker-focused agent).
+Create a new markdown file in `microagents/knowledge/` with a descriptive name (e.g., `docker.md` for a Docker-focused agent).
 
 ### 3. Required Components
 
-Your micro-agent file must include:
+The micro-agent file must include:
 
 - **Front Matter**: YAML metadata at the start of the file:
 ```markdown
@@ -133,15 +147,7 @@ Examples of usage:
 [Example 2]
 ```
 
-### 4. Best Practices for Micro-Agent Development
+### 4. Testing the Public Micro-Agent
-
-- **Clear Scope**: Keep the agent focused on a specific domain or task.
-- **Explicit Instructions**: Provide clear, unambiguous guidelines.
-- **Useful Examples**: Include practical examples of common use cases.
-- **Safety First**: Include necessary warnings and constraints.
-- **Integration Awareness**: Consider how the agent interacts with other components.
-
-### 5. Testing Your Micro-Agent
 
 Before submitting:
 - Test the agent with various prompts.
@@ -149,7 +155,14 @@ Before submitting:
 - Ensure instructions are clear and comprehensive.
 - Check for potential conflicts with existing agents.
 
-### 6. Example Implementation
+### 5. Submission Process
+
+Submit a pull request with:
+- The new micro-agent file.
+- Updated documentation if needed.
+- Description of the agent's purpose and capabilities.
+
+### Example Public Micro-Agent Implementation
 
 Here's a template for a new micro-agent:
 
@@ -197,14 +210,5 @@ Remember to:
 - Optimize for build time and image size
 ```
 
-### 7. Submission Process
-
-1. Create your micro-agent file in the correct directory.
-2. Test thoroughly.
-3. Submit a pull request with:
-   - The new micro-agent file.
-   - Updated documentation if needed.
-   - Description of the agent's purpose and capabilities.
-
 Remember that micro-agents are a powerful way to extend OpenHands' capabilities in specific domains. Well-designed
 agents can significantly improve the system's ability to handle specialized tasks.

docs/modules/usage/prompting/microagents-repo.md

@@ -1,10 +1,12 @@
-# Customizing Agent Behavior
+# Repository Micro-Agents
 
-OpenHands can be customized to work more effectively with specific repositories by providing repository-specific context and guidelines. This section explains how to optimize OpenHands for your project.
+OpenHands can be customized to work more effectively with specific repositories by providing repository-specific context
+and guidelines. This section explains how to optimize OpenHands for your project.
 
 ## Repository Configuration
 
-You can customize OpenHands' behavior for your repository by creating a `.openhands` directory in your repository's root. At minimum, it should contain the file
+You can customize OpenHands' behavior for your repository by creating a `.openhands/microagents/` directory in your repository's root.
+At minimum, it should contain the file
 `.openhands/microagents/repo.md`, which includes instructions that will
 be given to the agent every time it works with this repository.
 
@@ -39,7 +41,8 @@ Guidelines:
 
 ### Customizing Prompts
 
-When working with a repository:
+You may also add customized prompts to the `.openhands/microagents/repo.md` file when working with a repository.
+These could:
 
 - **Reference Project Standards**: Mention specific coding standards or patterns used in your project.
 - **Include Context**: Reference relevant documentation or existing implementations.
@@ -54,14 +57,10 @@ The component should use our shared styling from src/styles/components.
 
 ### Best Practices for Repository Customization
 
-- **Keep Instructions Updated**: Regularly update your `.openhands` directory as your project evolves.
+- **Keep Instructions Updated**: Regularly update your `.openhands/microagents/` directory as your project evolves.
 - **Be Specific**: Include specific paths, patterns, and requirements unique to your project.
 - **Document Dependencies**: List all tools and dependencies required for development.
 - **Include Examples**: Provide examples of good code patterns from your project.
 - **Specify Conventions**: Document naming conventions, file organization, and code style preferences.
 
 By customizing OpenHands for your repository, you'll get more accurate and consistent results that align with your project's standards and requirements.
-
-## Other Microagents
-You can create other instructions in the `.openhands/microagents/` directory
-that will be sent to the agent if a particular keyword is found, like `test`, `frontend`, or `migration`. See [Micro-Agents](microagents.md) for more information.

docs/sidebars.ts

@@ -23,15 +23,21 @@ const sidebars: SidebarsConfig = {
           id: 'usage/prompting/prompting-best-practices',
         },
         {
-          type: 'doc',
+          type: 'category',
-          label: 'Customization',
+          label: 'Micro-Agents',
-          id: 'usage/prompting/customization',
+          items: [
-        },
+            {
-        {
+              type: 'doc',
-          type: 'doc',
+              label: 'Public',
-          label: 'Microagents',
+              id: 'usage/prompting/microagents-public',
-          id: 'usage/prompting/microagents',
+            },
-        },
+            {
+              type: 'doc',
+              label: 'Repository',
+              id: 'usage/prompting/microagents-repo',
+            },
+          ],
+        }
       ],
     },
     {