OpenClaw Skills: Teaching Your AI Agent New Abilities
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 onPATH -
anyBins— at least one must exist onPATH -
env— env variable must be set (or provided via config) -
config— a key inopenclaw.jsonmust 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:
{
"skills": {
"entries": {
"openai-image-gen": {
"enabled": true,
"apiKey": { "source": "env", "provider": "default", "id": "OPENAI_API_KEY" }
},
"my-custom-skill": {
"enabled": true,
"env": {
"MY_TOOL_API_KEY": "sk-..."
},
"config": {
"endpoint": "https://api.myservice.com",
"model": "fast"
}
}
}
}
}
Key rules:
-
enabled: falsedisables a skill even if it’s bundled and eligible -
envvalues are injected only if the variable isn’t already in the environment -
apiKeyis a shorthand for the skill’s primary API key — supports plaintext or aSecretRefobject - 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.extraDirsinopenclaw.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?
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
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.mdin<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.
Originally published at openclawplaybook.ai. Get The OpenClaw Playbook — $9.99