Overview

Skills are specialized prompts that enhance OpenHands with domain-specific knowledge, expert guidance, and automated task handling.

Skills are specialized prompts that enhance OpenHands with domain-specific knowledge, expert guidance, and automated task handling. They provide consistent practices across projects and can be triggered automatically based on keywords or context.

OpenHands supports an extended version of the AgentSkills standard with optional keyword triggers for automatic activation. See the SDK Skills Guide for details on the SKILL.md format.

Official Skill Registry

The official global skill registry is maintained at github.com/OpenHands/skills. This repository contains community-shared skills that can be used by all OpenHands agents. You can browse available skills, contribute your own, and learn from examples created by the community.

How Skills Work

Skills inject additional context and rules into the agent’s behavior.

At a high level, OpenHands supports two loading models:

• Always-on context (e.g., AGENTS.md) that is injected into the system prompt at conversation start.
• On-demand skills that are either:
  • triggered by the user (keyword matches), or
  • invoked by the agent (the agent decides to look up the full skill content).

Permanent agent context (recommended)

For repository-wide, always-on instructions, prefer a root-level AGENTS.md file.

We also support model-specific variants:

• GEMINI.md for Gemini
• CLAUDE.md for Claude

Triggered and optional skills

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.

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.

Example Repository Structure

some-repository/
├── AGENTS.md                       # Permanent repository guidelines (recommended)
└── .openhands/
    └── skills/
        ├── rot13-encryption/       # AgentSkills standard (progressive disclosure)
        │   ├── SKILL.md
        │   ├── scripts/
        │   │   └── rot13.sh
        │   └── references/
        │       └── README.md
        ├── another-agentskill/     # AgentSkills standard (progressive disclosure)
        │   ├── SKILL.md
        │   └── scripts/
        │       └── placeholder.sh
        └── legacy_trigger_this.md  # Legacy/OpenHands format (keyword-triggered)

Skill Types

Currently supported skill types:

• Permanent Context: Repository-wide guidelines and best practices. We recommend AGENTS.md (and optionally GEMINI.md / CLAUDE.md).
• Keyword-Triggered Skills: Guidelines activated by specific keywords in user prompts.
• Organization Skills: Team or organization-wide standards.
• Global Skills: 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
General Skills	No
Keyword-Triggered Skills	Yes

Skills Support Matrix

Platform	Support Level	Configuration Method	Implementation	Documentation
CLI	✅ Full Support	~/.openhands/skills/ (user-level) and .openhands/skills/ (repo-level)	File-based markdown	Skills Overview
SDK	✅ Full Support	Programmatic Skill objects	Code-based configuration	SDK Skills Guide
Local GUI	✅ Full Support	.openhands/skills/ + UI	File-based with UI management	Local Setup
OpenHands Cloud	✅ Full Support	Cloud UI + repository integration	Managed skill library	Cloud UI

Platform-Specific Differences

CLI

• 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

SDK

• Programmatic Skill objects in code
• Dynamic skill creation and management
• Integration with custom workflows
• Full control over skill lifecycle

Local GUI

• Visual skill management through UI
• File-based storage with GUI editing
• Real-time skill status display
• Drag-and-drop skill organization

OpenHands Cloud

• Cloud-based skill library management
• Team-wide skill sharing and templates
• Organization-level skill policies
• Integrated skill marketplace

Learn More

• For SDK integration: See SDK Skills Guide
• For architecture details: See Skills Architecture
• For specific skill types: See Repository Skills, Keyword Skills, Organization Skills, and Global Skills