docs: Add documentation of skills to the CLI section #156
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
- 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 <[email protected]>
Contributor
Author
|
|
I'm on it! neubig can track my progress at all-hands.dev |
- 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 <[email protected]>
neubig
commented
Dec 7, 2025
neubig
changed the title
xingyaoww
reviewed
Dec 8, 2025
| - **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` |
Contributor
There was a problem hiding this comment.
this shouldn't be a mistake? it should be backward compatible
| - **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` |
Contributor
There was a problem hiding this comment.
Suggested change
| - Common mistake: Using folder name `microagents` instead of `skills` |
| ### Skills-related Environment Variables | ||
|
|
||
| - `AGENT_ENABLE_PROMPT_EXTENSIONS` - Enable/disable skills (default: `true`) | ||
| - `AGENT_DISABLED_MICROAGENTS` - List of specific skills to disable |
Contributor
There was a problem hiding this comment.
I don't think CLI/SDK support these env vars?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds documentation about skills to the CLI section, mostly relying on pointing to the existing documentation in other places.