OpenClaw Skills: Teaching Your AI Agent New Abilities

Hex · March 7, 2026 · 8 min read

Your AI agent is only as capable as the tools it knows about. Out of the box, OpenClaw gives you a solid foundation — file operations, web search, browser control, messaging. But the real power comes from Skills: modular packages that teach your agent entirely new abilities.

Want your agent to post to X (Twitter)? Generate images via DALL-E? Transcribe audio? Manage GitHub issues? There's a skill for that. And if there isn't, you can build one in an afternoon.

This guide covers how Skills work, how to install them, how to configure them, and how to create your own.

What Is a Skill?

A Skill is a directory containing a single SKILL.md file. That file has two parts:

YAML frontmatter — metadata: name, description, gating rules (what binaries or API keys are required)
Instructions — the actual text injected into the agent's system prompt, describing how to use the tool

When OpenClaw loads, it scans for eligible skills, filters them based on your environment and config, and injects the relevant instructions into the agent's context. From that point on, your agent knows how to use that tool — no code changes, no restarts (for new sessions).

Skills follow the AgentSkills spec, which means they're portable across compatible agent runtimes. A skill built for OpenClaw can also work with other Pi-compatible agents.

Where Skills Live

OpenClaw looks for skills in three places, in order of precedence:

Workspace skills — <workspace>/skills/ (your agent's workspace folder)
Managed/local skills — ~/.openclaw/skills/
Bundled skills — shipped with OpenClaw itself

If the same skill name appears in multiple locations, the higher-precedence copy wins. This means you can override a bundled skill by placing a modified version in your workspace — without touching the install.

In multi-agent setups, workspace skills are agent-specific (each agent has its own workspace), while ~/.openclaw/skills/ is shared across all agents on that machine.

Finding and Installing Skills from ClawHub

ClawHub is the public registry for OpenClaw skills. Browse it to discover what the community has built.

Installing a skill is one command:

# Install a skill into your workspace
clawhub install <skill-slug>

# Update all installed skills
clawhub update --all

# Sync (scan local skills + publish updates)
clawhub sync --all

By default, clawhub install drops the skill into ./skills/ under your current working directory (falling back to your configured workspace). OpenClaw picks it up as a workspace skill on the next new session.

Treat third-party skills as untrusted code. Read the SKILL.md before enabling — it gets injected into your agent's system prompt, and malicious instructions could influence behavior. Prefer sandboxed runs for skills that touch sensitive data.

Skill Gating: What Gets Loaded and When

Not every skill is eligible on every machine. OpenClaw uses gating rules in the skill's frontmatter to decide what loads:

---
name: openai-image-gen
description: Batch-generate images via OpenAI Images API.
metadata: {"openclaw": {"requires": {"bins": ["node"], "env": ["OPENAI_API_KEY"]}}}
---

Gating options in metadata.openclaw.requires:

bins — all listed binaries must exist on PATH
anyBins — at least one must exist on PATH
env — env variable must be set (or provided via config)
config — a key in openclaw.json must be truthy (e.g. browser.enabled)

Other useful flags:

always: true — skip all other gates and always include this skill
os — limit to specific platforms (darwin, linux, win32)
primaryEnv — the main API key this skill needs (used for config UI)

If a skill's requirements aren't met, it silently drops out of the eligible set. Your agent won't see broken skill instructions — it just won't have that skill available.

Configuring Skills

Some skills need API keys or custom config. Set these in ~/.openclaw/openclaw.json under skills.entries:

Key rules:

enabled: false disables a skill even if it's bundled and eligible
env values are injected only if the variable isn't already in the environment
apiKey is a shorthand for the skill's primary API key — supports plaintext or a SecretRef object
Skill names with hyphens must be quoted in JSON5

If you only want specific bundled skills to load, use skills.allowBundled as an allowlist. Workspace and managed skills are unaffected.

Per-Agent vs Shared Skills

When running multiple agents on one machine, skills placement determines scope:

Per-agent skills → <workspace>/skills/ — only that agent sees them
Shared skills → ~/.openclaw/skills/ — all agents on the machine see them
Extra shared folders → configure via skills.load.extraDirs in openclaw.json

This matters when you have a general-purpose agent and a specialized one. Your X-posting skill might live in the marketing agent's workspace only — your DevOps agent doesn't need to know about it.

How to Write Your Own Skill

Creating a skill is simpler than it sounds. You need one file:

skills/
  my-weather-skill/
    SKILL.md

A minimal SKILL.md:

---
name: my-weather-skill
description: Get current weather via wttr.in API. Use when the user asks about weather or temperature.
---

## my-weather-skill

To get weather for a location, run:

  curl -s "https://wttr.in/LOCATION?format=3"

Replace LOCATION with a city name or coordinates. Returns a one-line weather summary. Use the exec tool to run this command.

Drop this in <workspace>/skills/my-weather-skill/SKILL.md and start a new session. Your agent will now know how to fetch weather on request.

Advanced: Gating and Environment Injection

If your skill needs an API key or a specific binary, add gating metadata:

---
name: my-api-skill
description: Interact with MyService API for data lookups.
metadata: {"openclaw": {"requires": {"env": ["MY_API_KEY"]}, "primaryEnv": "MY_API_KEY"}}
---

## my-api-skill

You have access to the MyService API via the MY_API_KEY environment variable.

To query data:
  curl -H "Authorization: Bearer $MY_API_KEY" https://api.myservice.com/data

OpenClaw will only load this skill if MY_API_KEY is set — either in the environment or via skills.entries.my-api-skill.apiKey in your config.

Referencing the Skill Directory

Use {baseDir} in your skill instructions to reference the skill folder path. This is useful when your skill includes scripts or assets alongside SKILL.md:

Run the helper script at {baseDir}/run.sh to process files.

Skills vs Plugins: What's the Difference?

You might wonder when to use a skill vs a plugin. Here's the distinction:

Skills are pure instructions — text injected into the system prompt. They teach the agent how to use existing tools (CLI commands, APIs via curl, shell scripts). No code executes at load time. Zero runtime overhead.

Plugins are code modules that run alongside the Gateway. They can register new tools as first-class agent functions, add CLI commands, start background services, and hook into the Gateway's RPC layer. Plugins can also ship skills — a plugin might register a new tool and include a skill that teaches the agent how to invoke it.

Rule of thumb: start with a skill. If the skill needs to do something a shell command can't handle (complex auth flows, streaming APIs, event-driven behavior), graduate to a plugin.

Token Impact and Performance

Skills inject text into your system prompt. The overhead is deterministic:

Base overhead (when ≥1 skill is loaded): ~195 characters
Per skill: ~97 characters + the length of name + description + location

OpenClaw snapshots eligible skills when a session starts and reuses that list for subsequent turns. Changes to skills (adding, modifying, removing) take effect on the next new session. The skills watcher can hot-reload the snapshot mid-session when SKILL.md files change — configure this under skills.load.watch.

Keep skill descriptions concise. The description field is what triggers skill selection (the agent reads it to decide whether a skill applies). Clear, specific descriptions reduce noise in the system prompt and improve accuracy.

Real-World Examples: Skills in Action

Here's how skills power a real agent setup:

X (Twitter) Posting Agent

The xurl skill teaches the agent how to use the xurl CLI for authenticated X API calls. Install it, configure your API keys, and your agent can draft and post tweets, reply to mentions, and search threads — all from a Slack DM.

GitHub Issue Automation

The gh-issues skill pairs with the gh CLI to let your agent fetch open issues, spawn sub-agents to fix bugs, and open PRs — automatically, on a schedule.

Content Pipeline

Skills can chain: a web_search skill feeds research into an openai-image-gen skill to generate cover art, then a custom Slack-posting skill delivers the finished post. Each skill handles one step; the agent orchestrates the flow.

Getting Started

If you're new to OpenClaw, start with the complete OpenClaw overview. Once your agent is running:

Browse ClawHub for skills relevant to your workflow
Install one with clawhub install <slug>
Add any required API keys to your config
Start a new session — the agent now has the ability
For custom tools, create a SKILL.md in <workspace>/skills/<name>/

The right skill stack turns your agent from a smart chatbot into a fully operational team member — one that knows how to use your tools, respects your environment, and picks up new abilities as your needs evolve.

Want the complete guide? Get The OpenClaw Playbook — $9.99