diff --git a/overview/skills.mdx b/overview/skills.mdx
index a91b891e..50a20ab9 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.
 
 <Note>
 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,17 @@ 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. `.agents/skills/` (recommended)
+2. `.openhands/skills/` (legacy)
+3. `.openhands/microagents/` (deprecated)
+
+
 ## Skill Types
 
 Currently supported skill types:
@@ -85,9 +96,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 +107,7 @@ Each skill file may include frontmatter that provides additional information. In
   <Tab title="CLI">
     - 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)
     - 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..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 `.openhands/skills/*.md` (supported)
+- **Location:** `AGENTS.md` (recommended) and/or `.agents/skills/*.md` (supported)
 
 **Example Files (permanent context):**
 - `AGENTS.md` - General agent instructions