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

# Skills Overview

> Give OpenHands reusable instructions, domain knowledge, workflows, and supporting resources.

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.

<Info>
  OpenHands supports the [Agent Skills specification](https://agentskills.io/specification) and adds optional features such as keyword triggers and path-triggered rules. Other Agent Skills clients may ignore these OpenHands extensions.
</Info>

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

1. **Discovery**: OpenHands loads each skill's `name` and `description` into the available-skills catalog.
2. **Invocation**: When a task matches the description, the agent invokes the skill by name and receives the full `SKILL.md` instructions.
3. **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.

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

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

## Five-Minute Setup

Add concise repository guidance and one on-demand skill:

```text theme={null}
my-repository/
├── AGENTS.md
└── .agents/
    └── skills/
        └── release-checklist/
            └── SKILL.md
```

```markdown title="AGENTS.md" theme={null}
# Repository Guidance

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

```markdown title=".agents/skills/release-checklist/SKILL.md" theme={null}
---
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](/overview/skills/creating) 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](https://github.com/OpenHands/extensions/tree/main/skills) | 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.

<Note>
  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](/sdk/guides/skill) for loader configuration.
</Note>

## OpenHands-Specific Skill Types

* [Repository Context](/overview/skills/repo) provides always-on project instructions.
* [Keyword-Triggered Skills](/overview/skills/keyword) activate when a user message contains configured terms.
* [Path-Triggered Rules](/overview/skills/path) apply deterministic instructions to matching files.
* [Organization and User Skills](/overview/skills/org) share guidance across repositories.
* [Global Skills](/overview/skills/public) 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                    |

In Agent Canvas, disabling a bundled or custom skill prevents it from being included in the agent context for new OpenHands and ACP conversations. Enabled skills remain available to new conversations.

See [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) for Agent Canvas and [Plugin Launcher](/openhands/usage/cloud/plugin-launcher) for loading a Git-hosted skill into an OpenHands Cloud conversation.

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

## Next Steps

* [Add an Existing Skill](/overview/skills/adding)
* [Create a Skill](/overview/skills/creating)
* [Browse the OpenHands Skills Registry](https://github.com/OpenHands/extensions/tree/main/skills)
* [Bundle Skills in a Plugin](/overview/plugins)
* [Monitor and Improve Skills](/overview/skills/monitoring)

## 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), [**Path-Triggered Rules**](/overview/skills/path), [**Organization Skills**](/overview/skills/org), and [**Global Skills**](/overview/skills/public)