From 84e522b1b14e1db999196e4348beff4386bf1b1e Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 7 Dec 2025 16:59:08 +0000 Subject: [PATCH 1/5] docs: Clarify CLI skills documentation and add troubleshooting guide This commit addresses user confusion about where to place skills when using the OpenHands CLI and how to verify they are working correctly. Changes made: - Added comprehensive 'Using Skills with CLI' section to cli-mode.mdx explaining: - Both skill locations: ~/.openhands/skills/ (user-level) and .openhands/skills/ (repo-level) - How to create general and keyword-triggered skills - How to verify skills are working - Note about microagents vs skills naming - Updated skills overview matrix to clarify CLI supports both locations - Enhanced CLI platform-specific differences to show both skill locations - Added extensive troubleshooting section to keyword.mdx covering: - Common file location issues - Frontmatter formatting problems - How to verify skills are enabled - Trigger keyword best practices - Common mistakes (microagents folder, YAML formatting, etc.) - Step-by-step testing procedure - Updated cli-settings.mdx to add Skills Configuration section with: - Default skill locations - Environment variables for controlling skills - Link to troubleshooting guide These changes help users understand that: 1. Skills work in CLI mode with file-based configuration 2. Skills can be placed in two locations (user-level and repo-level) 3. The folder should be named 'skills' not 'microagents' 4. Skills are enabled by default 5. How to troubleshoot when skills don't trigger as expected Fixes documentation gap reported by users who couldn't get skills working in CLI mode. --- openhands/usage/run-openhands/cli-mode.mdx | 63 ++++++++++++++ .../usage/run-openhands/cli-settings.mdx | 16 +++- overview/skills.mdx | 7 +- overview/skills/keyword.mdx | 82 +++++++++++++++++++ 4 files changed, 165 insertions(+), 3 deletions(-) diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx index f481e7ba..240327c0 100644 --- a/openhands/usage/run-openhands/cli-mode.mdx +++ b/openhands/usage/run-openhands/cli-mode.mdx @@ -126,3 +126,66 @@ Key features include: - MCP server management with `/mcp` - Conversation management with `/new` and `/help` - Real-time status monitoring and control + +## Using Skills with CLI + +Skills are specialized prompts that enhance OpenHands with domain-specific knowledge and automated task handling. The CLI fully supports skills through file-based configuration. + +### Skill Locations + +The CLI loads skills from two locations: + +1. **User-Level Skills** (`~/.openhands/skills/`): + - Loaded for all conversations regardless of working directory + - Useful for personal preferences and frequently used guidelines + - Example: `~/.openhands/skills/my-coding-style.md` + +2. **Repository-Level Skills** (`.openhands/skills/` in current directory): + - Loaded only when working within a repository + - Project-specific guidelines and practices + - Example: `.openhands/skills/repo.md` or `.openhands/skills/testing.md` + +Both locations can contain the same types of skills (general skills and keyword-triggered skills). + +### Creating Skills + +Skills are markdown files with optional YAML frontmatter: + +**General Skills** (always active): +```markdown +# Development Guidelines +Always write tests for new features. +Use type hints in Python code. +``` + +**Keyword-Triggered Skills** (activated by specific words): +```markdown +--- +triggers: +- /testing +- test this +--- + +When the user asks for testing, ensure you: +1. Write comprehensive unit tests +2. Include edge cases +3. Run the test suite to verify +``` + +### Verifying Skills Are Working + +Skills are enabled by default. If skills don't seem to be working: + +1. Verify the file is in the correct location (`~/.openhands/skills/` or `.openhands/skills/`) +2. Check the file has a `.md` extension +3. For keyword-triggered skills, ensure the frontmatter is properly formatted with `triggers:` +4. Skills are enabled by default, but you can verify with the `AGENT_ENABLE_PROMPT_EXTENSIONS` environment variable + + +Skills were formerly called "microagents". Always use the folder name `skills` (not `microagents`). Some environment variables still reference "microagents" for backwards compatibility. + + +For more details on skills, see: +- **[Skills Overview](/overview/skills)** - Complete guide to skills +- **[Keyword-Triggered Skills](/overview/skills/keyword)** - Detailed syntax and examples +- **[Repository Skills](/overview/skills/repo)** - Creating repository-specific guidelines diff --git a/openhands/usage/run-openhands/cli-settings.mdx b/openhands/usage/run-openhands/cli-settings.mdx index b06e9ab5..a46f1eb4 100644 --- a/openhands/usage/run-openhands/cli-settings.mdx +++ b/openhands/usage/run-openhands/cli-settings.mdx @@ -51,9 +51,23 @@ 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 enabled by default in the CLI and load automatically from: + +- `~/.openhands/skills/` - User-level skills for all conversations +- `.openhands/skills/` - Repository-level skills for the current directory + +For detailed information about creating and using skills, see [Using Skills with CLI](/openhands/usage/run-openhands/cli-mode#using-skills-with-cli). + +**Skills-related Environment Variables:** +- `AGENT_ENABLE_PROMPT_EXTENSIONS` - Enable/disable skills (default: `true`) +- `AGENT_DISABLED_MICROAGENTS` - List of specific skills to disable + ## 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. \ No newline at end of file +- 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) \ No newline at end of file diff --git a/overview/skills.mdx b/overview/skills.mdx index 8fe46843..7617c940 100644 --- a/overview/skills.mdx +++ b/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 Mode](/openhands/usage/run-openhands/cli-mode#using-skills-with-cli) | | **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 - - 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 Documentation](/openhands/usage/run-openhands/cli-mode#using-skills-with-cli) for details - Programmatic `Skill` objects in code diff --git a/overview/skills/keyword.mdx b/overview/skills/keyword.mdx index 50ccc6ab..5852dff5 100644 --- a/overview/skills/keyword.mdx +++ b/overview/skills/keyword.mdx @@ -33,3 +33,85 @@ 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`) + +### 2. Verify Frontmatter Format +The frontmatter must be properly formatted: +- Enclosed in triple dashes (`---`) at the top and bottom +- `triggers:` field must be present and properly indented +- Each trigger must be on its own line starting with a dash and space (`- `) + +**Correct:** +```yaml +--- +triggers: +- /myskill +- myskill +--- +``` + +**Incorrect (will not work):** +```yaml +--- +triggers: [/myskill, myskill] # Wrong: not a list format +--- + +# Missing opening dashes +triggers: +- /myskill +--- + +--- +triggers: +-/myskill # Wrong: missing space after dash +--- +``` + +### 3. Check Skills Are Enabled +Skills are enabled by default, but verify with: +- **Environment Variable**: Ensure `AGENT_ENABLE_PROMPT_EXTENSIONS=true` (default) +- **CLI**: Skills load automatically when the CLI starts + +### 4. Test Your Trigger Keywords +- Trigger keywords are case-sensitive by default +- Try including both variations if needed: `- myskill` and `- MySkill` +- Use specific, unique keywords to avoid conflicts +- Slash prefixes (like `/myskill`) are treated as literal strings, not commands + +### 5. Verify File Contents +- Ensure there's content below the frontmatter (the actual skill instructions) +- Use markdown formatting for the skill content +- Test with a simple skill first to verify the system is working + +### 6. Common Mistakes +- Using folder name `microagents` instead of `skills` (skills is the current name) +- Missing the triple dashes around frontmatter +- Incorrect YAML indentation +- Missing the colon after `triggers` +- Using quotes around trigger words (not required: use `- myword` not `- "myword"`) + +### 7. Testing +To test if your skill is working: +1. Start a new conversation (use `/new` in CLI) +2. Type a message containing your trigger keyword +3. The skill should activate and provide the guidance in your skill file + +If you're still having issues, try creating a minimal test skill: +```markdown +--- +triggers: +- testskill +--- + +TEST SKILL IS ACTIVE! This is a test skill. +``` + +If this minimal skill doesn't work, check your OpenHands configuration and ensure skills are supported in your version. From dba9f1ba32c5e3e5636fb4a415b200ff22e28405 Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 7 Dec 2025 17:30:53 +0000 Subject: [PATCH 2/5] docs: Simplify CLI skills section and link to comprehensive docs - Replace verbose skills documentation with concise summary - Add links to existing comprehensive skills documentation - Remove redundant examples already covered in skills overview - Maintains essential information about user and repo skill locations This addresses feedback to make CLI docs more concise and avoid duplication of content that already exists in /overview/skills. Co-authored-by: openhands --- openhands/usage/run-openhands/cli-mode.mdx | 66 ++-------------------- 1 file changed, 6 insertions(+), 60 deletions(-) diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx index 240327c0..b08cc5e4 100644 --- a/openhands/usage/run-openhands/cli-mode.mdx +++ b/openhands/usage/run-openhands/cli-mode.mdx @@ -127,65 +127,11 @@ Key features include: - Conversation management with `/new` and `/help` - Real-time status monitoring and control -## Using Skills with CLI +## Skills Support -Skills are specialized prompts that enhance OpenHands with domain-specific knowledge and automated task handling. The CLI fully supports skills through file-based configuration. +The CLI loads skills from `~/.openhands/skills/` (user-level) and `.openhands/skills/` (repository-level). Skills are markdown files that can be always-active or keyword-triggered. -### Skill Locations - -The CLI loads skills from two locations: - -1. **User-Level Skills** (`~/.openhands/skills/`): - - Loaded for all conversations regardless of working directory - - Useful for personal preferences and frequently used guidelines - - Example: `~/.openhands/skills/my-coding-style.md` - -2. **Repository-Level Skills** (`.openhands/skills/` in current directory): - - Loaded only when working within a repository - - Project-specific guidelines and practices - - Example: `.openhands/skills/repo.md` or `.openhands/skills/testing.md` - -Both locations can contain the same types of skills (general skills and keyword-triggered skills). - -### Creating Skills - -Skills are markdown files with optional YAML frontmatter: - -**General Skills** (always active): -```markdown -# Development Guidelines -Always write tests for new features. -Use type hints in Python code. -``` - -**Keyword-Triggered Skills** (activated by specific words): -```markdown ---- -triggers: -- /testing -- test this ---- - -When the user asks for testing, ensure you: -1. Write comprehensive unit tests -2. Include edge cases -3. Run the test suite to verify -``` - -### Verifying Skills Are Working - -Skills are enabled by default. If skills don't seem to be working: - -1. Verify the file is in the correct location (`~/.openhands/skills/` or `.openhands/skills/`) -2. Check the file has a `.md` extension -3. For keyword-triggered skills, ensure the frontmatter is properly formatted with `triggers:` -4. Skills are enabled by default, but you can verify with the `AGENT_ENABLE_PROMPT_EXTENSIONS` environment variable - - -Skills were formerly called "microagents". Always use the folder name `skills` (not `microagents`). Some environment variables still reference "microagents" for backwards compatibility. - - -For more details on skills, see: -- **[Skills Overview](/overview/skills)** - Complete guide to skills -- **[Keyword-Triggered Skills](/overview/skills/keyword)** - Detailed syntax and examples -- **[Repository Skills](/overview/skills/repo)** - Creating repository-specific guidelines +**For complete documentation on skills:** +- **[Skills Overview](/overview/skills)** - What skills are and how they work +- **[Keyword-Triggered Skills](/overview/skills/keyword)** - Creating trigger-based skills +- **[Repository Skills](/overview/skills/repo)** - Repository-specific guidelines From f01d7f9ae7ff8a2e07382355ab2a349d599fdd4b Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 7 Dec 2025 17:45:16 +0000 Subject: [PATCH 3/5] docs: Refactor CLI skills documentation - Remove Skills Support section from cli-mode.mdx (per user request) - Make skills documentation in cli-settings.mdx self-contained with: - Clear explanation of what skills are (markdown files, always-active or keyword-triggered) - Skill locations (user-level and repo-level) - Skill types with links to detailed docs - Environment variables for configuration - Comprehensive links to all related documentation - Simplify troubleshooting in keyword.mdx to first 3 bullets: - Kept critical information from other bullets (folder name mistake, case sensitivity) - Folded common mistakes into frontmatter section - Consolidated testing guidance into bullet 3 - Update all cross-references in overview/skills.mdx to point to cli-settings.mdx instead of removed cli-mode.mdx section All documentation now consistently points to cli-settings.mdx#skills-configuration for CLI skills information. Co-authored-by: openhands --- openhands/usage/run-openhands/cli-mode.mdx | 9 --- .../usage/run-openhands/cli-settings.mdx | 23 +++++- overview/skills.mdx | 4 +- overview/skills/keyword.mdx | 78 +++++-------------- 4 files changed, 40 insertions(+), 74 deletions(-) diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx index b08cc5e4..f481e7ba 100644 --- a/openhands/usage/run-openhands/cli-mode.mdx +++ b/openhands/usage/run-openhands/cli-mode.mdx @@ -126,12 +126,3 @@ Key features include: - MCP server management with `/mcp` - Conversation management with `/new` and `/help` - Real-time status monitoring and control - -## Skills Support - -The CLI loads skills from `~/.openhands/skills/` (user-level) and `.openhands/skills/` (repository-level). Skills are markdown files that can be always-active or keyword-triggered. - -**For complete documentation on skills:** -- **[Skills Overview](/overview/skills)** - What skills are and how they work -- **[Keyword-Triggered Skills](/overview/skills/keyword)** - Creating trigger-based skills -- **[Repository Skills](/overview/skills/repo)** - Repository-specific guidelines diff --git a/openhands/usage/run-openhands/cli-settings.mdx b/openhands/usage/run-openhands/cli-settings.mdx index a46f1eb4..ebdbf4c9 100644 --- a/openhands/usage/run-openhands/cli-settings.mdx +++ b/openhands/usage/run-openhands/cli-settings.mdx @@ -53,17 +53,32 @@ The `/mcp` command in the CLI provides a read-only view of MCP server status: ## Skills Configuration -Skills are specialized prompts that provide domain-specific knowledge to OpenHands. They are enabled by default in the CLI and load automatically from: +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. -- `~/.openhands/skills/` - User-level skills for all conversations +### Skill Locations + +The CLI automatically loads skills from: +- `~/.openhands/skills/` - User-level skills that apply to all conversations - `.openhands/skills/` - Repository-level skills for the current directory -For detailed information about creating and using skills, see [Using Skills with CLI](/openhands/usage/run-openhands/cli-mode#using-skills-with-cli). +### Skill Types + +- **[General Skills](/overview/skills/repo)**: Repository-wide guidelines (e.g., `repo.md`) that are always active +- **[Keyword-Triggered Skills](/overview/skills/keyword)**: Skills activated by specific keywords in user prompts (require frontmatter with `triggers:` field) + +### Skills-related Environment Variables -**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. diff --git a/overview/skills.mdx b/overview/skills.mdx index 7617c940..1ce06328 100644 --- a/overview/skills.mdx +++ b/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/` (user-level) and `.openhands/skills/` (repo-level) | File-based markdown | [CLI Mode](/openhands/usage/run-openhands/cli-mode#using-skills-with-cli) | +| **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) | @@ -66,7 +66,7 @@ Each skill file may include frontmatter that provides additional information. In - Markdown format for skill definitions - Manual file management required - Supports both general and keyword-triggered skills - - See [CLI Skills Documentation](/openhands/usage/run-openhands/cli-mode#using-skills-with-cli) for details + - See [CLI Skills Configuration](/openhands/usage/run-openhands/cli-settings#skills-configuration) for details - Programmatic `Skill` objects in code diff --git a/overview/skills/keyword.mdx b/overview/skills/keyword.mdx index 5852dff5..60a6a0d7 100644 --- a/overview/skills/keyword.mdx +++ b/overview/skills/keyword.mdx @@ -42,12 +42,10 @@ If your keyword-triggered skill isn't activating: - **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: -- Enclosed in triple dashes (`---`) at the top and bottom -- `triggers:` field must be present and properly indented -- Each trigger must be on its own line starting with a dash and space (`- `) +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 @@ -58,60 +56,22 @@ triggers: --- ``` -**Incorrect (will not work):** -```yaml ---- -triggers: [/myskill, myskill] # Wrong: not a list format ---- - -# Missing opening dashes -triggers: -- /myskill ---- - ---- -triggers: --/myskill # Wrong: missing space after dash ---- -``` - -### 3. Check Skills Are Enabled -Skills are enabled by default, but verify with: -- **Environment Variable**: Ensure `AGENT_ENABLE_PROMPT_EXTENSIONS=true` (default) -- **CLI**: Skills load automatically when the CLI starts +**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` -### 4. Test Your Trigger Keywords -- Trigger keywords are case-sensitive by default -- Try including both variations if needed: `- myskill` and `- MySkill` -- Use specific, unique keywords to avoid conflicts +### 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 - -### 5. Verify File Contents -- Ensure there's content below the frontmatter (the actual skill instructions) -- Use markdown formatting for the skill content -- Test with a simple skill first to verify the system is working - -### 6. Common Mistakes -- Using folder name `microagents` instead of `skills` (skills is the current name) -- Missing the triple dashes around frontmatter -- Incorrect YAML indentation -- Missing the colon after `triggers` -- Using quotes around trigger words (not required: use `- myword` not `- "myword"`) - -### 7. Testing -To test if your skill is working: -1. Start a new conversation (use `/new` in CLI) -2. Type a message containing your trigger keyword -3. The skill should activate and provide the guidance in your skill file - -If you're still having issues, try creating a minimal test skill: -```markdown ---- -triggers: -- testskill ---- - -TEST SKILL IS ACTIVE! This is a test skill. -``` - -If this minimal skill doesn't work, check your OpenHands configuration and ensure skills are supported in your version. +- Test with a simple skill to verify the system is working: + ```markdown + --- + triggers: + - testskill + --- + + TEST SKILL IS ACTIVE! This is a test skill. + ``` From e5c94c3b52829b1d5f68bbbafa0246963929d1d9 Mon Sep 17 00:00:00 2001 From: Graham Neubig Date: Sun, 7 Dec 2025 09:49:55 -0800 Subject: [PATCH 4/5] Update openhands/usage/run-openhands/cli-settings.mdx --- openhands/usage/run-openhands/cli-settings.mdx | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/openhands/usage/run-openhands/cli-settings.mdx b/openhands/usage/run-openhands/cli-settings.mdx index ebdbf4c9..2e7936a5 100644 --- a/openhands/usage/run-openhands/cli-settings.mdx +++ b/openhands/usage/run-openhands/cli-settings.mdx @@ -55,17 +55,6 @@ The `/mcp` command in the CLI provides a read-only view of MCP server status: 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. -### Skill Locations - -The CLI automatically loads skills from: -- `~/.openhands/skills/` - User-level skills that apply to all conversations -- `.openhands/skills/` - Repository-level skills for the current directory - -### Skill Types - -- **[General Skills](/overview/skills/repo)**: Repository-wide guidelines (e.g., `repo.md`) that are always active -- **[Keyword-Triggered Skills](/overview/skills/keyword)**: Skills activated by specific keywords in user prompts (require frontmatter with `triggers:` field) - ### Skills-related Environment Variables - `AGENT_ENABLE_PROMPT_EXTENSIONS` - Enable/disable skills (default: `true`) From 77a72a7714ea5d59b5d8b4fa72acd7df0eef1181 Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 19 Dec 2025 19:02:53 +0000 Subject: [PATCH 5/5] Address xingyaoww's review comments - Remove Skills Configuration section from cli-settings.mdx (CLI/SDK don't support those env vars) - Remove Troubleshooting section from keyword.mdx Co-authored-by: openhands --- .../usage/run-openhands/cli-settings.mdx | 20 +-------- overview/skills/keyword.mdx | 42 ------------------- 2 files changed, 1 insertion(+), 61 deletions(-) diff --git a/openhands/usage/run-openhands/cli-settings.mdx b/openhands/usage/run-openhands/cli-settings.mdx index 2e7936a5..b06e9ab5 100644 --- a/openhands/usage/run-openhands/cli-settings.mdx +++ b/openhands/usage/run-openhands/cli-settings.mdx @@ -51,27 +51,9 @@ 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 skills aren't working, see the [Keyword Skills Troubleshooting Guide](/overview/skills/keyword#troubleshooting) \ No newline at end of file +- If you want to start over, use `/new` to begin a fresh conversation without restarting the CLI. \ No newline at end of file diff --git a/overview/skills/keyword.mdx b/overview/skills/keyword.mdx index 60a6a0d7..50ccc6ab 100644 --- a/overview/skills/keyword.mdx +++ b/overview/skills/keyword.mdx @@ -33,45 +33,3 @@ 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. - ```