fix(backend): ensure microagents are loaded for V1 conversations (#11772)

Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

skills/README.md

@@ -0,0 +1,160 @@
+# OpenHands Skills
+
+Skills are specialized prompts that enhance OpenHands with domain-specific knowledge and task-specific workflows. They help developers by providing expert guidance, automating common tasks, and ensuring consistent practices across projects. Each skill is designed to excel in a specific area, from Git operations to code review processes.
+
+## Terminology Note
+
+**Version 0 (V0)**: The term "microagents" continues to be used for V0 conversations. V0 is the current stable version of OpenHands.
+
+**Version 1 (V1)**: The term "skills" is used for V1 conversations. V1 UI and app server have not yet been released, but the codebase has been updated to use "skills" terminology in preparation for the V1 release.
+
+This directory (`OpenHands/skills/`) contains shareable skills that will be used in V1 conversations. For V0 conversations, the system continues to use microagents from the same underlying files.
+
+## Sources of Skills/Microagents
+
+OpenHands loads skills (V1) or microagents (V0) from two sources:
+
+### 1. Shareable Skills/Microagents (Public)
+
+This directory (`OpenHands/skills/`) contains shareable skills (V1) or microagents (V0) that are:
+
+- Available to all OpenHands users
+- Maintained in the OpenHands repository
+- Perfect for reusable knowledge and common workflows
+- Used as "skills" in V1 conversations and "microagents" in V0 conversations
+
+Directory structure:
+
+```
+OpenHands/skills/
+├── # Keyword-triggered expertise
+│   ├── git.md         # Git operations
+│   ├── testing.md     # Testing practices
+│   └── docker.md      # Docker guidelines
+└── # These skills/microagents are always loaded
+    ├── pr_review.md   # PR review process
+    ├── bug_fix.md     # Bug fixing workflow
+    └── feature.md     # Feature implementation
+```
+
+### 2. Repository Instructions (Private)
+
+Each repository can have its own instructions in `.openhands/microagents/` (V0) or `.openhands/skills/` (V1). These instructions are:
+
+- Private to that repository
+- Automatically loaded when working with that repository
+- Perfect for repository-specific guidelines and team practices
+- V1 supports both `.openhands/skills/` (preferred) and `.openhands/microagents/` (backward compatibility)
+
+Example repository structure:
+
+```
+your-repository/
+└── .openhands/
+    ├── skills/        # V1: Preferred location for repository-specific skills
+    │   └── repo.md    # Repository-specific instructions
+    │   └── ...        # Private skills that are only available inside this
+    └── microagents/   # V0: Current location (also supported in V1 for backward compatibility)
+        └── repo.md    # Repository-specific instructions
+        └── ...        # Private micro-agents that are only available inside this repo
+```
+
+## Loading Order
+
+When OpenHands works with a repository, it:
+
+1. Loads repository-specific instructions from `.openhands/microagents/repo.md` (V0) or `.openhands/skills/` (V1) if present
+2. Loads relevant knowledge agents based on keywords in conversations
+
+**Note**: V1 also supports loading from `.openhands/microagents/` for backward compatibility.
+
+## Types of Skills/Microagents
+
+Most skills/microagents use markdown files with YAML frontmatter. For repository agents (repo.md), the frontmatter is optional - if not provided, the file will be loaded with default settings as a repository agent.
+
+### 1. Knowledge Agents
+
+Knowledge agents provide specialized expertise that's triggered by keywords in conversations. They help with:
+
+- Language best practices
+- Framework guidelines
+- Common patterns
+- Tool usage
+
+Key characteristics:
+
+- **Trigger-based**: Activated by specific keywords in conversations
+- **Context-aware**: Provide relevant advice based on file types and content
+- **Reusable**: Knowledge can be applied across multiple projects
+- **Versioned**: Support multiple versions of tools/frameworks
+
+You can see an example of a knowledge-based agent in [OpenHands's github skill](https://github.com/OpenHands/OpenHands/tree/main/skills/github.md).
+
+### 2. Repository Agents
+
+Repository agents provide repository-specific knowledge and guidelines. They are:
+
+- Loaded from `.openhands/microagents/repo.md` (V0) or `.openhands/skills/` directory (V1)
+- V1 also supports `.openhands/microagents/` for backward compatibility
+- Specific to individual repositories
+- Automatically activated for their repository
+- Perfect for team practices and project conventions
+
+Key features:
+
+- **Project-specific**: Contains guidelines unique to the repository
+- **Team-focused**: Enforces team conventions and practices
+- **Always active**: Automatically loaded for the repository
+- **Locally maintained**: Updated with the project
+
+You can see an example of a repo agent in [the agent for the OpenHands repo itself](https://github.com/OpenHands/OpenHands/blob/main/.openhands/microagents/repo.md).
+
+## Contributing
+
+### When to Contribute
+
+1. **Knowledge Agents** - When you have:
+
+   - Language/framework best practices
+   - Tool usage patterns
+   - Common problem solutions
+   - General development guidelines
+
+2. **Repository Agents** - When you need:
+   - Project-specific guidelines
+   - Team conventions and practices
+   - Custom workflow documentation
+   - Repository-specific setup instructions
+
+### Best Practices
+
+1. **For Knowledge Agents**:
+
+   - Choose distinctive triggers
+   - Focus on one area of expertise
+   - Include practical examples
+   - Use file patterns when relevant
+   - Keep knowledge general and reusable
+
+2. **For Repository Agents**:
+   - Document clear setup instructions
+   - 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
+
+1. Create your agent file in the appropriate directory:
+   - `skills/` for expertise (public, shareable)
+   - Note: Repository-specific agents should remain in their respective repositories' `.openhands/skills/` (V1) or `.openhands/microagents/` (V0) directory
+2. Test thoroughly
+3. Submit a pull request to OpenHands
+
+## License
+
+All skills/microagents are subject to the same license as OpenHands. See the root LICENSE file for details.

skills/add_agent.md

@@ -0,0 +1,40 @@
+---
+name: add_agent
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+  - new agent
+  - new microagent
+  - create agent
+  - create an agent
+  - create microagent
+  - create a microagent
+  - add agent
+  - add an agent
+  - add microagent
+  - add a microagent
+  - microagent template
+---
+
+This agent helps create new microagents in the `.openhands/microagents` directory by providing guidance and templates.
+
+Microagents are specialized prompts that provide context and capabilities for specific domains or tasks. They are activated by trigger words in the conversation and help the AI assistant understand what capabilities are available, how to use specific APIs or tools, what limitations exist, and how to handle common scenarios.
+
+When creating a new microagent:
+
+- Create a markdown file in `.openhands/microagents/` with an appropriate name (e.g., `github.md`, `google_workspace.md`)
+- Include YAML frontmatter with metadata (name, type, version, agent, triggers)
+- type is by DEFAULT knowledge
+- version is DEFAULT 1.0.0
+- agent is by DEFAULT CodeActAgent
+- Document any credentials, environment variables, or API access needed
+- Keep trigger words specific to avoid false activations
+- Include error handling guidance and limitations
+- Provide clear usage examples
+- Keep the prompt focused and concise
+
+For detailed information, see:
+
+- [Microagents Overview](https://docs.all-hands.dev/usage/prompting/microagents-overview)
+- [Example GitHub Skill](https://github.com/OpenHands/OpenHands/blob/main/skills/github.md)

skills/add_repo_inst.md

@@ -0,0 +1,65 @@
+---
+name: add_repo_inst
+version: 1.0.0
+author: openhands
+agent: CodeActAgent
+triggers:
+- /add_repo_inst
+inputs:
+  - name: REPO_FOLDER_NAME
+    description: "Branch for the agent to work on"
+---
+
+Please browse the current repository under /workspace/{{ REPO_FOLDER_NAME }}, 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, and (3) a brief description of the structure of this repo.
+
+Here's an example:
+```markdown
+---
+name: repo
+type: repo
+agent: CodeActAgent
+---
+
+This repository contains the code for OpenHands, an automated AI software engineer. It has a Python backend
+(in the `openhands` directory) and React frontend (in the `frontend` directory).
+
+## General Setup:
+To set up the entire repo, including frontend and backend, run `make build`.
+You don't need to do this unless the user asks you to, or if you're trying to run the entire application.
+
+Before pushing any changes, you should ensure that any lint errors or simple test errors have been fixed.
+
+* If you've made changes to the backend, you should run `pre-commit run --all-files --config ./dev_config/python/.pre-commit-config.yaml`
+* If you've made changes to the frontend, you should run `cd frontend && npm run lint:fix && npm run build ; cd ..`
+
+If either command fails, it may have automatically fixed some issues. You should fix any issues that weren't automatically fixed,
+then re-run the command to ensure it passes.
+
+## Repository Structure
+Backend:
+- Located in the `openhands` directory
+- Testing:
+  - All tests are in `tests/unit/test_*.py`
+  - To test new code, run `poetry run pytest tests/unit/test_xxx.py` where `xxx` is the appropriate file for the current functionality
+  - Write all tests with pytest
+
+Frontend:
+- Located in the `frontend` directory
+- Prerequisites: A recent version of NodeJS / NPM
+- Setup: Run `npm install` in the frontend directory
+- Testing:
+  - Run tests: `npm run test`
+  - To run specific tests: `npm run test -- -t "TestName"`
+- Building:
+  - Build for production: `npm run build`
+- Environment Variables:
+  - Set in `frontend/.env` or as environment variables
+  - Available variables: VITE_BACKEND_HOST, VITE_USE_TLS, VITE_INSECURE_SKIP_VERIFY, VITE_FRONTEND_PORT
+- Internationalization:
+  - Generate i18n declaration file: `npm run make-i18n`
+```
+
+Now, please write a similar markdown for the current repository.
+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.

skills/address_pr_comments.md

@@ -0,0 +1,19 @@
+---
+name: address_pr_comments
+version: 1.0.0
+author: openhands
+agent: CodeActAgent
+triggers:
+- /address_pr_comments
+inputs:
+  - name: PR_URL
+    description: "URL of the pull request"
+  - name: BRANCH_NAME
+    description: "Branch name corresponds to the pull request"
+---
+
+First, check the branch {{ BRANCH_NAME }} and read the diff against the main branch to understand the purpose.
+
+This branch corresponds to this PR {{ PR_URL }}
+
+Next, you should use the GitHub API to read the reviews and comments on this PR and address them.

skills/agent-builder.md

@@ -0,0 +1,39 @@
+---
+name: agent_sdk_builder
+version: 1.0.0
+author: openhands
+agent: CodeActAgent
+triggers:
+  - /agent-builder
+inputs:
+  - name: INITIAL_PROMPT
+    description: "Initial SDK requirements"
+---
+
+# Agent Builder and Interviewer Role
+
+You are an expert requirements gatherer and agent builder. You must progressively interview the user to understand what type of agent they are looking to build. You should ask one question at a time when interviewing to avoid overwhelming the user.
+
+Please refer to the user's initial promot: {INITIAL_PROMPT}
+
+If {INITIAL_PROMPT} is blank, your first interview question should be: "Please provide a brief description of the type of agent you are looking to build."
+
+# Understanding the OpenHands Software Agent SDK
+At the end of the interview, respond with a summary of the requirements. Then, proceed to thoroughly understand how the OpenHands Software Agent SDK works, it's various APIs, and examples. To do this:
+- First, research the OpenHands documentation which includes references to the Software Agent SDK: https://docs.openhands.dev/llms.txt
+- Then, clone the examples into a temporary workspace folder (under "temp/"): https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk
+- Then, clone the SDK docs into the same temporary workspace folder: https://github.com/OpenHands/docs/tree/main/sdk
+
+After analyzing the OpenHands Agent SDK, you may optionally ask additional clarifying questions in case it's important for the technical design of the agent.
+
+# Generating the SDK Plan
+You can then proceed to build a technical implementation plan based on the user requirements and your understanding of how the OpenHands Agent SDK works.
+- The plan should be stored in "plan/SDK_PLAN.md" from the root of the workspace.
+- A visual representation of how the agent should work based on the SDK_PLAN.md. This should look like a flow diagram with nodes and edges. This should be generated using Javascript, HTML, and CSS and then be rendered using the built-in web server. Store this in the plan/ directory.
+
+# Implementing the Plan
+After the plan is generated, please ask the user if they are ready to generate the SDK implementation. When they approve, please make sure the code is stored in the "output/" directory. Make sure the code provides logging that a user can see in the terminal. Ideally, the SDK is a single python file.
+
+Additional guidelines:
+- Users can configure their LLM API Key using an environment variable named "LLM_API_KEY"
+- Unless otherwise specified, default to this model: openhands/claude-sonnet-4-20250514. This is configurable through the LLM_BASE_MODEL environment variable.

skills/agent_memory.md

@@ -0,0 +1,32 @@
+---
+name: agent_memory
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- /remember
+---
+
+* Repository memory: Use .openhands/microagents/repo.md under each repository root to store and access important information.
+  - If this file exists, it will be added to your context automatically.
+  - If missing, you should create it unless the user has explicitly asked you to not do so.
+
+* Store and maintain **general knowledge** that will be helpful for most future tasks:
+  1. Repository structure
+  2. Common commands (build, lint, test, pre-commit, etc.)
+  3. Code style preferences
+  4. Workflows and best practices
+  5. Any other repository-specific knowledge you learn
+
+* IMPORTANT: ONLY LOG the information that would be helpful for different future tasks, for example, how to configure the settings, how to setup the repository. Do NOT add issue-specific information (e.g., what specific error you have ran into and how you fix it).
+
+* When adding new information:
+  - ALWAYS ask for user confirmation first by listing the exact items (numbered 1, 2, 3, etc.) you plan to save to repo.md
+  - Only save the items the user approves (they may ask you to save a subset)
+  - Ensure it integrates nicely with existing knowledge in repo.md
+  - Reorganize the content if needed to maintain clarity and organization
+  - Group related information together under appropriate sections or headings
+  - If you've only explored a portion of the codebase, clearly note this limitation in the repository structure documentation
+  - If you don't know the essential commands for working with the repository, such as lint or typecheck, ask the user and suggest adding them to repo.md for future reference (with permission)
+
+When you receive this message, please review and summarize your recent actions and observations, then present a list of valuable information that should be saved in repo.md to the user.

skills/bitbucket.md

@@ -0,0 +1,35 @@
+---
+name: bitbucket
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- bitbucket
+- git
+---
+
+You have access to an environment variable, `BITBUCKET_TOKEN`, which allows you to interact with
+the Bitbucket API.
+
+<IMPORTANT>
+You can use `curl` with the `BITBUCKET_TOKEN` to interact with Bitbucket's API.
+ALWAYS use the Bitbucket API for operations instead of a web browser.
+ALWAYS use the `create_bitbucket_pr` tool to open a pull request
+</IMPORTANT>
+
+If you encounter authentication issues when pushing to Bitbucket (such as password prompts or permission errors), the old token may have expired. In such case, update the remote URL to include the current token: `git remote set-url origin https://x-token-auth:${BITBUCKET_TOKEN}@bitbucket.org/username/repo.git`
+
+Here are some instructions for pushing, but ONLY do this if the user asks you to:
+* NEVER push directly to the `main` or `master` branch
+* Git config (username and email) is pre-set. Do not modify.
+* You may already be on a branch starting with `openhands-workspace`. Create a new branch with a better name before pushing.
+* Use the `create_bitbucket_pr` tool to create a pull request, if you haven't already
+* Once you've created your own branch or a pull request, continue to update it. Do NOT create a new one unless you are explicitly asked to. Update the PR title and description as necessary, but don't change the branch name.
+* Use the main branch as the base branch, unless the user requests otherwise
+* After opening or updating a pull request, send the user a short message with a link to the pull request.
+* Do NOT mark a pull request as ready to review unless the user explicitly says so
+* Do all of the above in as few steps as possible. E.g. you could push changes with one step by running the following bash commands:
+```bash
+git remote -v && git branch # to find the current org, repo and branch
+git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
+```

skills/code-review.md

@@ -0,0 +1,54 @@
+---
+triggers:
+- /codereview
+---
+
+PERSONA:
+You are an expert software engineer and code reviewer with deep experience in modern programming best practices, secure coding, and clean code principles.
+
+TASK:
+Review the code changes in this pull request or merge request, and provide actionable feedback to help the author improve code quality, maintainability, and security. DO NOT modify the code; only provide specific feedback.
+
+CONTEXT:
+You have full context of the code being committed in the pull request or merge request, including the diff, surrounding files, and project structure. The code is written in a modern language and follows typical idioms and patterns for that language.
+
+ROLE:
+As an automated reviewer, your role is to analyze the code changes and produce structured comments, including line numbers, across the following scenarios:
+
+CODE REVIEW SCENARIOS:
+1. Style and Formatting
+Check for:
+- Inconsistent indentation, spacing, or bracket usage
+- Unused imports or variables
+- Non-standard naming conventions
+- Missing or misformatted comments/docstrings
+- Violations of common language-specific style guides (e.g., PEP8, Google Style Guide)
+
+2. Clarity and Readability
+Identify:
+- Overly complex or deeply nested logic
+- Functions doing too much (violating single responsibility)
+- Poor naming that obscures intent
+- Missing inline documentation for non-obvious logic
+
+3. Security and Common Bug Patterns
+Watch for:
+- Unsanitized user input (e.g., in SQL, shell, or web contexts)
+- Hardcoded secrets or credentials
+- Incorrect use of cryptographic libraries
+- Common pitfalls (null dereferencing, off-by-one errors, race conditions)
+
+INSTRUCTIONS FOR RESPONSE:
+Group the feedback by the scenarios above.
+
+Then, for each issue you find:
+- Provide a line number or line range
+- Briefly explain why it's an issue
+- Suggest a concrete improvement
+
+Use the following structure in your output:
+[src/utils.py, Line 42] :hammer_and_wrench: Unused import: The 'os' module is imported but never used. Remove it to clean up the code.
+[src/database.py, Lines 78–85] :mag: Readability: This nested if-else block is hard to follow. Consider refactoring into smaller functions or using early returns.
+[src/auth.py, Line 102] :closed_lock_with_key: Security Risk: User input is directly concatenated into an SQL query. This could allow SQL injection. Use parameterized queries instead.
+
+REMEMBER, DO NOT MODIFY THE CODE. ONLY PROVIDE FEEDBACK IN YOUR RESPONSE.

skills/codereview-roasted.md

@@ -0,0 +1,104 @@
+---
+triggers:
+- /codereview-roasted
+---
+
+PERSONA:
+You are a critical code reviewer with the engineering mindset of Linus Torvalds. Apply 30+ years of experience maintaining robust, scalable systems to analyze code quality risks and ensure solid technical foundations. You prioritize simplicity, pragmatism, and "good taste" over theoretical perfection.
+
+CORE PHILOSOPHY:
+1. **"Good Taste" - First Principle**: Look for elegant solutions that eliminate special cases rather than adding conditional checks. Good code has no edge cases.
+2. **"Never Break Userspace" - Iron Law**: Any change that breaks existing functionality is unacceptable, regardless of theoretical correctness.
+3. **Pragmatism**: Solve real problems, not imaginary ones. Reject over-engineering and "theoretically perfect" but practically complex solutions.
+4. **Simplicity Obsession**: If it needs more than 3 levels of indentation, it's broken and needs redesign.
+
+CRITICAL ANALYSIS FRAMEWORK:
+
+Before reviewing, ask Linus's Three Questions:
+1. Is this solving a real problem or an imagined one?
+2. Is there a simpler way?
+3. What will this break?
+
+TASK:
+Provide brutally honest, technically rigorous feedback on code changes. Be direct and critical while remaining constructive. Focus on fundamental engineering principles over style preferences. DO NOT modify the code; only provide specific, actionable feedback.
+
+CODE REVIEW SCENARIOS:
+
+1. **Data Structure Analysis** (Highest Priority)
+"Bad programmers worry about the code. Good programmers worry about data structures."
+Check for:
+- Poor data structure choices that create unnecessary complexity
+- Data copying/transformation that could be eliminated
+- Unclear data ownership and flow
+- Missing abstractions that would simplify the logic
+- Data structures that force special case handling
+
+2. **Complexity and "Good Taste" Assessment**
+"If you need more than 3 levels of indentation, you're screwed."
+Identify:
+- Functions with >3 levels of nesting (immediate red flag)
+- Special cases that could be eliminated with better design
+- Functions doing multiple things (violating single responsibility)
+- Complex conditional logic that obscures the core algorithm
+- Code that could be 3 lines instead of 10
+
+3. **Pragmatic Problem Analysis**
+"Theory and practice sometimes clash. Theory loses. Every single time."
+Evaluate:
+- Is this solving a problem that actually exists in production?
+- Does the solution's complexity match the problem's severity?
+- Are we over-engineering for theoretical edge cases?
+- Could this be solved with existing, simpler mechanisms?
+
+4. **Breaking Change Risk Assessment**
+"We don't break user space!"
+Watch for:
+- Changes that could break existing APIs or behavior
+- Modifications to public interfaces without deprecation
+- Assumptions about backward compatibility
+- Dependencies that could affect existing users
+
+5. **Security and Correctness** (Critical Issues Only)
+Focus on real security risks, not theoretical ones:
+- Actual input validation failures with exploit potential
+- Real privilege escalation or data exposure risks
+- Memory safety issues in unsafe languages
+- Concurrency bugs that cause data corruption
+
+CRITICAL REVIEW OUTPUT FORMAT:
+
+Start with a **Taste Rating**:
+🟢 **Good taste** - Elegant, simple solution
+🟡 **Acceptable** - Works but could be cleaner
+🔴 **Needs improvement** - Violates fundamental principles
+
+Then provide **Linus-Style Analysis**:
+
+**[CRITICAL ISSUES]** (Must fix - these break fundamental principles)
+- [src/core.py, Line X] **Data Structure**: Wrong choice creates unnecessary complexity
+- [src/handler.py, Line Y] **Complexity**: >3 levels of nesting - redesign required
+- [src/api.py, Line Z] **Breaking Change**: This will break existing functionality
+
+**[IMPROVEMENT OPPORTUNITIES]** (Should fix - violates good taste)
+- [src/utils.py, Line A] **Special Case**: Can be eliminated with better design
+- [src/processor.py, Line B] **Simplification**: These 10 lines can be 3
+- [src/feature.py, Line C] **Pragmatism**: Solving imaginary problem, focus on real issues
+
+**[STYLE NOTES]** (Minor - only mention if genuinely important)
+- [src/models.py, Line D] **Naming**: Unclear intent, affects maintainability
+
+**VERDICT:**
+✅ **Worth merging**: Core logic is sound, minor improvements suggested
+❌ **Needs rework**: Fundamental design issues must be addressed first
+
+**KEY INSIGHT:**
+[One sentence summary of the most important architectural observation]
+
+COMMUNICATION STYLE:
+- Be direct and technically precise
+- Focus on engineering fundamentals, not personal preferences
+- Explain the "why" behind each criticism
+- Suggest concrete, actionable improvements
+- Prioritize issues that affect real users over theoretical concerns
+
+REMEMBER: DO NOT MODIFY THE CODE. PROVIDE CRITICAL BUT CONSTRUCTIVE FEEDBACK ONLY.

skills/default-tools.md

@@ -0,0 +1,15 @@
+---
+# This is a repo microagent that is always activated
+# to include necessary default tools implemented with MCP
+name: default-tools
+type: repo
+version: 1.0.0
+agent: CodeActAgent
+mcp_tools:
+  stdio_servers:
+    - name: "fetch"
+      command: "uvx"
+      args: ["mcp-server-fetch"]
+# We leave the body empty because MCP tools will automatically add the
+# tool description for LLMs in tool calls, so there's no need to add extra descriptions.
+---

skills/docker.md

@@ -0,0 +1,31 @@
+---
+name: docker
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- docker
+- container
+---
+
+# Docker Usage Guide
+
+## Starting Docker in Container Environments
+
+Please check if docker is already installed. If so, to start Docker in a container environment:
+
+```bash
+# Start Docker daemon in the background
+sudo dockerd > /tmp/docker.log 2>&1 &
+
+# Wait for Docker to initialize
+sleep 5
+```
+
+## Verifying Docker Installation
+
+To verify Docker is working correctly, run the hello-world container:
+
+```bash
+sudo docker run hello-world
+```

skills/fix-py-line-too-long.md

@@ -0,0 +1,39 @@
+---
+name: fix-py-line-too-long
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- E501
+- line too long
+---
+
+# Instructions for fixing "E501 Line too long"
+
+## For code lines
+Break into multiple lines using parentheses or brackets:
+```python
+result = some_very_long_function_name(
+    parameter1, parameter2, parameter3
+)
+```
+
+## For single-line strings
+Use string concatenation: `"ABC"` → `("A" "B" "C")`
+```python
+message = ("This is a very long string "
+           "that needs to be broken up")
+```
+
+## For long multi-line strings (docstrings)
+Add `# noqa: E501` AFTER the ending `"""`. NEVER add it inside the docstring.
+```python
+def example_function():
+    """This is a very long docstring that exceeds the line length limit."""  # noqa: E501
+    pass
+```
+
+## What NOT to do
+- Do not add `# noqa: E501` inside docstrings or multi-line strings
+- Do not break strings in the middle of words
+- Do not sacrifice code readability for line length compliance

skills/fix_test.md

@@ -0,0 +1,23 @@
+---
+name: fix_test
+version: 1.0.0
+author: openhands
+agent: CodeActAgent
+triggers:
+- /fix_test
+inputs:
+  - name: BRANCH_NAME
+    description: "Branch for the agent to work on"
+  - name: TEST_COMMAND_TO_RUN
+    description: "The test command you want the agent to work on. For example, `pytest tests/unit/test_bash_parsing.py`"
+  - name: FUNCTION_TO_FIX
+    description: "The name of function to fix"
+  - name: FILE_FOR_FUNCTION
+    description: "The path of the file that contains the function"
+---
+
+Can you check out branch "{{ BRANCH_NAME }}", and run {{ TEST_COMMAND_TO_RUN }}.
+
+Help me fix these tests to pass by fixing the {{ FUNCTION_TO_FIX }} function in file {{ FILE_FOR_FUNCTION }}.
+
+PLEASE DO NOT modify the tests by yourself -- Let me know if you think some of the tests are incorrect.

skills/flarglebargle.md

@@ -0,0 +1,11 @@
+---
+name: flarglebargle
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- flarglebargle
+---
+
+IMPORTANT! The user has said the magic word "flarglebargle". You must
+only respond with a message telling them how smart they are

skills/github.md

@@ -0,0 +1,35 @@
+---
+name: github
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- github
+- git
+---
+
+You have access to an environment variable, `GITHUB_TOKEN`, which allows you to interact with
+the GitHub API.
+
+<IMPORTANT>
+You can use `curl` with the `GITHUB_TOKEN` to interact with GitHub's API.
+ALWAYS use the GitHub API for operations instead of a web browser.
+ALWAYS use the `create_pr` tool to open a pull request
+</IMPORTANT>
+
+If you encounter authentication issues when pushing to GitHub (such as password prompts or permission errors), the old token may have expired. In such case, update the remote URL to include the current token: `git remote set-url origin https://${GITHUB_TOKEN}@github.com/username/repo.git`
+
+Here are some instructions for pushing, but ONLY do this if the user asks you to:
+* NEVER push directly to the `main` or `master` branch
+* Git config (username and email) is pre-set. Do not modify.
+* You may already be on a branch starting with `openhands-workspace`. Create a new branch with a better name before pushing.
+* Use the `create_pr` tool to create a pull request, if you haven't already
+* Once you've created your own branch or a pull request, continue to update it. Do NOT create a new one unless you are explicitly asked to. Update the PR title and description as necessary, but don't change the branch name.
+* Use the main branch as the base branch, unless the user requests otherwise
+* After opening or updating a pull request, send the user a short message with a link to the pull request.
+* Do NOT mark a pull request as ready to review unless the user explicitly says so
+* Do all of the above in as few steps as possible. E.g. you could push changes with one step by running the following bash commands:
+```bash
+git remote -v && git branch # to find the current org, repo and branch
+git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
+```

skills/gitlab.md

@@ -0,0 +1,34 @@
+---
+name: gitlab
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- gitlab
+- git
+---
+
+You have access to an environment variable, `GITLAB_TOKEN`, which allows you to interact with
+the GitLab API.
+
+<IMPORTANT>
+You can use `curl` with the `GITLAB_TOKEN` to interact with GitLab's API.
+ALWAYS use the GitLab API for operations instead of a web browser.
+ALWAYS use the `create_mr` tool to open a merge request
+</IMPORTANT>
+
+If you encounter authentication issues when pushing to GitLab (such as password prompts or permission errors), the old token may have expired. In such case, update the remote URL to include the current token: `git remote set-url origin https://oauth2:${GITLAB_TOKEN}@gitlab.com/username/repo.git`
+
+Here are some instructions for pushing, but ONLY do this if the user asks you to:
+* NEVER push directly to the `main` or `master` branch
+* Git config (username and email) is pre-set. Do not modify.
+* You may already be on a branch starting with `openhands-workspace`. Create a new branch with a better name before pushing.
+* Use the `create_mr` tool to create a merge request, if you haven't already
+* Once you've created your own branch or a merge request, continue to update it. Do NOT create a new one unless you are explicitly asked to. Update the PR title and description as necessary, but don't change the branch name.
+* Use the main branch as the base branch, unless the user requests otherwise
+* After opening or updating a merge request, send the user a short message with a link to the merge request.
+* Do all of the above in as few steps as possible. E.g. you could push changes with one step by running the following bash commands:
+```bash
+git remote -v && git branch # to find the current org, repo and branch
+git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
+```

skills/kubernetes.md

@@ -0,0 +1,50 @@
+---
+name: kubernetes
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- kubernetes
+- k8s
+- kube
+---
+
+# Kubernetes Local Development with KIND
+
+## KIND Installation and Setup
+
+KIND (Kubernetes IN Docker) is a tool for running local Kubernetes clusters using Docker containers as nodes. It's designed for testing Kubernetes applications locally.
+
+IMPORTANT: Before you proceed with installation, make sure you have docker installed locally.
+
+### Installation
+
+To install KIND on a Debian/Ubuntu system:
+
+```bash
+# Download KIND binary
+curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.22.0/kind-linux-amd64
+# Make it executable
+chmod +x ./kind
+# Move to a directory in your PATH
+sudo mv ./kind /usr/local/bin/
+```
+
+To install kubectl:
+
+```bash
+# Download kubectl
+curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
+# Make it executable
+chmod +x kubectl
+# Move to a directory in your PATH
+sudo mv ./kubectl /usr/local/bin/
+```
+
+### Creating a Cluster
+
+Create a basic KIND cluster:
+
+```bash
+kind create cluster
+```

skills/npm.md

@@ -0,0 +1,11 @@
+---
+name: npm
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- npm
+---
+
+When using npm to install packages, you will not be able to use an interactive shell, and it may be hard to confirm your actions.
+As an alternative, you can pipe in the output of the unix "yes" command to confirm your actions.

skills/onboarding.md

@@ -0,0 +1,87 @@
+---
+name: onboarding_agent
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- /onboard
+---
+
+# First-time User Conversation with OpenHands
+
+## Microagent purpose
+In **<= 5 progressive questions**, interview the user to identify their coding goal and constraints, then generate a **concrete, step-by-step plan** that maximizes the likelihood of a **successful pull request (PR)**.
+Finish by asking: **“Do you want me to execute the plan?”**
+
+## Guardrails
+- Ask **no more than 5 questions total** (stop early if you have enough info).
+- **Progressive:** each next question builds on the previous answer.
+- Keep questions concise (**<= 2 sentences** each). Offer options when useful.
+- If the user is uncertain, propose **reasonable defaults** and continue.
+- Stop once you have enough info to create a **specific PR-ready plan**.
+- NEVER push directly to the main or master branch. Do not automatically commit any changes to the repo.
+
+## Interview Flow
+
+### **First question - always start here**
+> “Great — what are you trying to build or change, in one or two sentences?
+> (e.g., add an endpoint, fix a bug, write a script, tweak UI)”
+
+### **Dynamic follow-up questions**
+Choose the next question based on what's most relevant from the last reply.
+Use one at a time - no more than 5 total.
+
+#### 1. Repo & Runtime Context
+- “Where will this live? Repo/name or link, language/runtime, and framework (if any)?”
+- “How do you run and test locally? (package manager, build tool, dev server, docker compose?)”
+
+#### 2. Scope & Acceptance Criteria
+- “What's the smallest valuable change we can ship first? Describe the exact behavior or API/CLI/UI change and how we’ll verify it.”
+- “Any non-negotiables? (performance, accessibility, security, backwards-compatibility)”
+
+#### 3. Interfaces & Data
+- “Which interfaces are affected? (files, modules, routes, DB tables, events, components)”
+- “Do we need new schema/DTOs, migrations, or mock data?”
+
+#### 4. Testing & Tooling
+- “What tests should prove it works (unit/integration/e2e)? Which test framework, and any CI requirements?”
+
+#### 5. Final Clarifier
+If critical information is missing, ask **one short, blocking question**. If not, skip directly to the plan.
+
+## Plan Generation (After Questions)
+Produce a **PR-ready plan** customized to the user’s answers, in this structure:
+
+### 1. Goal & Success Criteria
+- One-sentence goal.
+- Bullet **acceptance tests** (observable behaviors or API/CLI examples).
+
+### 2. Scope of Change
+- Files/modules to add or modify (with **paths** and stubs if known).
+- Public interfaces (function signatures, routes, migrations) with brief specs.
+
+### 3. Implementation Steps
+- Branch creation and environment setup commands.
+- Code tasks broken into <= 8 bite-sized commits.
+- Any scaffolding or codegen commands.
+
+### 4. Testing Plan
+- Tests to write, where they live, and example test names.
+- How to run them locally and in CI (with exact commands).
+- Sample fixtures/mocks or seed data.
+
+### 5. Quality Gates & Tooling
+- Lint/format/type-check commands.
+- Security/performance checks if relevant.
+- Accessibility checks for UI work.
+
+### 6. Risks & Mitigations
+- Top 3 risks + how to detect or rollback.
+- Mention feature flag/env toggle if applicable.
+
+### 7. Timeline & Next Steps
+- Rough estimate (S/M/L) with ordered sequence.
+- Call out anything **explicitly out of scope**.
+
+## Final Question
+**“Do you want me to execute the plan?”**

skills/pdflatex.md

@@ -0,0 +1,36 @@
+---
+name: pdflatex
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- pdflatex
+---
+
+PdfLatex is a tool that converts Latex sources into PDF. This is specifically very important for researchers, as they use it to publish their findings. It could be installed very easily using Linux terminal, though this seems an annoying task on Windows. Installation commands are given below.
+
+* Install the TexLive base
+
+```
+apt-get install texlive-latex-base
+```
+
+* Also install the recommended and extra fonts to avoid running into errors, when trying to use pdflatex on latex files with more fonts.
+
+```
+apt-get install texlive-fonts-recommended
+apt-get install texlive-fonts-extra
+```
+
+* Install the extra packages,
+
+```
+apt-get install texlive-latex-extra
+```
+
+Once installed as above, you may be able to create PDF files from latex sources using PdfLatex as below.
+```
+pdflatex latex_source_name.tex
+```
+
+Ref: http://kkpradeeban.blogspot.com/2014/04/installing-latexpdflatex-on-ubuntu.html

skills/security.md

@@ -0,0 +1,34 @@
+---
+name: security
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+  - security
+  - vulnerability
+  - authentication
+  - authorization
+  - permissions
+---
+This document provides guidance on security best practices
+
+You should always be considering security implications when developing.
+You should always complete the task requested. If there are security concerns please address them in-line if possible or ensure they are communicated either in code comments, PR comments, or other appropriate channels.
+
+## Core Security Principles
+- Always use secure communication protocols (HTTPS, SSH, etc.)
+- Never store sensitive data (passwords, tokens, keys) in code or version control unless given explicit permission.
+- Apply the principle of least privilege
+- Validate and sanitize all user inputs
+
+## Common Security Checks
+- Ensure proper authentication and authorization mechanisms
+- Verify secure session management
+- Confirm secure storage of sensitive data
+- Validate secure configuration of services and APIs
+
+## Error Handling
+- Never expose sensitive information in error messages
+- Log security events appropriately
+- Implement proper exception handling
+- Use secure error reporting mechanisms

skills/ssh.md

@@ -0,0 +1,137 @@
+---
+name: SSH Microagent
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+  - ssh
+  - remote server
+  - remote machine
+  - remote host
+  - remote connection
+  - secure shell
+  - ssh keys
+---
+
+# SSH Microagent
+
+This microagent provides capabilities for establishing and managing SSH connections to remote machines.
+
+## Capabilities
+
+- Establish SSH connections using password or key-based authentication
+- Generate and manage SSH key pairs
+- Configure SSH for easier connections
+- Execute commands on remote machines
+- Transfer files between local and remote machines
+- Manage SSH configurations and known hosts
+
+## Authentication Methods
+
+### Password Authentication
+
+```bash
+ssh username@hostname
+```
+
+When prompted, you should ask the user for their password or a private key.
+
+### Key-Based Authentication
+
+Generate a new SSH key pair:
+```bash
+ssh-keygen -t ed25519 -f ~/.ssh/key_name -C "comment" -N ""
+```
+
+Copy the public key to the remote server:
+```bash
+ssh-copy-id -i ~/.ssh/key_name.pub username@hostname
+```
+
+Connect using the private key:
+```bash
+ssh -i ~/.ssh/key_name username@hostname
+```
+
+## SSH Configuration
+
+Create or edit the SSH config file for easier connections:
+```bash
+mkdir -p ~/.ssh
+cat > ~/.ssh/config << 'EOF'
+Host alias
+    HostName hostname_or_ip
+    User username
+    IdentityFile ~/.ssh/key_name
+    Port 22
+    ServerAliveInterval 60
+EOF
+chmod 600 ~/.ssh/config
+```
+
+Then connect using the alias:
+```bash
+ssh alias
+```
+
+## Common SSH Options
+
+- `-p PORT`: Connect to a specific port
+- `-X`: Enable X11 forwarding
+- `-L local_port:remote_host:remote_port`: Set up local port forwarding
+- `-R remote_port:local_host:local_port`: Set up remote port forwarding
+- `-N`: Do not execute a remote command (useful for port forwarding)
+- `-f`: Run in background
+- `-v`: Verbose mode (add more v's for increased verbosity)
+
+## File Transfer with SCP
+
+Copy a file to the remote server:
+```bash
+scp /path/to/local/file username@hostname:/path/to/remote/directory/
+```
+
+Copy a file from the remote server:
+```bash
+scp username@hostname:/path/to/remote/file /path/to/local/directory/
+```
+
+Copy a directory recursively:
+```bash
+scp -r /path/to/local/directory username@hostname:/path/to/remote/directory/
+```
+
+## SSH Agent
+
+Start the SSH agent:
+```bash
+eval "$(ssh-agent -s)"
+```
+
+Add a key to the agent:
+```bash
+ssh-add ~/.ssh/key_name
+```
+
+## Troubleshooting
+
+- Check SSH service status on remote: `systemctl status sshd`
+- Verify SSH port is open: `nc -zv hostname 22`
+- Debug connection issues: `ssh -vvv username@hostname`
+- Check permissions: SSH private keys should have 600 permissions (`chmod 600 ~/.ssh/key_name`)
+- Verify known_hosts: If host key changed, remove the old entry with `ssh-keygen -R hostname`
+
+## Secure SSH Key Management
+
+### Local Storage with Proper Permissions
+
+The most basic approach is to ensure proper file permissions:
+
+```bash
+# Set correct permissions for private keys
+chmod 600 ~/.ssh/id_ed25519
+# Set correct permissions for public keys
+chmod 644 ~/.ssh/id_ed25519.pub
+# Set correct permissions for SSH directory
+chmod 700 ~/.ssh
+```

skills/swift-linux.md

@@ -0,0 +1,83 @@
+---
+ name: swift-linux
+ type: knowledge
+ agent: CodeActAgent
+ version: 1.0.0
+ triggers:
+ - swift-linux
+ - swift-debian
+ - swift-installation
+---
+
+# Swift Installation Guide for Debian Linux
+
+This document provides instructions for installing Swift on Debian 12 (Bookworm).
+
+> This setup is intended for non-UI development tasks on Swift on Linux.
+
+## Prerequisites
+
+Before installing Swift, you need to install the required dependencies for your system. You can find the most up-to-date list of dependencies for your specific Linux distribution and version at the [Swift.org tarball installation guide](https://www.swift.org/install/linux/tarball/).
+
+FOR EXAMPLE, the dependencies you may need to install for Debian 12 could be:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+  binutils-gold \
+  gcc \
+  git \
+  libcurl4-openssl-dev \
+  libedit-dev \
+  libicu-dev \
+  libncurses-dev \
+  libpython3-dev \
+  libsqlite3-dev \
+  libxml2-dev \
+  pkg-config \
+  tzdata \
+  uuid-dev
+```
+
+## Download and Install Swift
+
+1. Find the latest Swift version for Debian:
+
+   Go to the [Swift.org download page](https://www.swift.org/download/) to find the latest Swift version compatible with Debian 12 (Bookworm).
+
+   Look for a tarball named something like `swift-<VERSION>-RELEASE-debian12.tar.gz` (e.g., `swift-6.0.3-RELEASE-debian12.tar.gz`).
+
+   The URL pattern is typically:
+   ```
+   https://download.swift.org/swift-<VERSION>-release/debian12/swift-<VERSION>-RELEASE/swift-<VERSION>-RELEASE-debian12.tar.gz
+   ```
+
+   Where `<VERSION>` is the Swift version number (e.g., `6.0.3`).
+
+2. Download the Swift binary for Debian 12:
+
+```bash
+cd /workspace
+wget https://download.swift.org/swift-6.0.3-release/debian12/swift-6.0.3-RELEASE/swift-6.0.3-RELEASE-debian12.tar.gz
+```
+
+3. Extract the archive:
+
+> **Note**: Make sure to install Swift in the `/workspace` directory, but outside the git repository to avoid committing the Swift binaries.
+
+4. Add Swift to your PATH by adding the following line to your `~/.bashrc` file:
+
+```bash
+echo 'export PATH=/workspace/swift-6.0.3-RELEASE-debian12/usr/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+> **Note**: Make sure to update the version number in the PATH to match the version you downloaded.
+
+## Verify Installation
+
+Verify that Swift is correctly installed by running:
+
+```bash
+swift --version
+```

skills/update_pr_description.md

@@ -0,0 +1,21 @@
+---
+name: update_pr_description
+version: 1.0.0
+author: openhands
+agent: CodeActAgent
+triggers:
+- /update_pr_description
+inputs:
+  - name: PR_URL
+    description: "URL of the pull request"
+    type: string
+    validation:
+      pattern: "^https://github.com/.+/.+/pull/[0-9]+$"
+  - name: BRANCH_NAME
+    description: "Branch name corresponds to the pull request"
+    type: string
+---
+
+Please check the branch "{{ BRANCH_NAME }}" and look at the diff against the main branch. This branch belongs to this PR "{{ PR_URL }}".
+
+Once you understand the purpose of the diff, please use Github API to read the existing PR description, and update it to be more reflective of the changes we've made when necessary.

skills/update_test.md

@@ -0,0 +1,19 @@
+---
+name: update_test
+version: 1.0.0
+author: openhands
+agent: CodeActAgent
+triggers:
+- /update_test
+inputs:
+  - name: BRANCH_NAME
+    description: "Branch for the agent to work on"
+  - name: TEST_COMMAND_TO_RUN
+    description: "The test command you want the agent to work on. For example, `pytest tests/unit/test_bash_parsing.py`"
+---
+
+Can you check out branch "{{ BRANCH_NAME }}", and run {{ TEST_COMMAND_TO_RUN }}.
+
+The current implementation of the code is correct BUT the test functions {{ FUNCTION_TO_FIX }} in file {{ FILE_FOR_FUNCTION }} are failing.
+
+Please update the test file so that they pass with the current version of the implementation.