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

CLI / Headless / Development Mode

User skills from ~/.agents/skills/ are loaded automatically — no extra configuration needed.

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:

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.26.0-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.8

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.

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

-e SANDBOX_VOLUMES="$HOME/my-skills:/home/openhands/.agents/skills:ro"

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

-e SANDBOX_VOLUMES="$HOME/project:/workspace:rw,$HOME/.agents/skills:/home/openhands/.agents/skills:ro"

See the SANDBOX_VOLUMES documentation for more details on the mount format.