Skills Overview

Skills give OpenHands reusable instructions for specialized tasks. A skill can capture domain knowledge, define a repeatable workflow, and include supporting scripts, references, or templates. Skills guide the agent’s behavior; they do not grant permissions or install dependencies by themselves. The agent can only use the files, tools, secrets, and network access available in its environment.

OpenHands supports the Agent Skills specification and adds optional features such as keyword triggers and path-triggered rules. Other Agent Skills clients may ignore these OpenHands extensions.

Choose the Right Mechanism

Need	Use	Recommended Location	Loading Behavior
Instructions for every task in a repository	`AGENTS.md`	Repository root	Full content is included in the initial system prompt
Reusable expertise or a workflow for a specific task	Agent Skills `SKILL.md`	`.agents/skills/<skill-name>/SKILL.md`	Name and description are advertised first; the agent invokes the full skill when relevant
Automatic activation for specific words or commands	`SKILL.md` with `triggers`	`.agents/skills/<skill-name>/SKILL.md`	The skill remains available for model invocation and its content is also injected when a trigger matches
Deterministic guidance for specific files	A skill with `paths`	`.agents/skills/<skill-name>/SKILL.md` or `.agents/skills/<rule-name>.md`	Content is injected when the agent first touches a matching file

Use AGENTS.md for short, repository-wide conventions. Use SKILL.md for focused knowledge that is needed only for some tasks. A legacy .md skill without a trigger is always loaded in full; prefer AGENTS.md for that use case so its purpose is clear. OpenHands also recognizes CLAUDE.md and GEMINI.md as model-specific repository context.

How Progressive Disclosure Works

Agent Skills use three levels of context:

Discovery: OpenHands loads each skill’s name and description into the available-skills catalog.
Invocation: When a task matches the description, the agent invokes the skill by name and receives the full SKILL.md instructions.
Resources: The agent reads referenced files from scripts/, references/, or assets/ only when needed.

This keeps the initial prompt smaller than loading every skill in full. Write the description to explain both what the skill does and when it applies; the agent uses that metadata to decide whether to invoke it. OpenHands supports two deterministic activation paths:

triggers injects the skill when a keyword or command appears in a user message. The skill is still available for model invocation.
paths turns the file into a path-triggered rule. The rule is not advertised to the model and is injected once per conversation when a matching file is read, edited, or created. If a file declares both paths and triggers, paths takes precedence.

Always-on content occupies the conversation context from the beginning. Keep AGENTS.md concise and move lengthy or specialized instructions into on-demand skills and references.

Official Skill Registry

The official global skill registry is maintained at github.com/OpenHands/extensions. 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.

Five-Minute Setup

Add concise repository guidance and one on-demand skill:

my-repository/
├── AGENTS.md
└── .agents/
    └── skills/
        └── release-checklist/
            └── SKILL.md

AGENTS.md

# Repository Guidance

Run the test suite before committing. Keep changes focused and follow the existing project conventions.

.agents/skills/release-checklist/SKILL.md

---
name: release-checklist
description: Prepare and verify a release checklist. Use when creating release notes or publishing a release.
---

Check the version, changelog, validation commands, and release notes before publishing.

For a portable Agent Skills package, name and description are required. The name must match the parent directory and use lowercase letters, numbers, and hyphens. See Creating Skills for the complete format and authoring guidance. Start a new conversation after changing skill files so OpenHands rebuilds the available-skills catalog.

Skill Locations and Precedence

OpenHands can combine skills from several scopes:

Scope	Recommended Location	Applies To
Repository context	`<repository>/AGENTS.md`	Conversations in that repository
Project skills	`<project>/.agents/skills/`	Conversations using that project workspace
User skills	`~/.agents/skills/`	Conversations for that user
Public skills	OpenHands extensions registry	Conversations configured to load the public registry

Both the legacy .openhands/skills/ and .openhands/microagents/ directories remain supported, but use .agents/skills/ for new skills. This location follows the Agent Skills standard and makes skills portable across compatible agent tools. Name conflicts are resolved by precedence rather than by merging skill bodies. For automatically loaded sources, project skills override user skills, and user skills override public skills. Within a project or user scope, .agents/skills/ takes precedence over the legacy directories.

In the SDK, explicitly supplied skills override automatically loaded user and public skills. Project skills are resolved from the conversation workspace and override a same-named skill from another source. See the SDK Skills Guide for loader configuration.

OpenHands-Specific Skill Types

Repository Context provides always-on project instructions.
Keyword-Triggered Skills activate when a user message contains configured terms.
Path-Triggered Rules apply deterministic instructions to matching files.
Organization and User Skills share guidance across repositories.
Global Skills are reusable skills published through the OpenHands extensions registry.

Using Skills Across OpenHands

Surface	How Skills Are Loaded
Agent Canvas	Manage installed skills under `Customize > Skills`; configuration is scoped to the active backend
SDK and agent server	Pass `Skill` objects directly or enable the user, project, and public file-based loaders in `AgentContext`
OpenHands Cloud	Select or import skills for a conversation, including skills stored in Git repositories

See Customize and Settings for Agent Canvas and Plugin Launcher for loading a Git-hosted skill into an OpenHands Cloud conversation.

Review a skill and its bundled resources before installing it. A skill can instruct the agent to run scripts, read files, use secrets, or call connected tools. Only install skills from sources you trust.

Next Steps

Learn More

For SDK integration: See SDK Skills Guide
For architecture details: See Skills Architecture
For specific skill types: See Repository Skills, Keyword Skills, Path-Triggered Rules, Organization Skills, and Global Skills

Get Started

Essential Guidelines

Use Cases

Product Guides

Additional Documentation

Deprecated Projects

OpenHands Community

Choose the Right Mechanism

How Progressive Disclosure Works

Official Skill Registry

Five-Minute Setup

Skill Locations and Precedence

OpenHands-Specific Skill Types

Using Skills Across OpenHands

Next Steps

Learn More

​Choose the Right Mechanism

​How Progressive Disclosure Works

​Official Skill Registry

​Five-Minute Setup

​Skill Locations and Precedence

​OpenHands-Specific Skill Types

​Using Skills Across OpenHands

​Next Steps

​Learn More

Choose the Right Mechanism

How Progressive Disclosure Works

Official Skill Registry

Five-Minute Setup

Skill Locations and Precedence

OpenHands-Specific Skill Types

Using Skills Across OpenHands

Next Steps

Learn More