From 5f906a3192ac1821b2830e525c244c701d74b728 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 21 Oct 2025 15:16:20 +0000 Subject: [PATCH 1/8] Add comprehensive microagent documentation to repo.md - Added detailed explanation of all 4 microagent types (general, keyword-triggered, org/user, global) - Included frontmatter format examples and best practices - Added repository structure visualization - Documented microagent-specific workflows and contributor guidelines - Preserved all existing documentation system content - Added CI/CD workflow information The repo.md microagent now serves as both a guide to the repository and a comprehensive reference for creating and using microagents. --- .openhands/microagents/repo.md | 135 ++++++++++++++++++++++++++++++++- 1 file changed, 131 insertions(+), 4 deletions(-) diff --git a/.openhands/microagents/repo.md b/.openhands/microagents/repo.md index 24ac8e26..4fbc81c5 100644 --- a/.openhands/microagents/repo.md +++ b/.openhands/microagents/repo.md @@ -1,7 +1,96 @@ -# Documentation System Overview +# OpenHands Documentation Repository + +This repository contains the official documentation for OpenHands, including guides for the core application and the Agent SDK. The documentation is deployed using Mintlify and features an automated code synchronization system. + +## Repository Purpose + +- **OpenHands Docs**: User guides, tutorials, and reference documentation for OpenHands core application +- **Agent SDK Docs**: Developer documentation for the OpenHands Agent SDK +- **Microagents Documentation**: Guidelines for creating and using microagents (specialized prompts) + +## Microagents in This Repository + +This repository demonstrates the use of microagents - specialized prompts that provide domain-specific knowledge to OpenHands. You are currently reading the `repo.md` general microagent. + +### Microagent Types + +1. **General Microagents** (e.g., `.openhands/microagents/repo.md`) + - Always loaded as part of the context + - Provide repository-specific guidelines and knowledge + - No frontmatter required (optional `agent` field defaults to 'CodeActAgent') + +2. **Keyword-Triggered Microagents** (e.g., `.openhands/microagents/trigger_name.md`) + - Loaded only when specific keywords appear in prompts + - Frontmatter with `triggers` field is **required** + - Format: + ```yaml + --- + triggers: + - keyword1 + - keyword2 + agent: CodeActAgent # optional, defaults to CodeActAgent + --- + ``` + +3. **Organization/User Microagents** + - Placed in a `.openhands` repository under the organization or user + - Applied to all repositories belonging to that organization/user + - Can be any type (general or keyword-triggered) + - For GitLab: use `openhands-config` repository name instead + +4. **Global Microagents** + - Keyword-triggered microagents in the main OpenHands repository + - Available to all OpenHands users + - Located at `github.com/All-Hands-AI/OpenHands/tree/main/microagents` + +### Creating Effective Microagents + +**Best Practices:** +- Keep microagents focused on specific domains or tasks +- Use clear, unambiguous instructions +- Include practical examples of common use cases +- Specify any constraints or limitations +- For keyword triggers, use specific words to avoid false activations +- Document required credentials or environment variables +- Consider how the microagent interacts with other components + +**When to Create a Microagent:** +- Repository-specific guidelines that should always be followed +- Domain expertise for specific tools, languages, or frameworks +- Automated responses for common patterns or requests +- Integration guidance for external APIs or services + +## Repository Structure -The documentation for this project follows a synchronized approach where code examples in the docs are automatically kept in sync with the actual example files in the agent-sdk repository. +``` +docs/ +├── .openhands/microagents/ # Repository microagents (like this file) +├── .github/ +│ ├── scripts/ +│ │ └── sync_code_blocks.py # Code synchronization script +│ └── workflows/ # CI/CD workflows +├── openhands/ # OpenHands core documentation +│ └── usage/ +│ ├── microagents/ # Microagent documentation +│ ├── cloud/ # Cloud service docs +│ ├── settings/ # Settings documentation +│ └── ... +├── sdk/ # Agent SDK documentation +│ ├── guides/ # SDK tutorials and guides +│ └── arch/ # Architecture documentation +└── docs.json # Mintlify navigation configuration +``` + +### Key Files + +- **`docs.json`**: Mintlify configuration including navigation structure, theme, and redirects +- **Microagent docs**: `openhands/usage/microagents/microagents-*.mdx` +- **Sync script**: `.github/scripts/sync_code_blocks.py` +- **This microagent**: `.openhands/microagents/repo.md` +## Documentation System Overview + +The documentation follows a synchronized approach where code examples are automatically kept in sync with actual example files in the agent-sdk repository. ## Automatic Code Synchronization @@ -213,6 +302,44 @@ name: Example Workflow on: [push] ``` -## Mintlify documentation +## Mintlify Documentation + +You can check https://www.mintlify.com/docs for documentation on what our doc site supports. + +## Working with Microagent Documentation + +When modifying microagent-related documentation files: + +1. **Location**: Microagent documentation is in `openhands/usage/microagents/` +2. **Navigation**: Update `docs.json` if adding new pages to the microagents section +3. **Consistency**: Follow the existing structure in microagent documentation files +4. **Cross-references**: Link between related microagent pages using relative paths +5. **Examples**: Include practical examples with proper code blocks (non-synced) + +### Key Microagent Documentation Files + +- `microagents-overview.mdx`: Introduction and types of microagents +- `microagents-repo.mdx`: General microagents (always loaded) +- `microagents-keyword.mdx`: Keyword-triggered microagents +- `microagents-org.mdx`: Organization and user microagents +- `microagents-public.mdx`: Global microagents (contributing guide) + +## CI/CD Workflows + +### Code Synchronization Workflow +- **File**: `.github/workflows/sync-docs-code-blocks.yml` +- **Triggers**: Push to any branch, daily at 2 AM UTC, manual dispatch +- **Purpose**: Keeps code blocks in sync with agent-sdk examples +- **Actions**: Checks out both repositories, runs sync script, commits changes if needed + +### OpenAPI Sync Workflow +- **File**: `.github/workflows/sync-agent-sdk-openapi.yml` +- **Purpose**: Syncs OpenAPI specifications for API documentation + +## Notes for Contributors -You can check https://www.mintlify.com/docs for documentation on what our doc site supported. +- Microagents take up context window space - keep them focused and concise +- Test keyword triggers to ensure they activate appropriately +- For agent-sdk examples, ensure the file path in code blocks is correct +- When adding new microagent types, update both the code and documentation +- Remember: this repo.md file is itself a microagent example! From 725f91fb14907784f791f2387706de64a163e58d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 21 Oct 2025 15:17:43 +0000 Subject: [PATCH 2/8] docs: sync code blocks from agent-sdk examples Synced from agent-sdk ref: main --- agent-sdk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agent-sdk b/agent-sdk index 74cc24f5..8d8134ca 160000 --- a/agent-sdk +++ b/agent-sdk @@ -1 +1 @@ -Subproject commit 74cc24f5ad15f9dff21dfaf77840f588718c7b10 +Subproject commit 8d8134ca5a87cc3e90e3ff968327a7f4c961e22e From 5a6ab9650e620aaf325a95230607dd51e503ee72 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 21 Oct 2025 15:25:43 +0000 Subject: [PATCH 3/8] Remove redundant Microagents Documentation from Repository Purpose The repo.md file itself is the microagent, so listing 'Microagents Documentation' as a separate purpose is redundant. --- .openhands/microagents/repo.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.openhands/microagents/repo.md b/.openhands/microagents/repo.md index 4fbc81c5..62d0bbc7 100644 --- a/.openhands/microagents/repo.md +++ b/.openhands/microagents/repo.md @@ -6,7 +6,6 @@ This repository contains the official documentation for OpenHands, including gui - **OpenHands Docs**: User guides, tutorials, and reference documentation for OpenHands core application - **Agent SDK Docs**: Developer documentation for the OpenHands Agent SDK -- **Microagents Documentation**: Guidelines for creating and using microagents (specialized prompts) ## Microagents in This Repository From 0ac79fae4bd90794e0dbedaa2eea7a7e7f61d80c Mon Sep 17 00:00:00 2001 From: Xingyao Wang Date: Tue, 21 Oct 2025 23:26:54 +0800 Subject: [PATCH 4/8] Apply suggestion from @xingyaoww --- .openhands/microagents/repo.md | 51 ---------------------------------- 1 file changed, 51 deletions(-) diff --git a/.openhands/microagents/repo.md b/.openhands/microagents/repo.md index 62d0bbc7..5bc69007 100644 --- a/.openhands/microagents/repo.md +++ b/.openhands/microagents/repo.md @@ -7,57 +7,6 @@ This repository contains the official documentation for OpenHands, including gui - **OpenHands Docs**: User guides, tutorials, and reference documentation for OpenHands core application - **Agent SDK Docs**: Developer documentation for the OpenHands Agent SDK -## Microagents in This Repository - -This repository demonstrates the use of microagents - specialized prompts that provide domain-specific knowledge to OpenHands. You are currently reading the `repo.md` general microagent. - -### Microagent Types - -1. **General Microagents** (e.g., `.openhands/microagents/repo.md`) - - Always loaded as part of the context - - Provide repository-specific guidelines and knowledge - - No frontmatter required (optional `agent` field defaults to 'CodeActAgent') - -2. **Keyword-Triggered Microagents** (e.g., `.openhands/microagents/trigger_name.md`) - - Loaded only when specific keywords appear in prompts - - Frontmatter with `triggers` field is **required** - - Format: - ```yaml - --- - triggers: - - keyword1 - - keyword2 - agent: CodeActAgent # optional, defaults to CodeActAgent - --- - ``` - -3. **Organization/User Microagents** - - Placed in a `.openhands` repository under the organization or user - - Applied to all repositories belonging to that organization/user - - Can be any type (general or keyword-triggered) - - For GitLab: use `openhands-config` repository name instead - -4. **Global Microagents** - - Keyword-triggered microagents in the main OpenHands repository - - Available to all OpenHands users - - Located at `github.com/All-Hands-AI/OpenHands/tree/main/microagents` - -### Creating Effective Microagents - -**Best Practices:** -- Keep microagents focused on specific domains or tasks -- Use clear, unambiguous instructions -- Include practical examples of common use cases -- Specify any constraints or limitations -- For keyword triggers, use specific words to avoid false activations -- Document required credentials or environment variables -- Consider how the microagent interacts with other components - -**When to Create a Microagent:** -- Repository-specific guidelines that should always be followed -- Domain expertise for specific tools, languages, or frameworks -- Automated responses for common patterns or requests -- Integration guidance for external APIs or services ## Repository Structure From 24610d1fa88476cb6a96594ae897eccc308c9cc7 Mon Sep 17 00:00:00 2001 From: Xingyao Wang Date: Tue, 21 Oct 2025 23:27:10 +0800 Subject: [PATCH 5/8] Apply suggestion from @xingyaoww --- .openhands/microagents/repo.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.openhands/microagents/repo.md b/.openhands/microagents/repo.md index 5bc69007..b27e7725 100644 --- a/.openhands/microagents/repo.md +++ b/.openhands/microagents/repo.md @@ -7,7 +7,6 @@ This repository contains the official documentation for OpenHands, including gui - **OpenHands Docs**: User guides, tutorials, and reference documentation for OpenHands core application - **Agent SDK Docs**: Developer documentation for the OpenHands Agent SDK - ## Repository Structure ``` From 7e529e0b0fea16bbaf8d7deb621789095cfeb4e3 Mon Sep 17 00:00:00 2001 From: Xingyao Wang Date: Tue, 21 Oct 2025 23:28:00 +0800 Subject: [PATCH 6/8] Apply suggestion from @xingyaoww --- .openhands/microagents/repo.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/.openhands/microagents/repo.md b/.openhands/microagents/repo.md index b27e7725..23956fb6 100644 --- a/.openhands/microagents/repo.md +++ b/.openhands/microagents/repo.md @@ -253,24 +253,6 @@ on: [push] You can check https://www.mintlify.com/docs for documentation on what our doc site supports. -## Working with Microagent Documentation - -When modifying microagent-related documentation files: - -1. **Location**: Microagent documentation is in `openhands/usage/microagents/` -2. **Navigation**: Update `docs.json` if adding new pages to the microagents section -3. **Consistency**: Follow the existing structure in microagent documentation files -4. **Cross-references**: Link between related microagent pages using relative paths -5. **Examples**: Include practical examples with proper code blocks (non-synced) - -### Key Microagent Documentation Files - -- `microagents-overview.mdx`: Introduction and types of microagents -- `microagents-repo.mdx`: General microagents (always loaded) -- `microagents-keyword.mdx`: Keyword-triggered microagents -- `microagents-org.mdx`: Organization and user microagents -- `microagents-public.mdx`: Global microagents (contributing guide) - ## CI/CD Workflows ### Code Synchronization Workflow From 6a159a524db535191b2e2eac6c3b060deba6ac3c Mon Sep 17 00:00:00 2001 From: Xingyao Wang Date: Tue, 21 Oct 2025 23:29:59 +0800 Subject: [PATCH 7/8] Apply suggestion from @xingyaoww --- .openhands/microagents/repo.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/.openhands/microagents/repo.md b/.openhands/microagents/repo.md index 23956fb6..5f3e4da9 100644 --- a/.openhands/microagents/repo.md +++ b/.openhands/microagents/repo.md @@ -267,8 +267,6 @@ You can check https://www.mintlify.com/docs for documentation on what our doc si ## Notes for Contributors -- Microagents take up context window space - keep them focused and concise -- Test keyword triggers to ensure they activate appropriately - For agent-sdk examples, ensure the file path in code blocks is correct -- When adding new microagent types, update both the code and documentation -- Remember: this repo.md file is itself a microagent example! +- For short agent-sdk examples, you don't need `expandable` in example file +- When you add new pages that need to refer to agent-sdk example script, you should create an empty block with correct block name (refer to the python example script correctly), then run `python .github/scripts/sync_code_blocks.py` to sync it From 9da54dd953910dcd50bc928ba62b4272e4f78db7 Mon Sep 17 00:00:00 2001 From: Xingyao Wang Date: Tue, 21 Oct 2025 23:36:21 +0800 Subject: [PATCH 8/8] Update .openhands/microagents/repo.md Co-authored-by: Engel Nyst --- .openhands/microagents/repo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.openhands/microagents/repo.md b/.openhands/microagents/repo.md index 5f3e4da9..8056b0e5 100644 --- a/.openhands/microagents/repo.md +++ b/.openhands/microagents/repo.md @@ -1,6 +1,6 @@ # OpenHands Documentation Repository -This repository contains the official documentation for OpenHands, including guides for the core application and the Agent SDK. The documentation is deployed using Mintlify and features an automated code synchronization system. +This repository contains the official documentation for OpenHands, including guides for the Agent SDK and the client OpenHands applications. The documentation is deployed using Mintlify and features an automated code synchronization system. ## Repository Purpose