Skill Precedence & Gating

+15 Mana ✨
OpenClaw Skill Precedence(DOCUMENTATION)OpenClaw Skill Gating Reference(DOCUMENTATION)

Introduction

When multiple skills with the same name exist across different sources, OpenClaw needs to decide which one to use. The skill precedence system resolves these conflicts with a clear hierarchy. Additionally, the gating system ensures skills only load when their requirements are met. Understanding both mechanisms is essential for managing skills in complex environments.

Key Concepts

  • Skill Precedence: The priority order that determines which version of a skill is used when duplicates exist
  • Load Order: Workspace skills override managed skills, which override bundled skills
  • Metadata Gating: Conditional loading based on required binaries, environment variables, OS, and install specifications
  • Bundled Skills: Skills that ship with OpenClaw out of the box
  • Managed Skills: Skills installed from ClawHub via clawhub install
  • Workspace Skills: Skills defined in the current workspace's skill directory

Real World Context

OpenClaw ships with a bundled commit skill that creates basic git commits. Your team installs a community commit skill from ClawHub that adds conventional commit format support. Additionally, one project has a workspace-level commit skill that enforces a project-specific commit template including ticket numbers. All three skills named commit exist simultaneously, and the workspace version takes precedence because it is the most specific to the current context.

Deep Dive

The skill precedence order follows a simple rule: more specific wins. Here is the hierarchy from highest to lowest priority:

markdown
Skill Precedence (highest to lowest):
1. Workspace skills   (~/.openclaw/agents/<id>/workspace/.openclaw/skills/)
2. Managed skills     (~/.openclaw/skills/ - installed via ClawHub)
3. Bundled skills     (shipped with OpenClaw installation)

When the agent looks for a skill named commit, it checks workspace skills first. If found, it uses that version and ignores managed and bundled versions. If not found in the workspace, it checks managed skills. If still not found, it falls back to bundled skills.

This precedence system means you can always override any skill by creating a workspace-level version with the same name.

Metadata gating controls whether a skill is available based on runtime conditions. The requires and os fields in the frontmatter define these conditions:

yaml
---
name: docker-deploy
description: Deploys applications using Docker Compose
user-invocable: true
requires:
  bins: ["docker", "docker-compose"]
  env: ["DOCKER_REGISTRY", "DEPLOY_TOKEN"]
os: ["macos", "linux"]
install: "brew install docker docker-compose"
---

This skill requires both docker and docker-compose on PATH, two environment variables, and only runs on macOS or Linux. If any condition is not met, the skill is marked as unavailable.

The gating checks happen at skill load time, not at invocation time. This means the agent knows upfront which skills are available and will not attempt to use a gated skill that cannot run.

Here is how gating fields work in detail:

markdown
Gating Fields:
- requires.bins: List of executables that must exist on PATH
  Example: ["git", "gh", "node"]
  Check: `which <bin>` returns success

- requires.env: List of environment variables that must be set
  Example: ["GITHUB_TOKEN", "AWS_REGION"]
  Check: Variable is defined and non-empty

- os: List of allowed operating systems
  Example: ["macos", "linux", "windows"]
  Check: Current OS matches one in the list

- install: Command to install missing dependencies
  Example: "npm install -g @company/deploy-tools"
  Usage: Shown to user when requirements are not met

The install field is informational only. OpenClaw does not automatically run install commands. It displays the command to the user when a skill is unavailable due to missing dependencies, letting the user decide whether to install them.

Common Pitfalls

  • Not realizing workspace skills override everything: If you create a workspace skill with the same name as a bundled skill, the bundled version is completely hidden. This is by design but can be surprising.
  • Omitting the install field: When a skill fails gating, the user sees a generic "requirements not met" message. Including an install command gives them a clear path to resolution.
  • Using overly strict OS gating: Unless your skill genuinely cannot work on certain operating systems, omit the os field to maximize availability.

Best Practices

  • Use workspace skills for project-specific overrides: When a project needs a different version of a common skill, create it at the workspace level rather than modifying the managed version.
  • Always include the install field: Even if it is just a hint, it saves users time when they encounter missing dependencies.
  • Test gating conditions on all target platforms: A skill that gates on docker works on a developer's machine but may fail in CI where Docker is not available.

Summary

  • Skill precedence follows workspace > managed > bundled, where more specific sources win
  • Workspace skills can override any managed or bundled skill by using the same name
  • Metadata gating checks required binaries, environment variables, and OS at load time
  • The install field provides a user-facing hint for resolving missing dependencies
  • Gating checks happen at load time, so the agent knows upfront which skills are available
✓ Completed