Advanced Skills Techniques: OS Filtering, Dependency Gating, Command Dispatch and Token Control

Chapter 20: Advanced Skills Techniques — OS Filtering, Dependency Gating, command-dispatch, and Token Control

Chapter Overview

This is the final chapter of the Skills section in the OpenClaw Complete Guide. The preceding chapters established the foundational Skills knowledge framework. This chapter dives into the advanced features that make Skills truly professional: precise OS filtering, multi-dimensional dependency gating, the internal mechanics of command-dispatch, when to hide a Skill from the model, and how to combine multiple techniques to minimize token costs while keeping full functionality.

20.1 OS Filtering: Ensuring Skills Only Appear on the Right Platform

The Problem

Many Skills depend on platform-specific tools or behaviors:

• macOS-specific: brew, pbcopy, open, caffeinate
• Linux-specific: apt, systemctl, xclip
• Windows-specific: winget, clip.exe, PowerShell

If a Skill that depends on brew appears as "available" on Linux, triggering it immediately produces an error — a terrible user experience. OS filtering solves this problem.

Configuration

metadata:
  openclaw:
    os: darwin    # macOS only

metadata:
  openclaw:
    os: linux     # Linux only (including WSL)

metadata:
  openclaw:
    os: win32     # Windows only (including Windows 11)

Omitting the os field = available on all platforms.

How OS Filtering Works Internally

OpenClaw detects the current platform at startup (via process.platform) and applies the following logic when loading Skills:

Load Skill metadata → read os field
  ├─ os field absent → load (all platforms)
  ├─ os matches current platform → load
  └─ os does not match → skip entirely (nothing injected into context)

Key point: A non-matching Skill does not appear in the model's context at all — saving tokens and preventing accidental triggering.

Hands-On Example: macOS Clipboard Skill

---
name: clipboard-mac
description: |
  Manage clipboard content on macOS: copy text to the clipboard,
  read clipboard content, and append content to the clipboard.
metadata:
  openclaw:
    emoji: "📋"
    os: darwin
    requires:
      bins:
        - pbcopy
        - pbpaste
---

# macOS Clipboard Operations

## Write to Clipboard

```bash
# Copy text to clipboard
echo "Hello, World" | pbcopy

# Copy file contents to clipboard
cat file.txt | pbcopy

# Copy command output to clipboard
ls -la | pbcopy

Read from Clipboard

# View clipboard contents
pbpaste

# Write clipboard contents to a file
pbpaste > output.txt

---

## 20.2 The Four requires Dimensions: Differences and Selection

### Dimension 1: requires.bins (Hard Binary Dependencies)

**Semantics:** ALL listed executables must exist in PATH.

```yaml
requires:
  bins:
    - git
    - gh
    - jq

Use case: The Skill's functionality cannot degrade and has no fallback alternative.

Actual check performed:

OpenClaw executes the equivalent of `which git && which gh && which jq`
If any single check fails → Skill does not load

Dimension 2: requires.anyBins (Soft Multi-Option Dependency)

Semantics: At least ONE must exist.

requires:
  anyBins:
    - yarn
    - npm
    - pnpm
    - bun

Use case: Multiple tools can accomplish the task; the Skill detects which one to use internally.

In-Skill tool detection pattern:

## Determine the Package Manager

Detect in priority order:
1. `which bun`  → use bun
2. `which yarn` → use yarn
3. `which pnpm` → use pnpm
4. `which npm`  → use npm (always present in a Node.js environment)

Stop at the first available option.

Dimension 3: requires.env (Environment Variable Gating)

Semantics: All listed environment variables must exist and be non-empty.

requires:
  env:
    - GITHUB_TOKEN
    - SLACK_WEBHOOK_URL

Common environment variables:

Note: requires.env only checks whether the variable exists — it does not validate whether the value is correct. An invalid API key will only fail at call time.

Dimension 4: requires.config (Feature Flag Gating)

Semantics: The specified paths in openclaw.json must exist and be truthy.

requires:
  config:
    - features.experimental.acp
    - tools.browser.enabled

Corresponding openclaw.json configuration:

{
  "features": {
    "experimental": {
      "acp": true
    }
  },
  "tools": {
    "browser": {
      "enabled": true
    }
  }
}

Use case: Experimental feature flags, enterprise-tier features, high-risk features that require explicit user opt-in.

Combining All Four Dimensions

requires:
  bins:
    - docker
    - kubectl
  anyBins:
    - helm
    - kustomize
  env:
    - KUBECONFIG
    - DOCKER_REGISTRY_TOKEN
  config:
    - features.k8s.enabled

