Adding New Skills

OpenHands makes it easy to extend your agent’s capabilities by adding pre-built skills from the community or custom repositories. Skills can be added globally (available in all conversations) or to specific projects.

Using the Add-Skill Action

The quickest way to add a skill is using the /add-skill command in your conversation with OpenHands. This command fetches skills from GitHub repositories and installs them in your workspace.

Basic Usage

Provide a GitHub URL pointing to a skill:

/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview

OpenHands will:

Parse the URL to identify the repository and skill path
Fetch the skill files from GitHub
Install the skill in .agents/skills/ directory
Verify the installation
Make the skill immediately available

Supported URL Formats

The /add-skill command accepts various GitHub URL formats:

Full GitHub tree URL: https://github.com/OpenHands/extensions/tree/main/skills/codereview
Repository path: https://github.com/OpenHands/extensions/skills/codereview
Short form: github.com/OpenHands/extensions/skills/codereview
Shorthand: OpenHands/extensions/skills/codereview

Examples

Add the code review skill:

/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview-roasted

Add the Kubernetes skill:

/add-skill OpenHands/extensions/skills/kubernetes

Add a skill from a custom repository:

/add-skill https://github.com/your-org/your-repo/tree/main/custom-skills/analytics

Skill Storage Locations

Skills are stored in different locations depending on the platform and scope:

Agent Canvas
SDK
OpenHands Cloud

Manage skills under Customize > Skills. Skills are scoped to the active backend.Project-level skills (specific to the conversation workspace):

.agents/skills/

User-level skills (global, available in all conversations):

~/.agents/skills/

Skills added with /add-skill are installed in .agents/skills/ of the conversation workspace. Skills load when a conversation starts, so after installing a skill Agent Canvas shows a Start new conversation with this skill banner.See Customize and Settings for details.

SDK users programmatically load skills:

from openhands.sdk import Skill

# Load from a directory
skill = Skill.load("/path/to/skill")

# Load all skills from a directory
skills = Skill.load_all("/path/to/skills")

See the SDK Skills Guide for more details.

Manual Installation

You can also manually install skills by copying skill directories into the appropriate location.

For Project-Level Skills

Create the skills directory if it doesn’t exist:
mkdir -p .agents/skills

Copy or clone the skill directory:

# Using git
git clone https://github.com/OpenHands/extensions temp-clone
cp -r temp-clone/skills/codereview .agents/skills/
rm -rf temp-clone

# Or download and extract manually

Verify the skill structure:
ls .agents/skills/codereview/SKILL.md

For User-Level Skills

Create the global skills directory:
mkdir -p ~/.agents/skills
Add skills to this directory:
cp -r /path/to/skill ~/.agents/skills/

Skills in ~/.agents/skills/ are available in all your conversations. Start a new conversation after adding them so Agent Canvas picks them up.

Verifying Installation

After adding a skill, verify it’s available:

Check the file exists: The skill directory should contain at least a SKILL.md file
ls .agents/skills/your-skill/SKILL.md
Test the trigger: For keyword-triggered skills, use one of the trigger words in your prompt:
Help me set up kubernetes
Check skill loading: OpenHands will indicate when a skill is loaded in response to your prompt

Skill Updates

To update a skill to the latest version:

Remove the old version:
rm -rf .agents/skills/skill-name

Add the updated version:

/add-skill https://github.com/OpenHands/extensions/tree/main/skills/skill-name

Or manually pull updates if you cloned the skill repository.

Authentication for Private Skills

The /add-skill command automatically uses the GITHUB_TOKEN environment variable to access private repositories via the GitHub API. For manual git clone operations (such as when cloning directly into .agents/skills/), you’ll need to handle authentication differently—typically using SSH keys or embedding a personal access token in the clone URL. Using /add-skill with private repositories:

Set the GITHUB_TOKEN environment variable:

export GITHUB_TOKEN=your_github_token

Use /add-skill as normal with private repository URLs

The command will automatically use the token for authentication.

Skill Conflicts

If a skill with the same name already exists, OpenHands will warn you before overwriting. To resolve conflicts:

Rename the existing skill: Move or rename the existing skill directory
Choose a different installation location: Install at user-level vs project-level
Overwrite: Confirm the overwrite when prompted

Next Steps

Browse available skills in the official registry
Create your own skills for custom workflows
Learn about keyword triggers to make skills activate automatically
Understand skill structure for the AgentSkills format

Get Started

Essential Guidelines

Use Cases

Product Guides

Additional Documentation

OpenHands Community

Using the Add-Skill Action

Basic Usage

Supported URL Formats

Examples

Skill Storage Locations

Manual Installation

For Project-Level Skills

For User-Level Skills

Verifying Installation

Skill Updates

Authentication for Private Skills

Skill Conflicts

Next Steps

​Using the Add-Skill Action

​Basic Usage

​Supported URL Formats

​Examples

​Skill Storage Locations

​Manual Installation

​For Project-Level Skills

​For User-Level Skills

​Verifying Installation

​Skill Updates

​Authentication for Private Skills

​Skill Conflicts

​Next Steps

Using the Add-Skill Action

Basic Usage

Supported URL Formats

Examples

Skill Storage Locations

Manual Installation

For Project-Level Skills

For User-Level Skills

Verifying Installation

Skill Updates

Authentication for Private Skills

Skill Conflicts

Next Steps