OpenClaw skills are how you stop teaching the same workflow to an agent over and over. A skill is a named instruction package: a `SKILL.md` file with frontmatter, a clear trigger description, and the steps the agent should follow when that job comes up.
That sounds small. It is not. Once your agent has tools, files, credentials, browser access, or publishing rights, “just paste the checklist again” becomes a messy way to run operations. Skills give repeatable work a home. The agent can discover the skill, load the full instructions only when needed, and follow the same recipe next time.
The main mistake is treating skills as a dumping ground for every preference you have. A good skill is narrower than memory and more procedural than a note in `AGENTS.md`. It says: when this kind of task appears, do this work, in this order, with these checks.
What OpenClaw skills are
The official docs define skills as markdown instruction files that teach the agent how and when to use tools. Each skill lives in a directory with a `SKILL.md` file. That file has YAML frontmatter at the top and markdown instructions below it.
At minimum, an OpenClaw skill needs two frontmatter fields:
---
name: report-review
description: Review a weekly report draft for missing numbers, broken links, and unclear action items.
---
# Report review
When the user asks you to review a weekly report, check the draft for:
- missing source links
- unexplained numbers
- stale dates
- unclear owners
Return the highest-risk issues first.The `name` is the stable command name. The `description` is not filler copy. It is the matching surface the agent sees before it decides whether to load the full skill. If the description is vague, the skill will trigger at the wrong time or not trigger when you need it.
OpenClaw can also expose skills as slash commands. Some skills are user-invocable. Some can be hidden from model-initiated use with `disable-model-invocation`. Some can dispatch straight to a tool. Most should stay simple: one `SKILL.md`, one job, clear steps.
Why OpenClaw skills are not just longer prompts
A long prompt is disposable. A skill is part of the agent’s working environment.
That distinction matters because skills use progressive disclosure. The agent starts with the list of available skill names and descriptions. It reads the full `SKILL.md` only when the task matches. Codex and ChatGPT skills use the same basic idea: keep the cheap discovery layer small, then load the full procedure only when needed.
This is exactly what you want for serious agent work. A deployment checklist, a blog publishing pipeline, a security review recipe, or a browser automation routine can be too long to paste into every session. As a skill, it costs little until the task needs it.
There is a catch. Progressive disclosure makes the description more important, not less. Write descriptions like routing rules, not marketing blurbs.
Bad:
description: Helps with reports.
Better:
description: Review weekly status report drafts for missing metrics, stale dates, unclear owners, and unsupported claims.The second version gives the agent enough signal to choose correctly. The first one forces a guess.
How the openclaw skills command fits
The `openclaw skills` CLI is the operator surface for finding, installing, checking, and maintaining skills. The docs list commands for search, install, update, verify, list, info, check, curator status, and Skill Workshop proposal flows.
In practice, the common loop looks like this:
openclaw skills list
openclaw skills info report-review
openclaw skills check
openclaw skills search "calendar"
openclaw skills install @owner/calendar-helper
openclaw skills verify @owner/calendar-helper
openclaw skills update --all`list` tells you what the current agent can see. `info` shows details for one skill. `check` is useful when a skill should exist but does not load because a binary, environment variable, config value, or allowlist is missing. Search, install, verify, and update connect the local workspace to ClawHub and other install sources.
This matters most when a team has more than one agent. A skill installed somewhere on disk is not automatically visible to every agent. Workspace paths, managed paths, extra directories, bundled skills, and per-agent allowlists all affect the final snapshot.
Where OpenClaw loads skills from
OpenClaw has a defined loading order. Highest precedence wins when the same skill name appears in more than one place. Workspace skills come first, then project agent skills, personal agent skills, managed or local skills, bundled and custodian skills, and finally extra directories plus plugin skills.
That order is not trivia. It decides which version of a skill the agent actually sees.
Say a bundled skill and a workspace skill share the same name. The workspace version wins. That is useful when you want a house-style override, but it can also confuse you if an older local copy quietly shadows a newer shared skill. When behavior looks wrong, check the skill source before editing the wrong file.
OpenClaw also supports grouped layouts. A `SKILL.md` can live several levels deep under a configured root. The folder path is for organization. The skill name comes from frontmatter, not from the parent folder.
<workspace>/skills/research/serp-gap/SKILL.md
<workspace>/skills/publishing/wordpress-draft/SKILL.mdThat makes large skill collections easier to browse without changing the command names users invoke.
How to create your first OpenClaw skill
Start with a task you already repeat. Do not start with an abstract “AI assistant improvement” idea. Pick something boring enough that you know whether it worked.
A good first skill might be:
- Review a WordPress draft before publishing.
- Run a local app and capture a screenshot.
- Prepare a release note from a git diff.
- Turn meeting notes into a dated action log.
- Check a server after a deploy.
The creating-skills docs show the basic workflow: create a directory under the workspace `skills/` folder, write `SKILL.md`, run `openclaw skills list`, then test the behavior with a real agent message.
~/.openclaw/workspace/skills/draft-review/
SKILL.mdKeep the instruction body direct. Tell the agent what inputs to gather, what steps to run, what to verify, and what output to return. Avoid personality instructions. The agent already has its persona. The skill should carry the procedure.
Use Skill Workshop for agent-drafted skills
Skill Workshop is the governed path for creating or updating workspace skills. This is one of the best parts of OpenClaw’s model because it refuses to pretend durable instructions are casual edits.
The Workshop flow is proposal first. Generated content is stored as `PROPOSAL.md`, not `SKILL.md`. Create, update, and revise actions do not change the live skill. Apply is the only live write, and apply reruns the security scanner before writing.
That design is the right default for self-hosted agents. If an agent notices a reusable workflow, it can propose a skill. You can inspect it, evaluate it, revise it, reject it, quarantine it, or apply it. The live skill collection changes only when the proposal is accepted.
Use Workshop when the agent is helping author the skill. Write by hand only when you already know exactly what should go into the file and you are comfortable owning the change directly.
Install, verify, and update skills with care
OpenClaw can install skills from ClawHub, Git, local directories, and resolved external listings. ClawHub is the public registry, and the standalone `clawhub` CLI handles search, inspect, install, uninstall, list, pin, update, publish, sync, scan, and scan-report downloads.
For operators, the key habit is simple: inspect before trust.
A skill can be “just instructions”, but instructions can still tell an agent to run tools, touch files, call APIs, or move data. If the skill includes scripts, the risk goes up. If it expects credentials, the risk goes up again.
OpenClaw gives you some guardrails. Skill installs and updates can pass through install policy. ClawHub exposes verification and scan state. Skills can be pinned so an update does not overwrite known-good local bytes. Those controls are there because reusable automation becomes part of your operating surface.
Do not install random skills into the same agent that holds production credentials. If you need to test one, use a limited agent, a throwaway workspace, and a narrow set of tools.
Skill visibility is not real authorization
This is the section people are most likely to skip, and it is the one that prevents expensive mistakes.
OpenClaw agent allowlists decide which skills an agent can see. They affect prompt building, slash-command discovery, sandbox sync, and skill snapshots. The docs are blunt about the limit: allowlists are not a host shell authorization boundary.
If an agent can run `exec` on a host account that can read a file, the fact that a skill is hidden does not magically protect that file. Skill visibility is a discovery and prompt-control layer. Real authorization still comes from sandboxing, OS user boundaries, tool allowlists or denylists, and scoped credentials.
Use both layers. Let allowlists keep the agent focused. Let sandboxing and account isolation enforce the line.
When not to use a skill
Not every durable note deserves a skill.
Use `MEMORY.md` for preferences and facts the agent should remember: tone, past decisions, recurring people, project context. Use `AGENTS.md` for core operating rules the agent must always see. Use standing orders for authority: what the agent owns, what it may do, and when it must ask. Use hooks for event reactions. Use cron or automation for schedules.
Use a skill when the repeatable part is procedural. The test is easy: if you can name a start condition, input, steps, checks, and output, a skill probably fits.
If all you have is “remember that I prefer shorter introductions”, that is memory. If you have “when drafting a docs blog post, run this research protocol, write this HTML structure, score it with humanizer, upload media, publish draft-only, and report these fields”, that is a skill or standing workflow.
A practical checklist for OpenClaw skills
Before you call a skill finished, run through this checklist:
- The `name` is lowercase, stable, and specific.
- The `description` says exactly when the skill should trigger.
- The body names required inputs.
- The steps are ordered and testable.
- The output format is clear.
- Risky actions have approval or escalation rules.
- Any required binaries, environment variables, or config values are gated.
- The skill has been tested from a fresh session.
- `openclaw skills check` does not show missing dependencies.
- The skill is not doing authorization work that belongs in sandboxing or credentials.
This sounds strict because skills are sticky. A bad one does not fail once. It keeps teaching the same bad habit until someone notices.
FAQ about OpenClaw skills
What is an OpenClaw skill?
An OpenClaw skill is a directory with a `SKILL.md` file that teaches an agent a repeatable workflow. The file has YAML frontmatter for name and description, then markdown instructions for the actual procedure.
Where do OpenClaw skills live?
They can live in workspace, project-agent, personal-agent, managed, bundled, extra, or plugin skill roots. OpenClaw applies a precedence order when the same skill name appears in more than one place.
How do I see which skills are available?
Run `openclaw skills list` from the relevant workspace. Use `openclaw skills info <name>` for one skill and `openclaw skills check` when a skill is missing or failing eligibility checks.
Should I use Skill Workshop or edit SKILL.md directly?
Use Skill Workshop when an agent drafts or updates a skill. It creates a proposal first and writes the live skill only when applied. Direct edits are fine for hand-authored changes you are ready to own.
Are skills safe to install from the internet?
Treat third-party skills as untrusted until inspected. Verify them, read the instructions, check any scripts, and test them with limited credentials before using them in a real agent workspace.
Can skill allowlists replace sandboxing?
No. Allowlists control which skills an agent sees. They do not stop a host shell from reading files or running commands available to that operating-system user. Use sandboxing and scoped credentials for enforcement.
Start with the workflow you already repeat
The best OpenClaw skill is not clever. It is boring, named, and reliable.
Pick one workflow you keep explaining to your agent. Turn it into a small `SKILL.md` with a sharp description, explicit inputs, ordered steps, and a verification section. Test it from a fresh session. Then, when it works, let it replace the pasted checklist.
That is where skills earn their keep: not by making the agent more magical, but by making its useful habits repeatable.