All conditions must be satisfied simultaneously for the Skill to load. If any single dimension fails, the Skill is skipped entirely.

20.3 The Four install Script Types

When a binary listed in requires.bins is missing, OpenClaw can attempt automatic installation using the install configuration.

Type 1: brew (macOS Homebrew)

install:
  - type: brew
    pkg: ffmpeg
  - type: brew
    pkg: imagemagick
    tap: homebrew/cask    # Optional: specify a tap

Applies to: macOS users; requires Homebrew to already be installed.

Equivalent command:

brew install ffmpeg
brew install imagemagick

Type 2: node (npm/npx packages)

install:
  - type: node
    pkg: "@anthropic-ai/claude-cli"
    global: true
  - type: node
    pkg: "tsx"
    global: true

Equivalent command:

npm install -g @anthropic-ai/claude-cli
npm install -g tsx

Type 3: go (Go binary tools)

install:
  - type: go
    pkg: github.com/cli/cli/v2@latest

Equivalent command:

go install github.com/cli/cli/v2@latest

Prerequisite: Go must already be installed (Go itself is not automatically installed).

Type 4: uv (Python tools)

install:
  - type: uv
    pkg: ruff
  - type: uv
    pkg: mypy

Equivalent command:

uv tool install ruff
uv tool install mypy

Note: uv is a modern Python tool manager — faster and safer than pip install.

Type 5: download (Direct Binary Download)

install:
  - type: download
    url: https://releases.example.com/tool-v2.0-darwin-arm64.tar.gz
    dest: ~/.local/bin/
    extract: true
    chmod: "0755"
    binary: tool

Applies to: Closed-source tools without package manager support, or when a specific version is required.

The Full Auto-Install Flow

User triggers a Skill with requires.bins: [ffmpeg]
  ↓
OpenClaw checks: which ffmpeg → not found
  ↓
Reads install config: type: brew, pkg: ffmpeg
  ↓
Prompts user:
  "ffmpeg is not installed. Install automatically? (y/n)"
  ↓
User confirms → executes brew install ffmpeg
  ↓
Installation complete → continues loading and executing the Skill

20.4 command-dispatch Internal Mechanics

The Zero-Reasoning Call Path

Normal Skill invocation flow:

User input → [model token consumption] → model decision → tool call → result

command-dispatch invocation flow:

User input → OpenClaw routing layer → tool call → result
(model bypassed entirely, 0 tokens consumed)

How the Routing Layer Works

When OpenClaw receives /browser https://example.com:

1. Parse slash command name: browser
2. Find the Skill named browser
3. Check whether the Skill has command-dispatch: tool set
4. Yes → read command-tool: "browser_action"
5. Read command-arg-mode: raw
6. Pass "https://example.com" as a raw string to browser_action
7. Return tool result directly
(Language model is not invoked at any step)

Real-World Token Savings from command-dispatch

Scenario: User averages 20 /browser command invocations per day

Calculated at GPT-4 tier $0.03/1K tokens

The Two command-arg-mode Modes

raw mode:

User input:  /search --limit 10 python async best practices
Tool receives: python async best practices --limit 10
(arguments passed verbatim, no parsing)

parsed mode (default):

User input:  /search --limit 10 python async best practices
Tool receives: {query: "python async best practices", limit: 10}
(arguments parsed into structured format)

20.5 When to Use disable-model-invocation

When Should a Skill Be Hidden?

disable-model-invocation: true completely removes a Skill from the model's context. Use it in these scenarios:

Scenario 1: Internal tools that should not be exposed to users

---
name: internal-diagnostics
description: Internal diagnostics tool (not for end users)
disable-model-invocation: true
user-invocable: true   # Only invocable by users who know the command name
---

Scenario 2: High-frequency command tools where you want to minimize context

---
name: clipboard
description: Quick clipboard operations
disable-model-invocation: true
user-invocable: true
command-dispatch: tool
command-tool: "clipboard_action"
---

This Skill will never be auto-triggered by the model and takes zero context, but users can access it directly via /clipboard.

Scenario 3: High-risk operations where accidental model triggering is unacceptable

---
name: production-deploy
description: Deploy to the production environment (dangerous operation)
disable-model-invocation: true
user-invocable: true
---

The Skill can only trigger when the user explicitly types /production-deploy. The model will never autonomously decide "it's time to deploy" during a conversation.

Choosing Between disable-model-invocation and requires.config

20.6 always: true — Risks and Valid Use Cases

always: true is a special field that causes a Skill to bypass all gates (including requires checks) and always be available.

Configuration

