Principle:Openclaw Openclaw Skill Loading

Skill Loading

Skill Loading is the principle governing how OpenClaw discovers, parses, and filters agent skills. Skills are markdown documents (SKILL.md) that teach the AI agent how to accomplish tasks using available tools. The loading process scans multiple directories in a defined precedence order, parses YAML frontmatter for metadata and eligibility criteria, and filters skills based on the runtime environment.

Overview

Unlike plugins (which execute code), skills are declarative text injected into the agent system prompt. The skill loading pipeline must:

1. Discover skill directories across multiple source locations.
2. Parse each skill's SKILL.md frontmatter for metadata.
3. Merge skills from different sources with a clear precedence order.
4. Filter skills based on eligibility criteria (OS, required binaries, environment variables, config flags, and explicit enable/disable).
5. Format eligible skills into the agent prompt.

Discovery Sources and Precedence

Skills are loaded from four source types, listed from lowest to highest precedence. When two skills share the same name, the higher-precedence source wins:

Priority	Source	Directory	Description
1 (lowest)	Extra	Configured via skills.load.extraDirs + plugin skill dirs	Additional directories specified in config or contributed by plugins.
2	Bundled	Built-in skills shipped with OpenClaw	Skills included in the OpenClaw package.
3	Managed	~/.openclaw/skills/	User-installed skills in the global config directory.
4 (highest)	Workspace	<workspace>/skills/	Project-specific skills in the current workspace.

This ordering means workspace skills always override bundled or managed skills of the same name, enabling project-specific customization.

Frontmatter Metadata

Each SKILL.md can contain YAML frontmatter with an openclaw metadata block. The metadata controls:

Metadata Field	Type	Purpose
always	boolean	When true, the skill bypasses binary/env checks (but not explicit disable or OS filtering).
os	string[]	List of supported platforms (e.g., ["darwin", "linux"]). Skill is excluded if the runtime platform is not in the list.
requires.bins	string[]	All listed binaries must be found in PATH.
requires.anyBins	string[]	At least one of the listed binaries must be found in PATH.
requires.env	string[]	All listed environment variables must be set (or provided via skill config).
requires.config	string[]	All listed config paths must be truthy in the OpenClaw config.
primaryEnv	string	The environment variable that can be satisfied by the skill's apiKey config.
skillKey	string	Override key used for config lookup (defaults to the skill name).

Invocation Policy

Frontmatter also controls how the skill appears to users and the model:

Frontmatter Key	Default	Meaning
user-invocable	true	Whether the skill can be invoked as a slash command.
disable-model-invocation	false	When true, the skill is excluded from the model prompt (used for user-only commands).

Eligibility Filtering

The shouldIncludeSkill() function applies a cascade of checks:

1. Explicit disable. If skills.entries.<key>.enabled === false, the skill is excluded.
2. Bundled allowlist. If skills.allowBundled is set and the skill is bundled, it must appear in the list.
3. OS check. If the skill specifies os, the runtime platform (or remote platforms) must match.
4. Always flag. If always === true, remaining checks are skipped.
5. Binary checks. requires.bins (all required) and requires.anyBins (at least one required) are checked against PATH and remote capabilities.
6. Environment checks. requires.env variables must be present in the process environment, skill config env, or satisfied by apiKey + primaryEnv.
7. Config checks. requires.config paths must resolve to truthy values in the OpenClaw config.

Remote Eligibility

The eligibility context supports remote environments. When the agent runs remotely (e.g., on a VPS), the SkillEligibilityContext.remote field provides:

• platforms: platforms available on the remote host.
• hasBin(bin): checks if a binary exists on the remote host.
• hasAnyBin(bins): checks if any of the listed binaries exist remotely.

This allows skills to be included when their requirements are met by the remote environment, even if the local machine lacks the needed binaries.

Related Concepts

• Extension Type Identification -- how skills differ from plugins.
• Extension Configuration -- per-skill configuration and enable/disable.
• Extension Verification -- how loaded extensions report status.

Implementation

Implementation:Openclaw_Openclaw_LoadSkillEntries