OpenClaw Skills System Explained: How SKILL.md Works

The OpenClaw skills system is what transforms OpenClaw from a capable chatbot into a true AI agent. Skills are pluggable capability modules that give your agent access to external services, APIs, and system capabilities. The SKILL.md format is the standard way skills declare their capabilities, permissions, and implementation. Here's how it all works.

What Is a Skill?

A skill is a directory containing:

• SKILL.md — the skill manifest (human-readable + machine-parseable metadata)
• main.py (or other entry point) — the actual implementation
• requirements.txt — Python dependencies
• Optionally: config.schema.json, tests, documentation

Skills live in ~/.openclaw/skills/ and are automatically discovered by OpenClaw on startup.

The SKILL.md Format

SKILL.md is a special Markdown file with YAML front-matter metadata:

---
name: web-search
version: 1.4.2
author: openclaw-team
description: Search the web using Brave Search API
permissions:
  - network_access
  - read_env:BRAVE_API_KEY
tools:
  - name: search_web
    description: Search the internet for current information
    parameters:
      query:
        type: string
        description: The search query
        required: true
      max_results:
        type: integer
        description: Maximum number of results to return
        default: 5
minimum_openclaw_version: "2.3.0"
---

# Web Search Skill

This skill enables your OpenClaw agent to search the internet using
the Brave Search API...

How OpenClaw Reads SKILL.md

When OpenClaw starts, it:

1. Scans ~/.openclaw/skills/ for skill directories
2. Parses each SKILL.md front-matter for metadata
3. Registers the skill's tools as callable functions for the LLM
4. Validates requested permissions against the tools.allow configuration
5. Loads the skill's Python module

The LLM then knows about all registered tools and can call them based on conversation context.

Permissions System

Skills declare what they need access to. OpenClaw validates these against your security config before activating a skill:

• network_access — can make outbound HTTP requests
• read_file — can read files from your filesystem
• write_file — can write files
• execute_command — can run shell commands (high risk — review carefully)
• read_env:VAR_NAME — can read specific environment variables

Skills requesting undeclared permissions are blocked automatically.

Installing Skills

# From ClawHub
python -m openclaw skill install web-search

# From a local directory
python -m openclaw skill install /path/to/skill

# From a GitHub URL
python -m openclaw skill install https://github.com/user/my-skill

Frequently Asked Questions

Can a skill call other skills?

Yes. Skills can invoke other installed skills through the OpenClaw internal API, enabling skill composition. A research skill might call web-search and then call a summarization skill.

How does the LLM know when to use a skill?

The LLM receives all tool definitions from installed skills in its system context. It decides when to call tools based on conversation context and its training to use tools when appropriate. Well-written description fields in SKILL.md are critical for the LLM to use tools correctly.

What's the difference between OpenClaw skills and n8n workflows?

Skills are tightly integrated with your OpenClaw agent's LLM — the agent decides when to use them contextually. n8n workflows are triggered by explicit events and execute linearly. Skills are more adaptive; n8n is more predictable for fixed pipelines.