---
name: core-guidelines
description: Core behavioral guidelines, always active
metadata:
  openclaw:
    always: true
---

# Core Guidelines

Apply these principles in every conversation:
- Confirm understanding of user intent before answering
- Provide a test strategy alongside any code
- Explicitly state uncertainty when it exists

Genuinely Valid Use Cases (Very Few)

• Global behavioral guidelines: conventions that should apply in every conversation
• Context injection: environment information the model always needs to know
• Emergency overrides: temporarily overriding behavior (during debugging)

Risks of always: true

Recommendation: In the vast majority of cases, do not use always: true. If you truly need it, keep the Skill body under 200 tokens.

20.7 Token Cost Control: Combining Lazy-Loading with command-dispatch

Strategy Architecture

High-frequency command-like operations
    ↓
command-dispatch + disable-model-invocation
    → 0 token cost

Low-frequency operations requiring reasoning
    ↓
Lazy-loading (metadata injection only)
    → ~50 token metadata; full content loaded on activation

Deep reference material
    ↓
references/ directory + {baseDir} references
    → Loaded only when explicitly needed

Case Study: Optimizing Token Costs for a Team Toolkit

Scenario: Team uses 15 Skills, 50 conversation rounds per day, average 2 Skills activated per round.

Before optimization (full load):

Per conversation round: 15 Skills × 1,500 tokens = 22,500 tokens (Skills portion)
Daily: 50 × 22,500 = 1,125,000 tokens
Monthly cost: ~$33.75

After optimization (lazy-loading + command-dispatch):

Per conversation round:
  - Metadata: 15 × 50 tokens = 750 tokens
  - Activated Skills: 2 × 1,500 tokens = 3,000 tokens
  - command-dispatch Skills (5 of them): 0 tokens
  Total: 3,750 tokens (Skills portion)

Daily: 50 × 3,750 = 187,500 tokens
Monthly cost: ~$5.63

Savings: 83%

Assigning Techniques by Operation Type

20.8 Multi-Skill Collaboration: The skill-creator Meta-Skill

The Meta-Skill Concept

A meta-skill is a special category of Skill whose purpose is to create other Skills. This is the most advanced usage pattern in the OpenClaw Skills system.

Complete skill-creator SKILL.md

---
name: skill-creator
description: |
  Use when the user wants to create a new OpenClaw Skill, package a
  repetitive workflow as a Skill, or asks how to write a SKILL.md file.
  Guides the user through a question-and-answer process to generate
  a complete Skill file.
user-invocable: true
metadata:
  openclaw:
    emoji: "🏗️"
    primaryEnv: shell
---

# Skill Creator — Skill Authoring Wizard

## Step 1: Gather Information

Ask the user the following questions, one at a time, waiting for each answer:

1. **What should this Skill do?** (One-sentence description of the core function)
2. **When would a user need it?** (Trigger scenarios — for the description field)
3. **Which external tools does it depend on?** (For requires.bins)
4. **Which environment variables does it need?** (For requires.env)
5. **Which operating systems should it run on?** (darwin / linux / win32 / all)
6. **Can users invoke it via a slash command?** (user-invocable)
7. **Is there a simple command-line form?** (Whether command-dispatch is appropriate)

## Step 2: Choose the Right Pattern

Based on the gathered information, apply this logic:

Is there a clearly defined single tool call? ├─ Yes → command-dispatch pattern └─ No → Is there a complex workflow? ├─ Yes → Informational or TDD Professional pattern └─ No → Does it depend on external tools? ├─ Yes → Tool Integration pattern └─ No → Minimal Tool pattern (most concise)

## Step 3: Generate the SKILL.md

Using the gathered information, generate a complete SKILL.md file.

**Generation rules:**
- Keep description to 50–150 characters
- Only declare confirmed dependencies in requires
- Organize body by "operational steps" — not prose paragraphs
- If the body exceeds 1,000 tokens, move detailed content to references/

## Step 4: Validate and Install

After generation, provide these verification steps:

```bash
# 1. View the generated file
cat ~/.openclaw/skills/<skill-name>/SKILL.md

# 2. Validate SKILL.md format
openclaw skill validate ~/.openclaw/skills/<skill-name>/

# 3. Test triggering
# In a new conversation, describe the Skill's trigger scenario
# and confirm it is correctly activated

Templates

For specific templates, see:

• Minimal Tool: {baseDir}/references/template-tool.md
• Informational: {baseDir}/references/template-info.md
• command-dispatch: {baseDir}/references/template-dispatch.md

---

## 20.9 Advanced Combination Case: Production-Grade Skill Design

### Case Study: Enterprise Kubernetes Deployment Skill

This case study demonstrates combining all advanced techniques from this chapter:

```yaml
---
name: k8s-deploy
description: |
  Use when the team needs to deploy services to a Kubernetes cluster:
  create or update Deployments, Services, and ConfigMaps; perform
  rolling updates; roll back failed deployments; view Pod status and
  logs. Only available in environments with configured kubectl access.
