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

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

<Tabs>
  <Tab title="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/`.
  </Tab>

  <Tab title="SDK">
    SDK users programmatically load skills:

    ```python theme={null}
    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](/sdk/guides/skill) for more details.
  </Tab>

  <Tab title="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.
  </Tab>

  <Tab title="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](/openhands/usage/cloud/cloud-ui) for details.
  </Tab>
</Tabs>

## 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:
   ```bash theme={null}
   mkdir -p .agents/skills
   ```

2. Copy or clone the skill directory:
   ```bash theme={null}
   # 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:
   ```bash theme={null}
   ls .agents/skills/codereview/SKILL.md
   ```

### For User-Level Skills (CLI Only)

1. Create the global skills directory:
   ```bash theme={null}
   mkdir -p ~/.openhands/skills
   ```

2. Add skills to this directory:
   ```bash theme={null}
   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
   ```bash theme={null}
   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**:
   ```bash theme={null}
   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:

```bash theme={null}
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](https://github.com/OpenHands/extensions)** in the official registry
* **[Create your own skills](/overview/skills/creating)** for custom workflows
* **[Learn about keyword triggers](/overview/skills/keyword)** to make skills activate automatically
* **[Understand skill structure](/sdk/guides/skill)** for the AgentSkills format