From a8a095793fe1ca84a14355de13b13ad0d43bf1b9 Mon Sep 17 00:00:00 2001 From: enyst Date: Sun, 8 Feb 2026 09:53:23 +0000 Subject: [PATCH 1/5] docs: update skills path precedence Co-authored-by: openhands --- overview/skills.mdx | 22 +++++++++++++++++----- overview/skills/keyword.mdx | 2 +- sdk/arch/skill.mdx | 2 +- 3 files changed, 19 insertions(+), 7 deletions(-) diff --git a/overview/skills.mdx b/overview/skills.mdx index a91b891e..9047e4d4 100644 --- a/overview/skills.mdx +++ b/overview/skills.mdx @@ -37,7 +37,7 @@ We also support model-specific variants: To add optional skills that are loaded on demand: - **AgentSkills standard (recommended for progressive disclosure)**: create one directory per skill and add a `SKILL.md` file. -- **Legacy/OpenHands format (simple)**: put markdown files in `.openhands/skills/*.md`. +- **Legacy/OpenHands format (simple)**: put markdown files in `.agents/skills/*.md` at the repository root (or `.openhands/skills/*.md` for backward compatibility). Loaded skills take up space in the context window. On-demand skills help keep the system prompt smaller because the agent sees a summary first and reads the full content only when needed. @@ -48,7 +48,7 @@ Loaded skills take up space in the context window. On-demand skills help keep th ``` some-repository/ ├── AGENTS.md # Permanent repository guidelines (recommended) -└── .openhands/ +└── .agents/ └── skills/ ├── rot13-encryption/ # AgentSkills standard (progressive disclosure) │ ├── SKILL.md @@ -63,6 +63,18 @@ some-repository/ └── legacy_trigger_this.md # Legacy/OpenHands format (keyword-triggered) ``` +## Skill Loading Precedence (Project Directory) + +All paths are relative to the repository root; `.agents/skills/` is a subdirectory of the project directory. + +When multiple skills share the same name, OpenHands keeps the first match in this order: + +1. Root-level permanent context files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, etc.) +2. `.agents/skills/` (recommended) +3. `.openhands/skills/` (legacy) +4. `.openhands/microagents/` (deprecated) + + ## Skill Types Currently supported skill types: @@ -85,9 +97,9 @@ Each skill file may include frontmatter that provides additional information. In | Platform | Support Level | Configuration Method | Implementation | Documentation | |----------|---------------|---------------------|----------------|---------------| -| **CLI** | ✅ Full Support | `~/.openhands/skills/` (user-level) and `.openhands/skills/` (repo-level) | File-based markdown | [Skills Overview](/overview/skills) | +| **CLI** | ✅ Full Support | `~/.openhands/skills/` (user-level) and `.agents/skills/` (repo-level, `.openhands/skills/` legacy) | File-based markdown | [Skills Overview](/overview/skills) | | **SDK** | ✅ Full Support | Programmatic `Skill` objects | Code-based configuration | [SDK Skills Guide](/sdk/guides/skill) | -| **Local GUI** | ✅ Full Support | `.openhands/skills/` + UI | File-based with UI management | [Local Setup](/openhands/usage/run-openhands/local-setup) | +| **Local GUI** | ✅ Full Support | `.agents/skills/` + UI (`.openhands/skills/` legacy) | File-based with UI management | [Local Setup](/openhands/usage/run-openhands/local-setup) | | **OpenHands Cloud** | ✅ Full Support | Cloud UI + repository integration | Managed skill library | [Cloud UI](/openhands/usage/cloud/cloud-ui) | ## Platform-Specific Differences @@ -96,7 +108,7 @@ Each skill file may include frontmatter that provides additional information. In - File-based configuration in two locations: - `~/.openhands/skills/` - User-level skills (all conversations) - - `.openhands/skills/` - Repository-level skills (current directory) + - `.agents/skills/` - Repository-level skills (current directory, `.openhands/skills/` legacy) - Markdown format for skill definitions - Manual file management required - Supports both general and keyword-triggered skills diff --git a/overview/skills/keyword.mdx b/overview/skills/keyword.mdx index 50ccc6ab..e187a034 100644 --- a/overview/skills/keyword.mdx +++ b/overview/skills/keyword.mdx @@ -21,7 +21,7 @@ Enclose the frontmatter in triple dashes (---) and include the following fields: ## Example -Keyword-triggered skill file example located at `.openhands/skills/yummy.md`: +Keyword-triggered skill file example located at `.agents/skills/yummy.md` (or `.openhands/skills/yummy.md` for legacy setups): ``` --- triggers: diff --git a/sdk/arch/skill.mdx b/sdk/arch/skill.mdx index 311a2bbf..38843ced 100644 --- a/sdk/arch/skill.mdx +++ b/sdk/arch/skill.mdx @@ -106,7 +106,7 @@ flowchart LR - **Trigger:** `None` (always active) - **Purpose:** Project conventions, coding standards, architecture rules - **MCP Tools:** Can include MCP tool configuration -- **Location:** `AGENTS.md` (recommended) and/or `.openhands/skills/*.md` (supported) +- **Location:** `AGENTS.md` (recommended) and/or `.agents/skills/*.md` (supported; `.openhands/skills/*.md` legacy) **Example Files (permanent context):** - `AGENTS.md` - General agent instructions From 1e15b41722b38ea6fa93bbea6caf42554d234bd0 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Sun, 8 Feb 2026 10:56:22 +0100 Subject: [PATCH 2/5] Apply suggestion from @enyst --- overview/skills.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/overview/skills.mdx b/overview/skills.mdx index 9047e4d4..ad140399 100644 --- a/overview/skills.mdx +++ b/overview/skills.mdx @@ -37,7 +37,7 @@ We also support model-specific variants: To add optional skills that are loaded on demand: - **AgentSkills standard (recommended for progressive disclosure)**: create one directory per skill and add a `SKILL.md` file. -- **Legacy/OpenHands format (simple)**: put markdown files in `.agents/skills/*.md` at the repository root (or `.openhands/skills/*.md` for backward compatibility). +- **Legacy/OpenHands format (simple)**: put markdown files in `.agents/skills/*.md` at the repository root. Loaded skills take up space in the context window. On-demand skills help keep the system prompt smaller because the agent sees a summary first and reads the full content only when needed. From 2f58e51e9b0ec2d81a61773ed82834d79352c169 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Sun, 8 Feb 2026 10:58:18 +0100 Subject: [PATCH 3/5] Apply suggestion from @enyst --- overview/skills.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/overview/skills.mdx b/overview/skills.mdx index ad140399..8f65dccd 100644 --- a/overview/skills.mdx +++ b/overview/skills.mdx @@ -108,7 +108,7 @@ Each skill file may include frontmatter that provides additional information. In - File-based configuration in two locations: - `~/.openhands/skills/` - User-level skills (all conversations) - - `.agents/skills/` - Repository-level skills (current directory, `.openhands/skills/` legacy) + - `.agents/skills/` - Repository-level skills (current directory) - Markdown format for skill definitions - Manual file management required - Supports both general and keyword-triggered skills From 4b11de5bf061785bab862f30d7013a2f13b4e9c2 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Sun, 8 Feb 2026 10:59:15 +0100 Subject: [PATCH 4/5] Apply suggestion from @enyst --- sdk/arch/skill.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/arch/skill.mdx b/sdk/arch/skill.mdx index 38843ced..d26deb73 100644 --- a/sdk/arch/skill.mdx +++ b/sdk/arch/skill.mdx @@ -106,7 +106,7 @@ flowchart LR - **Trigger:** `None` (always active) - **Purpose:** Project conventions, coding standards, architecture rules - **MCP Tools:** Can include MCP tool configuration -- **Location:** `AGENTS.md` (recommended) and/or `.agents/skills/*.md` (supported; `.openhands/skills/*.md` legacy) +- **Location:** `AGENTS.md` (recommended) and/or `.agents/skills/*.md` (supported) **Example Files (permanent context):** - `AGENTS.md` - General agent instructions From 3ca9ccce9d3ec18ceaf57b5952c37faae652d6df Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 8 Feb 2026 10:46:24 +0000 Subject: [PATCH 5/5] docs: adjust skills precedence list Co-authored-by: openhands --- overview/skills.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/overview/skills.mdx b/overview/skills.mdx index 8f65dccd..50a20ab9 100644 --- a/overview/skills.mdx +++ b/overview/skills.mdx @@ -69,10 +69,9 @@ All paths are relative to the repository root; `.agents/skills/` is a subdirecto When multiple skills share the same name, OpenHands keeps the first match in this order: -1. Root-level permanent context files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, etc.) -2. `.agents/skills/` (recommended) -3. `.openhands/skills/` (legacy) -4. `.openhands/microagents/` (deprecated) +1. `.agents/skills/` (recommended) +2. `.openhands/skills/` (legacy) +3. `.openhands/microagents/` (deprecated) ## Skill Types