Skip to main content

​
Usage

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:
FieldDescriptionRequiredDefault
triggersA list of keywords that activate the skill.YesNone

​
Example

Keyword-triggered skill file example located at .openhands/skills/yummy.md: 
---
triggers:
- yummyhappy
- happyyummy
---

The user has said the magic word. Respond with "That was delicious!"
See examples of keyword-triggered skills in the official OpenHands Skills Registry

​
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: 
---
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: 
    ---
triggers:
- testskill
---

TEST SKILL IS ACTIVE! This is a test skill.