user-invocable: true
disable-model-invocation: false
metadata:
  openclaw:
    emoji: "☸️"
    os: linux
    requires:
      bins:
        - kubectl
        - helm
      anyBins:
        - kustomize
        - helmfile
      env:
        - KUBECONFIG
        - K8S_NAMESPACE
      config:
        - features.k8s.enabled
        - features.k8s.production_access
    primaryEnv: shell
    homepage: https://kubernetes.io/docs/
    install:
      - type: brew
        pkg: kubernetes-cli
      - type: go
        pkg: helm.sh/helm/v3@latest
---

# Kubernetes Deployment Skill

## Safety Prerequisites (Read Before Every Operation)

**Three principles for production operations:**
1. Validate in staging first; then promote to production
2. Always use rolling updates — never delete-and-recreate
3. Preserve rollback points (use revision history; `--record` is deprecated)

## Deploy a New Version

```bash
# Update image version (preserves history — recommended approach)
kubectl set image deployment/<name> \
  <container>=<image>:<tag> \
  -n ${K8S_NAMESPACE}

# Monitor rolling update progress
kubectl rollout status deployment/<name> -n ${K8S_NAMESPACE}

View Status

# List all Pods
kubectl get pods -n ${K8S_NAMESPACE} -o wide

# View specific Pod logs (last 100 lines, streaming)
kubectl logs <pod-name> -n ${K8S_NAMESPACE} --tail=100 -f

# View Pod events (diagnose CrashLoopBackOff)
kubectl describe pod <pod-name> -n ${K8S_NAMESPACE}

Rollback

# View Deployment revision history
kubectl rollout history deployment/<name> -n ${K8S_NAMESPACE}

# Roll back to the previous version
kubectl rollout undo deployment/<name> -n ${K8S_NAMESPACE}

# Roll back to a specific revision
kubectl rollout undo deployment/<name> \
  --to-revision=3 \
  -n ${K8S_NAMESPACE}

Helm Deployments

Detailed Helm values configuration guide: {baseDir}/references/helm-values-guide.md Chart template best practices: {baseDir}/references/helm-chart-patterns.md

**Advanced techniques used in this Skill:**
- `os: linux`: OS filtering (K8s typically runs in Linux environments)
- `requires.bins`: hard dependency on kubectl + helm
- `requires.anyBins`: soft dependency on kustomize or helmfile
- `requires.env`: gates on KUBECONFIG (should not load without it)
- `requires.config`: double gating (features.k8s.enabled + production_access)
- `{baseDir}/references/`: deep documentation via lazy-loading
- `install`: provides automatic installation paths

---

## 20.10 Chapter Summary and Quick-Reference Decision Table

### Technology Selection Quick-Decision Table

| Need | Technique | Field |
|------|-----------|-------|
| macOS only | OS filtering | `os: darwin` |
| All tools must exist | Hard dependency | `requires.bins` |
| Any one tool suffices | Soft dependency | `requires.anyBins` |
| Requires API key | Env var gating | `requires.env` |
| Requires feature flag | Config gating | `requires.config` |
| Command routes directly to tool | Zero-reasoning call | `command-dispatch: tool` |
| Completely hide Skill | Hide from model | `disable-model-invocation: true` |
| Always active globally (use sparingly) | Skip all gates | `always: true` |
| Reduce context footprint | Defer deep docs | `references/ + {baseDir}` |

### Core Principles of Advanced Skill Design

1. **Precise gating beats broad permission**: the more precisely you configure `requires`, the more reliable the Skill
2. **command-dispatch first**: any command whose behavior is deterministic should use command-dispatch
3. **references/ is a context buffer**: detailed content always goes in references/; the body retains only operational core
4. **always: true is a nuclear option**: only use it when global influence is genuinely required
5. **OS filtering protects user experience**: platform-specific tools must have OS filtering configured

**Congratulations!** You have completed all of the Skills chapters in the OpenClaw Complete Guide. From Chapter 16's ACP protocol to Chapter 20's advanced techniques, you now have the complete knowledge framework for designing and implementing enterprise-grade Skills ecosystems.

The next section covers OpenClaw's security model and deployment strategy — how to run OpenClaw safely in team and enterprise environments.