docs: update skills path precedence

overview/skills.mdx

@@ -37,7 +37,7 @@
 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 @@
 ```
 some-repository/
 ├── AGENTS.md                       # Permanent repository guidelines (recommended)
-└── .openhands/
+└── .agents/
     └── skills/
         ├── rot13-encryption/       # AgentSkills standard (progressive disclosure)
         │   ├── SKILL.md
@@ -63,6 +63,17 @@
         └── 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:
@@ -72,9 +83,9 @@
 - **[Organization Skills](/overview/skills/org)**: Team or organization-wide standards.
 - **[Global Skills](/overview/skills/public)**: Community-shared skills and templates.
 
 ### Skills Frontmatter Requirements
 
 Each skill file may include frontmatter that provides additional information. In some cases, this frontmatter is required:
 
 | Skill Type  | Required |
 |-------------|----------|
@@ -85,9 +96,9 @@
 
 | 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 @@
   <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

overview/skills/keyword.mdx

@@ -7,12 +7,12 @@
 
 These skills are only loaded when a prompt includes one of the trigger words.
 
 ## Frontmatter Syntax
 
 Frontmatter is required for keyword-triggered skills. It must be placed at the top of the file,
 above the guidelines.
 
 Enclose the frontmatter in triple dashes (---) and include the following fields:
 
 | Field      | Description                                      | Required | Default          |
 |------------|--------------------------------------------------|----------|------------------|
@@ -21,7 +21,7 @@
 
 ## 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:

sdk/arch/skill.mdx

@@ -72,11 +72,11 @@
 
 | Component | Purpose | Design |
 |-----------|---------|--------|
 | **[`Skill`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/skill.py)** | Core skill model | Pydantic model with name, content, trigger |
 | **[`KeywordTrigger`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/trigger.py)** | Keyword-based activation | String matching on user messages |
 | **[`TaskTrigger`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/trigger.py)** | Task-based activation | Special type of KeywordTrigger for skills with user inputs |
 | **[`InputMetadata`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/types.py)** | Task input parameters | Defines user inputs for task skills |
 | **Skill Loader** | File parsing | Reads markdown with frontmatter, validates schema |
 
 ## Skill Types
 
@@ -106,7 +106,7 @@
 - **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
@@ -291,7 +291,7 @@
 ```
 
 **Workflow:**
 1. **Load Skill:** Parse markdown file with frontmatter
 2. **Extract MCP Config:** Read `mcp_tools` field
 3. **Spawn MCP Servers:** Create MCP clients for each server
 4. **Register Tools:** Add MCP tools to agent's tool registry
@@ -299,7 +299,7 @@
 
 ## Skill File Format
 
 Skills are defined in markdown files with YAML frontmatter:
 
 ```markdown
 ---
@@ -314,13 +314,13 @@
 This is the instruction text that will be added to the agent's context.
 ```
 
 **Frontmatter Fields:**
 
 | Field | Required | Description |
 |-------|----------|-------------|
 | **name** | Yes | Unique skill identifier |
 | **trigger** | Yes* | Activation trigger (`null` for always active) |
 | **mcp_tools** | No | MCP server configuration (repo skills only) |
 | **inputs** | No | User input metadata (task skills only) |
 
 *Repository skills use `trigger: null` (or omit trigger field)