Plain-English Guide
OpenClaw Skills: What They Are and How to Write Your First One
A skill is a folder, a text file, and a decision about how much to trust a stranger.
OpenClaw has its own skills system, separate from the skills in Claude and from Hermes Agent. This guide covers what a skill is, how to install one from the ClawHub registry, how to write a first one, and how to read a third-party skill before you let it run. Nightschool AI is independent of OpenClaw, and its name is used here only to describe the software.
An OpenClaw skill is a folder built around a SKILL.md file. The file has YAML frontmatter (a name and a short description) followed by plain-language instructions that guide the agent through a kind of task, such as a research workflow or a code-review checklist. You can write your own or install community skills from ClawHub, OpenClaw's public registry. Because a third-party skill is instructions and code from a stranger, read it before enabling it.
Published
Free lesson · no account neededMeet ClaudeWhy Claude?6 minStart the free lessonKey Takeaways
- A skill is a folder with a SKILL.md file: YAML frontmatter on top, instructions in the body. It guides how the agent handles a kind of task rather than performing the action itself.
- In OpenClaw's terminology a tool performs an action, a skill guides behavior, and a plugin packages tools, skills, configuration, or channels together.
- The folder name must match the name field in the frontmatter, using only lowercase letters, digits, and hyphens. Keep the description to one line under 160 characters.
- ClawHub is the official public registry of community skills. Install with openclaw skills install followed by the skill slug, and update with openclaw skills update --all.
- Treat every third-party skill as untrusted code and read it before enabling it. Run a gateway that handles real credentials or files on a dedicated machine, VM, or container.
Tool, skill, or plugin in OpenClaw
| Term | What it does | Example |
|---|---|---|
| Tool | Performs an action in the world. | A browser, a shell, file access, or an API call. |
| Skill | Guides the agent's behavior for a kind of task. It is instructions, not a new ability. | A research workflow, or a code-review checklist. |
| Plugin | Packages tools, skills, configuration, or channels together so they install as one unit. | A bundle that ships a tool, two skills, and the settings they need. |
Copy and Paste
Prompts You Can Use Today
Draft a first SKILL.md from a task you repeat
I want to write an OpenClaw skill called weekly-meeting-recap. It should take a folder of raw meeting notes and produce a recap with decisions, owners, and open questions. Draft a SKILL.md with YAML frontmatter containing a name and a one-line description under 160 characters, then a body with numbered steps, an output format, and a short list of things the agent must not do.
Swap the skill name and task for something you really repeat. Keep the name lowercase with hyphens so it matches your folder.
Tighten a description so the agent can find the skill
Here is the description field from my SKILL.md: 'This skill helps with various writing tasks and other things people might need.' Rewrite it as a single line under 160 characters that says exactly what the skill does and when to use it. Give me three versions and explain which one is easiest to find in a list of slash commands.
Paste your own description. A good one names the task and the trigger, not a general category.
Review a third-party skill before enabling it
I downloaded a skill from a public registry and have not enabled it. Below is the full text of its SKILL.md and every file in its folder. Act as a cautious reviewer. List anything that runs shell commands, reads or writes files outside its own folder, makes network requests, asks for credentials, or tells the agent to ignore earlier instructions. Quote each line you flag.
Paste every file, not just SKILL.md. Scripts bundled in the folder matter as much as the instructions.
Turn a skill into a plain-English summary of its risks
Summarize this OpenClaw skill for a non-technical teammate who must decide whether it is safe to enable. Say in plain language what it will do on their machine, which files or accounts it could touch, what could go wrong, and what you would want to see changed before approving it. Keep it under 200 words.
Useful when someone else owns the machine or the accounts the agent can reach.
Add a test plan to a skill you wrote
Below is a SKILL.md I wrote for OpenClaw. Write five test requests I can send the agent to check it behaves correctly: two normal cases, two edge cases such as missing or messy input, and one request the skill should politely decline. For each, state what a correct result looks like.
Run the five requests in a scratch workspace with no real credentials before you rely on the skill.
Split a long skill into something maintainable
My SKILL.md has grown to about 400 lines and mixes a research workflow, a formatting guide, and some one-off notes. Suggest how to restructure it into one focused skill, or several. For each, propose a lowercase-hyphen name, a one-line description under 160 characters, and the sections that belong in its body.
One skill per kind of task is easier to discover, review, and update.
The Anatomy
What is inside an OpenClaw skill
A skill is deliberately small. Once you know the pieces, any skill you meet will be readable in a few minutes.
A folder
Each skill lives in its own folder. The folder name is not decoration: it must match the name in the SKILL.md frontmatter.
A SKILL.md file
The file at the center of the folder. It has YAML frontmatter at the top and instructions in plain language below.
YAML frontmatter
A short block of metadata, including the name and the description. The description is what the agent sees and what slash-command discovery uses.
Instructions in the body
The steps, rules, and output format you want the agent to follow. Think of it as a briefing for a capable colleague who has never done this task for you.
Discoverability
A skill nobody can find does not get used. A clear one-line description is the difference between a skill that fires and one that sits idle.
Vocabulary
Tools, skills, and plugins are three different things
Most confusion about OpenClaw skills comes from mixing up three words. One widely cited explanation of OpenClaw's terminology says a tool performs an action, a skill guides the agent's behavior for a kind of task, and a plugin packages tools, skills, configuration, or channels together. The table above lays them side by side.
The practical consequence is that a skill cannot give the agent a power it does not already have. If a skill tells the agent to run a script, the shell tool still has to be available to do it. A skill shapes how the agent uses what it has: which steps to take first, what to check, how to format the result, and when to stop and ask you.
That is also why skills are easy to write. You are not programming a new capability. You are writing down a procedure you already know, in the same kind of language you would use in a handover note. The skill makes that note reusable, so the agent follows it the same way every time.
It is also why skills deserve scrutiny when they come from someone else. A skill can instruct the agent to use the tools it has in ways you did not intend. A short block of text can steer a shell or a file system, which is the heart of the safety discussion later in this guide.
Not To Be Confused
OpenClaw skills are their own system
Several AI products now use the word skill, and they do not share a format or a folder. OpenClaw has its own skills system. It is distinct from the skills feature in Claude, and distinct from the skills in Hermes Agent. A skill written for one will not simply drop into another, even where the file names look familiar.
If you searched for this topic after reading about skills elsewhere, keep your mental models separate. The rules in this guide, such as the folder name matching the frontmatter name and the ClawHub registry, describe OpenClaw. Anything you have learned about another product's skills may rhyme with it, but treat it as a different system until you have read OpenClaw's own documentation.
Nightschool AI is an independent learning platform. It is not affiliated with OpenClaw, and nothing here implies endorsement by or of any product named. Product names appear only so you can tell which software a statement is about.
On Disk
Where OpenClaw looks for skills
OpenClaw watches a skills root directory on disk for SKILL.md files. When you add a folder containing a valid SKILL.md under that root, the agent can pick it up. One commonly cited per-workspace layout is a path such as ~/.openclaw/workspace/skills/<skill-name>/SKILL.md, where <skill-name> is the folder you created.
Guides describe the exact default location a little differently, and this page was written from secondary descriptions of the official documentation rather than a direct read of docs.openclaw.ai. Before you rely on any path, flag, or wording in this guide, confirm it against the live docs, since they may have changed.
The one-folder-per-skill layout has a useful side effect. Because everything a skill needs sits in one place, you can read it in full, copy it, put it under version control, or delete it by removing a single directory. That is a real advantage when you are deciding whether to trust something.
Installing
Installing a skill from ClawHub
ClawHub, hosted at github.com/openclaw/clawhub, is described as OpenClaw's official public registry of community-built skills. Think of it as a shared shelf: other people have written skills for common workflows and published them so you do not have to start from nothing. The registry changes often, and sources disagree on how many skills it holds, so this guide gives no count.
The install command takes the form openclaw skills install followed by the skill slug, for example openclaw skills install some-skill-slug. To bring everything you have installed up to date, the reported command is openclaw skills update --all. If you run that, remember that an update changes the text and files the agent will follow, so an update is a fresh thing to read, not a formality.
A sensible habit is to separate finding from enabling. Browse the registry, pick a skill that fits a task you really have, and read its SKILL.md and any other files in its folder. Only after that do you enable it, ideally first in a scratch workspace that holds no real credentials. Installing is easy by design, and that ease is exactly why the reading step needs to be deliberate.
Hands On
Writing your first skill, step by step
Start by choosing a task you already do the same way each time. Good first candidates are small and checkable: turning meeting notes into a recap, reviewing a pull request against your team's checklist, or summarizing a research topic into a fixed template. Avoid anything that needs broad access to your accounts for your first attempt.
Next, name it. Pick a name using only lowercase letters, digits, and hyphens, such as weekly-meeting-recap. Create a folder with exactly that name under your skills root, then create a SKILL.md inside it. The folder name must match the name field in the frontmatter, so a mismatch here is the first thing to check if your skill does not appear.
Then write the frontmatter. It needs the name and a description. The description is shown to the agent and used for slash-command discovery, and reported guidance says to keep it on one line and under 160 characters. A workable example is: Summarize a folder of meeting notes into decisions, owners, and open questions. Say what the skill does and when to reach for it, in that one line.
Now write the body as instructions to a smart colleague. State the goal in a sentence, list the steps in order, describe the output format exactly, and add a short list of things the agent should not do, such as inventing owners who were not named in the notes. Include what to do when input is missing or unclear, because that is where first versions usually fail.
Finally, test it with real requests in a scratch workspace. Try a normal case, a messy case, and a request the skill should decline. Change one thing at a time, re-run, and keep the version that behaves best. Expect to edit the description more than once; it is the part that decides whether the skill is chosen at all.
Craft
Habits that make a skill good
These are not OpenClaw rules. They are practical habits that apply to any written procedure an agent will follow.
One skill, one kind of task
A skill that tries to cover research, formatting, and email tone is hard to find and hard to review. Split it, and give each piece a sharp description.
Say the output format
Name the headings, the order, and the length you want. Vague outputs come from vague instructions, not from a weak agent.
Write down what not to do
A short list of prohibitions, such as never guessing a name or never touching files outside the task folder, prevents the most common surprises.
Test with awkward input
Empty files, contradictory notes, and out-of-scope requests reveal gaps that a clean example never will.
Review it again later
A skill that worked last month can drift as your tools and habits change. Reread it when the task changes, and trim anything the agent no longer needs.
Safety
A third-party skill is code and prompts from a stranger
A skill from a registry is not a neutral download. It is a set of instructions, and sometimes bundled scripts, written by someone you do not know, that your agent will follow with whatever access it has. Independent sources describing OpenClaw's own documentation report that it says, close to verbatim, to treat third-party skills as untrusted code and to read them before enabling them. That is the right posture, and it holds whether or not the wording is exact.
What can go wrong is concrete. A skill can tell the agent to run shell commands you did not expect, to read files outside the task, to send data to a remote address, or to ask you for credentials under a plausible pretext. Instructions can also be written to override your own, for example by telling the agent to ignore earlier rules. None of this requires sophisticated code; a few ordinary sentences are enough.
The same sources report separate advice for people who run an OpenClaw gateway that handles real credentials or file access: run it on a dedicated machine, VM, or container rather than on a personal device. The reasoning is containment. If a skill misbehaves, the damage is limited to an environment that holds nothing you cannot afford to lose.
None of this is a reason to avoid community skills. It is a reason to treat installation as the start of a review rather than the end of a task. A calm, repeatable reading routine costs a few minutes and removes most of the risk that makes people nervous about registries.
Before You Enable
A reading checklist for any skill you did not write
Work through these in order. If any answer is unclear, leave the skill disabled.
Read every file
Open SKILL.md and everything else in the folder. Scripts and extra files can do things the main file never mentions.
Look for commands
Search for shell commands, installs, downloads, and anything that pipes remote content into a program. Each one needs a reason you understand.
Check what it touches
Note which files, folders, accounts, and network addresses the skill reaches for, and whether the task truly needs them.
Check the source
Look at who published it, how long it has existed, and whether others have read and discussed it. A thin history is not proof of harm, but it is a reason to read harder.
Try it in isolation
First run it in a scratch workspace, ideally on a dedicated machine, VM, or container, with no real credentials in reach.
Re-read after updates
After running openclaw skills update --all, treat changed skills as new. An update can change what the agent is told to do.
Choosing
Write your own, or install one: which should you pick
If the task is specific to you, such as your team's review checklist or your own note format, write it yourself. You know the details, you will trust the result, and a first skill is the best way to learn how the format behaves. A skill you wrote and tested is also the easiest to review, because you already know everything in it.
If the task is common and well understood, such as a standard research workflow, start by reading what exists on ClawHub. Even if you do not install anything, a well-made community skill is a good model for structure and phrasing. If you do install one, follow the reading checklist and test in isolation before it touches anything real.
If you are new to agents in general, build your intuition first on something low-stakes. Write one small skill with no special access, run it on harmless input, and watch how closely the agent follows the text. That experience will make you a sharper reviewer of other people's skills, which is the skill that matters most.
Learn to write instructions an AI can actually follow
Reading about skills and writing good ones are different things. A clear SKILL.md depends on the same habits as any strong prompt: context, constraints, and a stated output format. The free Nightschool AI curriculum is hands-on from the first lesson, so you practice those habits instead of just reading about them.
Frequently Asked Questions
What is an OpenClaw skill?
An OpenClaw skill is a folder built around a SKILL.md file. The file starts with YAML frontmatter, including a name and a short description, and continues with plain-language instructions that guide the agent through a kind of task, such as a research workflow or a code-review checklist. A skill shapes how the agent behaves; it does not add a new capability by itself.
What is the difference between a tool, a skill, and a plugin in OpenClaw?
One widely cited explanation of OpenClaw's terminology says a tool performs an action, such as a browser, shell, file access, or an API call. A skill guides the agent's behavior for a kind of task. A plugin packages tools, skills, configuration, or channels together. In short: tools act, skills instruct, and plugins bundle.
Are OpenClaw skills the same as Claude skills or Hermes Agent skills?
No. OpenClaw has its own skills system, distinct from the skills feature in Claude and from the skills in Hermes Agent. Each product defines its own format, folders, and rules, so a skill written for one should not be assumed to work in another. Read the documentation for the product you are using.
How do I install a skill from ClawHub?
ClawHub, hosted at github.com/openclaw/clawhub, is described as OpenClaw's official public registry of community skills. Reported documentation gives the install command as openclaw skills install followed by the skill's slug, and the update command as openclaw skills update --all. Read the skill's files before you enable it, and test it somewhere that holds no real credentials.
How do I write my first OpenClaw skill?
Pick a task you repeat. Create a folder named with lowercase letters, digits, and hyphens, and put a SKILL.md inside. In the frontmatter, set name to match the folder and write a one-line description under 160 characters. In the body, state the goal, numbered steps, the output format, and what the agent should not do. Then test it with normal and awkward requests.
What are the naming rules for a skill?
As reported from the official docs, the skill's folder name must match the name field in its SKILL.md frontmatter, and that name should use only lowercase letters, digits, and hyphens. So a skill called weekly-meeting-recap lives in a folder of that exact name. If a skill does not show up, a mismatch between folder and name is the first thing to check.
How long should the description be?
Reported guidance recommends keeping the description on one line and under 160 characters. The description is shown to the agent and used for slash-command discovery, so it works as the skill's label. Say what the skill does and when to use it, for example: Summarize meeting notes into decisions, owners, and open questions.
Where do OpenClaw skills live on disk?
OpenClaw watches a skills root directory for SKILL.md files. One commonly cited per-workspace layout is ~/.openclaw/workspace/skills/<skill-name>/SKILL.md. Guides describe the default path slightly differently, so confirm yours in the official documentation at docs.openclaw.ai before you create folders.
Are third-party OpenClaw skills safe?
Treat them as untrusted until you have read them. A third-party skill is instructions, and possibly scripts, written by a stranger that your agent will follow with its access. Sources describing OpenClaw's documentation report that it advises treating third-party skills as untrusted code and reading them before enabling. Check every file, look for commands and network calls, and test in isolation.
Where should I run OpenClaw if it handles real credentials?
Sources describing OpenClaw's documentation advise that a gateway handling real credentials or file access should run on a dedicated machine, VM, or container rather than a personal device. The point is containment: if a skill or an instruction misbehaves, the damage stays inside an environment that holds nothing you cannot afford to lose.
How many skills are on ClawHub?
Sources differ on the current number, and the registry changes constantly, so this page does not give a figure. For an accurate view, browse the registry at github.com/openclaw/clawhub. The more useful question than the count is whether a particular skill does what you need and passes your own reading of it.
Do I need to be a programmer to write a skill?
Not for a basic one. A skill is a text file with a short metadata block and written instructions, so the main requirement is the ability to describe a procedure clearly. Programming helps if you bundle scripts, but a first skill can be pure instructions. Clear writing, an explicit output format, and careful testing matter most.
Ready to write instructions that work?
Good skills start with good prompts, and good prompts are learned by doing.