Adding New Skills

Learn how to add existing skills to your OpenHands workspace from the official registry or custom repositories.

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:

1. Parse the URL to identify the repository and skill path
2. Fetch the skill files from GitHub
3. Install the skill in .agents/skills/ directory
4. Verify the installation
5. 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:

CLI

The CLI supports two skill locations:

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

~/.openhands/skills/

Project-level skills (specific to current directory):

.agents/skills/

Skills added via /add-skill are installed in .agents/skills/ of your current workspace, making them available for that project.

To add skills globally, manually place skill directories in ~/.openhands/skills/.

SDK

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.

Local GUI

Skills are stored in:

.agents/skills/

The GUI provides a visual interface for managing skills, but skills can also be added manually by placing them in this directory.

OpenHands Cloud

OpenHands Cloud provides a centralized skill library accessible through the web interface. Skills can be:

• Added from the official registry with one click
• Imported from your connected repositories
• Shared across your team or organization

See the Cloud UI documentation for details.

Manual Installation

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

For Project-Level Skills

1. Create the skills directory if it doesn’t exist:

   mkdir -p .agents/skills
   

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

3. Verify the skill structure:

   ls .agents/skills/codereview/SKILL.md
   

For User-Level Skills (CLI Only)

1. Create the global skills directory:

   mkdir -p ~/.openhands/skills
   

2. Add skills to this directory:

   cp -r /path/to/skill ~/.openhands/skills/
   

Skills in ~/.openhands/skills/ are available in all your conversations when using the CLI.

Verifying Installation

After adding a skill, verify it’s available:

1. Check the file exists: The skill directory should contain at least a SKILL.md file

   ls .agents/skills/your-skill/SKILL.md
   

2. Test the trigger: For keyword-triggered skills, use one of the trigger words in your prompt:

   Help me set up kubernetes
   

3. 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:

1. Remove the old version:

   rm -rf .agents/skills/skill-name
   

2. 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:

1. Set the GITHUB_TOKEN environment variable:

export GITHUB_TOKEN=your_github_token

2. 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:

1. Rename the existing skill: Move or rename the existing skill directory
2. Choose a different installation location: Install at user-level vs project-level
3. 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