docs: Add documentation of skills to the CLI section

openhands/usage/run-openhands/cli-settings.mdx

@@ -51,9 +51,27 @@ The `/mcp` command in the CLI provides a read-only view of MCP server status:
 - **View pending changes**: If the `mcp.json` file has been modified, shows which servers will be mounted when the
   conversation is restarted.
 
+## Skills Configuration
+
+Skills are specialized prompts that provide domain-specific knowledge to OpenHands. They are markdown files (`.md`) that can be always-active or keyword-triggered, and they inject additional context and rules into the agent's behavior.
+
+### Skills-related Environment Variables
+
+- `AGENT_ENABLE_PROMPT_EXTENSIONS` - Enable/disable skills (default: `true`)
+- `AGENT_DISABLED_MICROAGENTS` - List of specific skills to disable
+
+### Learn More
+
+For comprehensive documentation on creating and using skills:
+- **[Skills Overview](/overview/skills)** - Complete guide to how skills work
+- **[Keyword-Triggered Skills](/overview/skills/keyword)** - Creating trigger-based skills
+- **[Repository Skills](/overview/skills/repo)** - Repository-specific guidelines
+- **[Official Skills Registry](https://github.com/OpenHands/skills)** - Community-shared skills and examples
+
 ## Tips and Troubleshooting
 
 - Use `/help` at any time to see the list of available commands.
 - If you encounter permission issues, make sure your workspace directory is trusted and all required environment
   variables are set correctly.
-- If you want to start over, use `/new` to begin a fresh conversation without restarting the CLI.
+- If you want to start over, use `/new` to begin a fresh conversation without restarting the CLI.
+- If skills aren't working, see the [Keyword Skills Troubleshooting Guide](/overview/skills/keyword#troubleshooting)

overview/skills.mdx

@@ -51,7 +51,7 @@ Each skill file may include frontmatter that provides additional information. In
 
 | Platform | Support Level | Configuration Method | Implementation | Documentation |
 |----------|---------------|---------------------|----------------|---------------|
-| **CLI** | ✅ Full Support | `.openhands/skills/` directory | File-based markdown | This guide |
+| **CLI** | ✅ Full Support | `~/.openhands/skills/` (user-level) and `.openhands/skills/` (repo-level) | File-based markdown | [CLI Settings](/openhands/usage/run-openhands/cli-settings#skills-configuration) |
 | **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) |
 | **OpenHands Cloud** | ✅ Full Support | Cloud UI + repository integration | Managed skill library | [Cloud UI](/openhands/usage/cloud/cloud-ui) |
@@ -60,10 +60,13 @@ Each skill file may include frontmatter that provides additional information. In
 
 <Tabs>
   <Tab title="CLI">
-    - File-based configuration in `.openhands/skills/` directory
+    - File-based configuration in two locations:
+      - `~/.openhands/skills/` - User-level skills (all conversations)
+      - `.openhands/skills/` - Repository-level skills (current directory)
     - Markdown format for skill definitions
     - Manual file management required
     - Supports both general and keyword-triggered skills
+    - See [CLI Skills Configuration](/openhands/usage/run-openhands/cli-settings#skills-configuration) for details
   </Tab>
   <Tab title="SDK">
     - Programmatic `Skill` objects in code

overview/skills/keyword.mdx

@@ -33,3 +33,45 @@ The user has said the magic word. Respond with "That was delicious!"
 ```
 
 [See examples of keyword-triggered skills in the official OpenHands Skills Registry](https://github.com/OpenHands/skills)
+
+## Troubleshooting
+
+If your keyword-triggered skill isn't activating:
+
+### 1. Check File Location
+- **CLI**: Place skills in `~/.openhands/skills/` (user-level) or `.openhands/skills/` (repository-level)
+- **GUI**: Place skills in `.openhands/skills/` in your repository root
+- Ensure the file has a `.md` extension (e.g., `my-skill.md`, not `my-skill.txt`)
+- Common mistake: Using folder name `microagents` instead of `skills`
+
+### 2. Verify Frontmatter Format
+The frontmatter must be properly formatted with triple dashes (`---`), a `triggers:` field, and each trigger on its own line with a dash and space (`- `).
+
+**Correct:**
+```yaml
+---
+triggers:
+- /myskill
+- myskill
+---
+```
+
+**Common mistakes:**
+- Using list format instead of separate lines: `triggers: [/myskill, myskill]`
+- Missing triple dashes at top or bottom
+- Missing space after dash: `-/myskill`
+- Missing colon after `triggers`
+
+### 3. Check Skills Are Enabled and Test Triggers
+- Verify `AGENT_ENABLE_PROMPT_EXTENSIONS=true` (default)
+- Trigger keywords are **case-sensitive** - include both variations if needed: `- myskill` and `- MySkill`
+- Slash prefixes (like `/myskill`) are treated as literal strings, not commands
+- Test with a simple skill to verify the system is working:
+  ```markdown
+  ---
+  triggers:
+  - testskill
+  ---
+
+  TEST SKILL IS ACTIVE! This is a test skill.
+  ```