> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  OpenHands supports an **extended version** of the [AgentSkills standard](https://agentskills.io/specification) with optional keyword triggers for automatic activation. See the [SDK Skills Guide](/sdk/guides/skill) for details on the SKILL.md format.
</Info>

## Official Skill Registry

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

## 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 `.agents/skills/*.md` at the repository root.

<Note>
  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.
</Note>

### Example Repository Structure

```
some-repository/
├── AGENTS.md                       # Permanent repository guidelines (recommended)
└── .agents/
    └── 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 Loading Precedence

For project location, paths are relative to the repository root; `.agents/skills/` is a subdirectory of the project directory.
For user home location, paths are relative to the user home: `~/`

When multiple skills share the same name, OpenHands keeps the first match in this order:

1. `.agents/skills/` (recommended)
2. `.openhands/skills/` (deprecated)
3. `.openhands/microagents/` (deprecated)

Project-specific skills take precedence over user skills.

## Skill Types

Currently supported skill types:

* **[Permanent Context](/overview/skills/repo)**: Repository-wide guidelines and best practices. We recommend `AGENTS.md` (and optionally `GEMINI.md` / `CLAUDE.md`).
* **[Keyword-Triggered Skills](/overview/skills/keyword)**: Guidelines activated by specific keywords in user prompts.
* **[Organization Skills](/overview/skills/org)**: Team or organization-wide standards.
* **[Global Skills](/overview/skills/public)**: 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 | `~/.agents/skills/` (user-level) and `.agents/skills/` (repo-level) | File-based markdown           | [Skills Overview](/overview/skills)                       |
| **SDK**             | ✅ Full Support | Programmatic `Skill` objects                                        | Code-based configuration      | [SDK Skills Guide](/sdk/guides/skill)                     |
| **Local GUI**       | ✅ Full Support | `.agents/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)               |

## Platform-Specific Differences

<Tabs>
  <Tab title="CLI">
    * File-based configuration in two locations:
      * `~/.agents/skills/` - User-level skills (all conversations).
      * `.agents/skills/` - Repository-level skills (current directory)
    * Markdown format for skill definitions
    * Manual file management required
    * Supports both general and keyword-triggered skills
  </Tab>

  <Tab title="SDK">
    * Programmatic `Skill` objects in code
    * Dynamic skill creation and management
    * Integration with custom workflows
    * Full control over skill lifecycle
  </Tab>

  <Tab title="Local GUI">
    * Visual skill management through UI
    * File-based storage with GUI editing
    * Real-time skill status display
    * Drag-and-drop skill organization
  </Tab>

  <Tab title="OpenHands Cloud">
    * Cloud-based skill library management
    * Team-wide skill sharing and templates
    * Organization-level skill policies
    * Integrated skill marketplace
  </Tab>
</Tabs>

## Learn More

* **For SDK integration**: See [SDK Skills Guide](/sdk/guides/skill)
* **For architecture details**: See [Skills Architecture](/sdk/arch/skill)
* **For specific skill types**: See [Repository Skills](/overview/skills/repo), [Keyword Skills](/overview/skills/keyword), [Organization Skills](/overview/skills/org), and [Global Skills](/overview/skills/public)