OpenHands skills. Where they live and how to install them.

What skills are in OpenHands

OpenHands documents skills as reusable instructions for specialised tasks. A skill can capture domain knowledge, define a repeatable workflow, and include scripts, references or templates. OpenHands supports the Agent Skills specification and adds optional features of its own, such as keyword triggers and path-triggered rules, which other Agent Skills clients may ignore.

The documentation draws a line between two mechanisms. AGENTS.md at the repository root holds short, always-on guidance that goes into the initial system prompt. A SKILL.md holds focused knowledge needed only for some tasks, and only its name and description are advertised until the agent invokes it. Skills guide the agent but do not grant permissions or install dependencies, so the agent can only use the files, tools, secrets and network access its environment already has.

Where OpenHands looks for skills

The legacy .openhands/skills/ and .openhands/microagents/ folders still work, but new skills should go in .agents/skills/. In the CLI, user-level skills can also live in ~/.openhands/skills/. When names clash, project skills override user skills and user skills override public skills. Within one scope, .agents/skills/ takes precedence over the legacy folders.

Install a skill

The examples use frontend-design from anthropics/skills, located at skills/frontend-design.

Option 1: the /add-skill command

In a conversation with OpenHands, give it a GitHub URL for the skill:

/add-skill https://github.com/anthropics/skills/tree/main/skills/frontend-design

OpenHands parses the URL, fetches the skill files, installs them in .agents/skills/ of the current workspace, verifies the installation and makes the skill available immediately. The command also accepts forms like github.com/OpenHands/extensions/skills/codereview and OpenHands/extensions/skills/kubernetes.

Option 2: the skills CLI

npx skills add anthropics/skills --skill frontend-design -a openhands

This writes to .openhands/skills/, the legacy folder that OpenHands still supports. Add -g for ~/.openhands/skills/.

Option 3: GitHub CLI

gh skill install anthropics/skills frontend-design --agent openhands
gh skill install anthropics/skills frontend-design --agent openhands --scope user

Needs GitHub CLI 2.90.0 or later, where gh skill is a public preview.

Option 4: copy the folder

git clone --depth 1 https://github.com/anthropics/skills.git skills-src
mkdir -p .agents/skills
cp -r skills-src/skills/frontend-design .agents/skills/frontend-design
rm -rf skills-src

Use ~/.agents/skills/ for a user-level skill.

Other surfaces

In OpenHands Cloud you can add skills from the official registry or import them from connected repositories through the web interface. In Agent Canvas, installed skills are managed under Customize > Skills, where only recommended skills are enabled by default and you can switch on others one by one. SDK users load skills with Skill.load or Skill.load_all.

Check that it loaded

Start a new conversation after you change skill files, because OpenHands rebuilds its available-skills catalogue then. In Agent Canvas, open Customize > Skills to see what is enabled. Otherwise ask the agent about its available skills, or give it a task that matches the skill's description and see whether it invokes the skill by name.

Update and remove

• Remove: delete the skill folder, or run npx skills remove frontend-design.
• Update: run /add-skill again with the same URL, or copy a newer version of the folder. npx skills update and gh skill update cover skills installed with those tools.
• In Agent Canvas, disabling a skill keeps it out of the context for new conversations.

Troubleshooting

• The skill is not available in the current conversation: start a new one.
• The name must match the parent directory and use lowercase letters, numbers and hyphens.
• A skill from an older location wins unexpectedly: compare scopes. A project skill overrides a same-named user skill.
• An SDK integration ignores your folders: pass skills explicitly or enable the user, project and public file-based loaders in AgentContext.
• A trigger-based skill acts differently from a plain one: a skill with paths becomes a path-triggered rule that is not advertised to the model and is injected when a matching file is first touched.

Safety

OpenHands tells you to review a skill and its bundled resources before installing it, because a skill can instruct the agent to run scripts, read files, use secrets or call connected tools. Only install skills from sources you trust, and remember the agent can only use what its environment provides, so limiting secrets and network access in that environment is part of the protection.