OpenClaw Skills Packaging and Extension Design

OpenClaw Skills Packaging and Extension Design

This article explains how Skills are structured, loaded, filtered, injected into prompts, and executed in OpenClaw.

1. Minimal Skill Packaging

A skill is a directory with SKILL.md as core entry.

  • Uses YAML frontmatter + markdown body
  • Parsed by loadSkillsFromDir and formatSkillsForPrompt
  • metadata frontmatter field is parsed as JSON5 string into metadata.openclaw

Minimal example:

markdown 
---
name: hello_world
description: A simple skill
---

# Hello
Use the echo tool to say hello.

2. Skill Sources and Precedence

Load order (low -> high priority):

  1. skills.load.extraDirs
  2. bundled skills
  3. managed skills (~/.openclaw/skills)
  4. workspace skills (<workspace>/skills)

Later source overrides earlier one on same skill name.

Bundled path resolution prefers env override, then compiled binary-adjacent skills/, then repo-root skills/.

Plugin-provided skills are loaded from plugin manifests and merged using the same precedence rules.

3. Frontmatter Metadata Design

Typical metadata.openclaw fields:

  • always, skillKey, primaryEnv
  • emoji, homepage, os
  • requires (bins, anyBins, env, config)
  • install specs (brew, node, go, uv, download)

Command behavior controls include:

  • user-invocable (default true)
  • disable-model-invocation (default false)
  • command-dispatch: tool + command-tool for direct tool dispatch

4. Eligibility Gating

shouldIncludeSkill applies checks in order:

  1. config disable (enabled=false)
  2. bundled allowlist restriction
  3. OS compatibility
  4. always=true short-circuit
  5. required binaries
  6. any-of binaries
  7. required env vars (or config-injected equivalents)
  8. required config path truthiness

Only eligible skills are included in skill prompt snapshots.

5. Config and Env Injection

skills.entries.<skillKey> supports:

  • enabled
  • apiKey
  • env
  • config

applySkillEnvOverrides injects env values only when the target key is currently unset. Injected values are scoped to a run and restored afterwards.

6. Prompt Snapshot and Watchers

buildWorkspaceSkillSnapshot builds:

  • prompt: formatted skill section for system prompt
  • skills: lightweight list used by env injection logic

ensureSkillsWatcher (chokidar) monitors workspace/managed/extra/plugin skill dirs and bumps snapshot version so next run picks up changes.

syncSkillsToWorkspace syncs skills into sandbox workspace with serialization lock.

7. Slash Commands and Dispatch

buildWorkspaceSkillCommandSpecs and skill-commands generate skill commands:

  • only for userInvocable !== false
  • normalized command names ([a-z0-9_], <= 32 chars)
  • collision resolution with suffix (_2, _3, ...)
  • generic /skill <name> [args] fallback
  • optional direct tool dispatch path bypassing model reasoning

8. Installer Architecture

Installer spec (metadata.openclaw.install) supports:

  • brew, node, go, uv, download

Selection policy prefers brew when configured and available, then uv, then node, then brew/go, then first entry.

download mode supports:

  • fetch
  • optional archive extraction (tar/unzip)
  • optional stripComponents
  • default install dir ~/.openclaw/tools/<skillKey>

9. Remote macOS Node Collaboration

When gateway is not on macOS but a macOS node is available with required system methods:

  • remote bin availability is probed
  • eligibility context includes remote capabilities
  • prompt adds remote execution hints (nodes.run)
  • remote capability changes bump snapshot version

10. CLI / Gateway API / UI Entry Points

CLI (openclaw skills):

  • skills list
  • skills info <name>
  • skills check

Gateway methods (skills.*):

  • skills.status
  • skills.bins
  • skills.install
  • skills.update

UI fetches these methods to render status, diagnostics, and install actions.

11. Potential Issues (Code Review)

  1. Frontmatter metadata parse failures degrade silently

    • Invalid JSON5 metadata may disable gating logic without strong user-visible errors.

  2. Download installer path lacks integrity verification

    • No built-in hash/signature check increases supply-chain risk.

  3. Env injection is fill-only

    • Existing stale env values are not overwritten by config values.

  4. Sandbox skill sync clears target before copy

    • Mid-copy failure can leave partially synced state.

  5. Command collision renaming has weak visibility

    • Auto-renamed commands can diverge from user expectation without strong surfacing.
Back to Resources

Table of Contents