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

# Organization and User Skills

> Organizations and users can define skills that apply to all repositories belonging to the organization or user.

## Usage

These skills can be [any type of skill](/overview/skills#skill-types) and will be loaded
accordingly. However, they are applied to all repositories belonging to the organization or user.

Add a `.agents` repository under the organization or user and create a `skills` directory and place the
skills in that directory.

For GitLab organizations, use `openhands-config` as the repository name instead of `.agents`, since GitLab doesn't support repository names starting with non-alphanumeric characters.

## Example

General skill file example for organization `Great-Co` located inside the `.agents` repository:
`skills/org-skill.md`:

```
* Use type hints and error boundaries; validate inputs at system boundaries and fail with meaningful error messages.
* Document interfaces and public APIs; use implementation comments only for non-obvious logic.
* Follow the same naming convention for variables, classes, constants, etc. already used in each repository.
```

For GitLab organizations, the same skill would be located inside the `openhands-config` repository.

## User Skills When Running OpenHands on Your Own

When running OpenHands on your own, you can place skills in the `~/.agents/skills/` folder on your local
system and OpenHands will always load them for all your conversations. Repo-level overrides live in `.agents/skills/`.

<Tabs>
  <Tab title="CLI / Headless / Development Mode">
    User skills from `~/.agents/skills/` are loaded automatically — no extra configuration needed.
  </Tab>

  <Tab title="Docker">
    When running OpenHands via Docker, the agent-server container cannot see your host filesystem by default.
    You need to mount your local skills directory into the sandbox using the `SANDBOX_VOLUMES` environment variable:

    ```bash theme={null}
    docker run -it --rm --pull=always \
      -e SANDBOX_VOLUMES="$HOME/.agents/skills:/home/openhands/.agents/skills:ro" \
      -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
      -e AGENT_SERVER_IMAGE_TAG=1.19.1-python \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -v ~/.openhands:/.openhands \
      -p 3000:3000 \
      --add-host host.docker.internal:host-gateway \
      --name openhands-app \
      docker.openhands.dev/openhands/openhands:1.7
    ```

    <Warning>
      Mount into `~/.agents/skills` inside the container (not `~/.openhands/skills`). Mounting
      into `~/.openhands/skills` would overwrite the public skills cache and prevent built-in
      skills from loading.
    </Warning>

    You can store your skills in any host directory (e.g., `~/my-skills/`) and mount them
    to `~/.agents/skills` in the sandbox:

    ```bash theme={null}
    -e SANDBOX_VOLUMES="$HOME/my-skills:/home/openhands/.agents/skills:ro"
    ```

    If you also need to mount a workspace, use a comma-separated list:

    ```bash theme={null}
    -e SANDBOX_VOLUMES="$HOME/project:/workspace:rw,$HOME/.agents/skills:/home/openhands/.agents/skills:ro"
    ```

    See the [SANDBOX\_VOLUMES documentation](/openhands/usage/sandboxes/docker#using-sandbox_volumes) for more details
    on the mount format.
  </Tab>
</Tabs>