Overview
In a multi-agent architecture, Skills are the core medium through which an agent perceives and uses tools. OpenClaw, as a mature agent runtime framework, implements a layered invocation mechanism: skill discovery, priority resolution, load-time filtering, and agent-level visibility control — each with explicit rules. This article dissects the layered architecture so developers and operators can understand exactly how skills get loaded, filtered, and invoked.
What Is a Skill?
In OpenClaw, every Skill is a directory containing a SKILL.md file. The file combines YAML frontmatter with Markdown instructions telling the agent when and how to use a specific tool. A typical layout:
skills/
github/
SKILL.md
weather/
SKILL.md
wp-post-from-outline/
SKILL.md
scripts/When an agent starts, OpenClaw scans every registered skill directory, injects qualifying skills into the system prompt, and the agent can invoke them in conversation.
The Six-Layer Loading Priority
OpenClaw loads skills from multiple sources. When same-named skills appear in different locations, the highest-priority source wins. The order, highest to lowest:
Layer 1: Workspace Skills — <workspace>/skills/. Each agent has its own workspace; skills here are visible only to that agent and override any same-named skill elsewhere.
Layer 2: Project Agent Skills — <workspace>/.agents/skills/. Workspace-level shared skills, visible to agents in that workspace.
Layer 3: Personal Agent Skills — ~/.agents/skills/. Machine-level personal skills, visible to all agents.
Layer 4: Managed/Local Skills — ~/.openclaw/skills/. For local overrides and patches, shared by all agents.
Layer 5: Bundled Skills — shipped with the OpenClaw installation; lowest standard priority.
Layer 6: Extra Skill Folders — configured via skills.load.extraDirs; also lowest priority.
The layering guarantees one invariant: agent-level customization always outranks global defaults, while flexible sharing is preserved underneath.
Skill Isolation in Multi-Agent Mode
In single-agent mode every skill is visible to the one agent. In multi-agent mode, each agent owns an independent workspace (containing AGENTS.md, SOUL.md, USER.md, and skills/), its own authentication configuration with separate auth profiles, and its own session storage. When loading, OpenClaw first merges all sources (deduplicating same-named skills by priority), then applies agent-level visibility filtering. That means: location/priority decides which copy wins; the agent allowlist decides which skills are visible; and the two are independent control dimensions.
The Agent Skill Allowlist
Fine-grained visibility comes through agents.defaults.skills and agents.list[].skills:
{
"agents": {
"defaults": {
"skills": ["github", "weather"]
},
"list": [
{ "id": "writer" },
{ "id": "docs", "skills": ["docs-search"] },
{ "id": "locked-down", "skills": [] }
]
}
}The rules: omit agents.defaults.skills and all skills are available by default; omit agents.list[].skills and the agent inherits the defaults; set agents.list[].skills: [] and the agent gets no skills at all; and a non-empty list is the final set — it does not merge with defaults. This design lets teams assign different skill sets to role-differentiated agents: a customer-service agent limited to weather and search, while an ops agent gets github and healthcheck.
The Gating Mechanism
Even allowlisted skills pass through load-time runtime filtering. The metadata.openclaw field in SKILL.md declares preconditions:
---
name: image-lab
description: Generate images via provider
metadata: {"openclaw": {"requires": {"bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"]}}}
---Supported gate types: requires.bins (binaries that must exist on PATH), requires.anyBins (at least one of several), requires.env (required environment variables), requires.config (required OpenClaw config entries), and os (darwin/linux/win32). Only skills whose every condition is satisfied get injected into the agent’s context — preventing the agent from seeing skills it cannot actually use and erroring out.
Plugin-Bundled Skills
OpenClaw’s plugin system can carry its own skills. A plugin declares a skills directory in openclaw.plugin.json, and enabling the plugin loads the skills automatically. The browser plugin, for example, bundles the browser-automation skill that teaches the agent multi-step browser control. Plugin skills rank alongside skills.load.extraDirs and can be overridden by workspace or bundled skills. The design achieves capability self-containment: install the plugin and its operating manual is immediately available, no extra configuration.
Environment Injection and Security Boundaries
When an agent runs, OpenClaw processes in order: read skill metadata; apply skills.entries.<key>.env and apiKey values into process.env; build the system prompt containing only qualifying skills; and restore the original environment after the run. Environment injection is scope-isolated — it applies only while that agent runs, never touching the global shell. In sandboxed environments, skill processes run inside the container without inheriting the host’s process.env, so sandbox variables must be configured separately through agents.defaults.sandbox.docker.env.
Snapshots and Hot Reload
OpenClaw snapshots qualifying skills at session start, and later turns in the same session reuse that snapshot; skill changes take effect at the next new session. Two cases support in-session hot reload: when the skill watcher is enabled (skills.load.watch: true, on by default), and when a new remote macOS node appears. The watcher refreshes the snapshot on SKILL.md file-change events, debounced at 250ms.
The Token Cost, Quantified
Qualifying skills are injected into the system prompt as a compact XML list, and the token overhead is deterministic: a base overhead of 195 characters once at least one skill is present, plus 97 characters per skill plus the XML-escaped lengths of its name, description, and location. The formula: total = 195 + Σ(97 + len(name) + len(description) + len(location)). At OpenAI’s rough estimate of four characters per token, each skill costs about 24 tokens of base overhead plus its field content — so keeping the skill count disciplined directly lowers context cost.
A Practical Multi-Agent Configuration
Suppose a team needs three agents: main, a daily assistant with general skills; coding, a code assistant with GitHub and coding skills; and family, a restricted household assistant:
{
"agents": {
"defaults": {
"skills": ["weather", "search", "summarizer"]
},
"list": [
{
"id": "main",
"workspace": "~/.openclaw/workspace-main"
},
{
"id": "coding",
"workspace": "~/.openclaw/workspace-coding",
"skills": ["github", "coding-agent", "summarizer"]
},
{
"id": "family",
"workspace": "~/.openclaw/workspace-family",
"skills": ["weather"],
"sandbox": { "mode": "all" }
}
]
}
}All three agents share one machine and one gateway process, yet skill visibility is fully isolated — and the family agent even runs inside a sandbox.
The Bottom Line
OpenClaw’s layered skills mechanism compresses into three strata: a discovery layer of six priority tiers where the highest-priority same-named skill wins; a filtering layer whose gating on bins/env/config/os guarantees skills can actually run; and a visibility layer of agent allowlists for fine-grained permissions. The design is flexible — every layer configures independently — and safe, with sandbox isolation and allowlist control. For any multi-agent deployment, understanding this mechanism is the key to building reliable agent infrastructure.
Tags: OpenClaw, agent, skills, multi-agent, skill system
