OpenClaw skills, how to build your first one tonight

OpenClaw skills are plain markdown files that tell the OpenClaw assistant how and when to do a job, and each skill is a folder holding one file called SKILL.md with 2 required lines at the top, a name and a description. You install one from the ClawHub registry with a single command, or you write your own tonight in about 20 minutes, because the file is ordinary English and the assistant will write it for you if you ask it the right way.

This walks through all of it starting from a machine with nothing installed on it, and every command below comes from the official OpenClaw documentation rather than from memory. OpenClaw is the assistant that reads those skill files, started by Peter Steinberger in November 2025, and the skills idea is the reason people keep asking what one actually is. By the end you'll have installed the assistant, installed somebody else's skill from the public registry, and written one of your own that does a small job you care about.

What are OpenClaw skills, and what do they actually do?

An OpenClaw skill is a markdown instruction file that teaches the assistant how and when to use a tool, and the documentation puts it in one line, each skill lives in a directory containing a SKILL.md file with YAML frontmatter and a markdown body. The frontmatter is the label on the tin and the body is the instruction sheet inside it.

What matters for a beginner is how the assistant reads them. It doesn't load every skill you own into the conversation. At the start it sees only the name and description of each one, and the documentation gives the cost of that listing, about 24 tokens for each skill you have installed, which is the name, the description and where it lives. The assistant reads the body only when it decides your request matches. So a dozen installed skills cost you almost nothing until one of them is needed.

That design has a consequence worth hearing before you write anything. The description isn't decoration, it is the only thing the assistant sees when it decides whether your skill applies, so it has to say when to use the skill and not merely what the skill is. The documentation asks for one line under 160 characters. A description reading "reads my notes file and returns a short brief when I ask for my brief" will fire. A description reading "productivity helper" will sit there unused forever.

Where you put the folder decides who can see it. OpenClaw looks in several places in a fixed order, starting with a skills folder inside your workspace, then a hidden agents folder in the same workspace, then the same thing in your home directory, then a managed folder, and finally the skills that shipped with the install. It searches several levels deep under each of those roots and picks up anything named SKILL.md. If you have never used a system like this, the closest thing is the way Claude Skills work, and the shapes are similar enough that learning one helps with the other.

What do you need before you start, and what does OpenClaw cost to run?

You need a computer running macOS, Linux or Windows, a recent Node.js, and one model provider, and the cheapest working setup costs nothing because OpenClaw can talk to a model running on your own machine. The assistant itself is free to install and so are the skills.

• A computer that stays on, so any Mac, Linux box or Windows PC, and no graphics card is needed
• A recent Node.js, which the installer downloads for you when yours is missing or too old
• One model provider, either a local model through Ollama, a Gemini credential on the free tier, or a Claude or ChatGPT subscription you already pay for
• About 45 minutes in total, and writing the first skill takes most of that

The cost question deserves a straight answer, because it is where most tutorials go vague. OpenClaw is free and its skills are free. What costs money is the model doing the thinking, and there are 3 honest options. Running a model on your own machine through Ollama costs nothing beyond electricity, and the onboarding wizard has an Ollama choice with a local only mode. Google's pricing page lists a free tier on the Gemini API, so a small setup can sit on that tier. If you already pay for ChatGPT, OpenClaw signs you in through a browser flow rather than asking for a credential, and if you already run Claude Code on the same machine, OpenClaw can reuse that login and draw on the same subscription limits.

The local route is slower and less capable than a hosted model, which is the tradeoff and worth knowing before you pick. If you want to know which local model to pull first, we ranked them by how much memory your machine has in the best local LLM for coding. If you would rather pay per token and skip the download entirely, the current numbers across providers sit in our LLM API pricing comparison.

How do you install OpenClaw on a Mac or a Windows machine?

You install OpenClaw with one line pasted into a terminal, and the installer detects your system, installs Node.js if it is missing, installs OpenClaw and starts the onboarding wizard. On a Mac you open the application called Terminal, which lives in Applications and then Utilities, and on Windows you open PowerShell from the start menu.

This is the line, copied from the install page of the documentation. Paste it, press return, and leave it alone for a few minutes.

curl -fsSL https://openclaw.ai/install.sh | bash

You should see it name your operating system, install Node.js if you don't already have it, install OpenClaw itself, and finish by starting onboarding. It provisions a current Node.js for you when yours is missing or too old, so that is one fewer thing to arrange. Windows has its own line for PowerShell, and it does the same 4 things.

iwr -useb https://openclaw.ai/install.ps1 | iex

When the installer finishes, onboarding opens by itself and asks you to pick a model provider and hand it a credential. If it doesn't open, or you closed it by accident, this command brings it back and also sets OpenClaw up to start with your machine.

openclaw onboard --install-daemon

The wizard walks you through the provider list. Pick Ollama if you want the free local route, or pick your provider and paste the credential when it asks for one. Read that screen slowly, because a missed credential is the single most common reason the assistant answers nothing an hour later.

3 short commands then tell you whether the install actually worked, and you run them one after the other.

openclaw --version
openclaw doctor
openclaw gateway status

The first prints a version number. The second prints a list of checks with a mark against each one, which is the screen you will come back to whenever something breaks. The third tells you the gateway is listening, and the gateway is the piece everything else talks to. If all 3 look healthy, you have a working assistant.

Now open the interface you will actually use day to day.

openclaw dashboard

That opens the Control UI in your browser. Type a message into the chat and you should get a reply, which is the last step the getting started page lists. Time spent so far is a few minutes on a fast connection, and longer if Node had to be downloaded first.

How do you find and install an OpenClaw skill from ClawHub?

ClawHub is the public registry for OpenClaw skills and plugins, it lives at clawhub.ai, and you install from it with a command in the form openclaw skills install followed by an owner and a slug. You search from that same command line, so you never have to leave the terminal to find something.

Start by searching for something you would genuinely use, and a calendar works well here because almost everybody keeps one.

openclaw skills search "calendar"

You get back a list of published skills whose names or descriptions match what you typed. Each result carries an owner and a slug, and those 2 pieces together make the address you install by. Installing is one line, and this example comes straight from the documentation, so it works as a first test even before you have found something you want.

openclaw skills install @openclaw/demo

It downloads the skill and puts it where the assistant looks for it. Adding --global to the end makes it available in every workspace rather than only the one you are sitting in. Then confirm the thing landed where you expect.

openclaw skills list

Your new skill should appear by name in that list. If it doesn't, your chat session was open before the file existed, and one command from the failures section further down puts it right.

The last row is the one people underuse, and it is where the rest of this piece goes. There is little reason to hunt through a registry for a skill that reads your own notes file when you can describe the job in English and let the assistant write the file in front of you.

How do you build your own OpenClaw skill tonight?

You build your own OpenClaw skill by pasting a numbered instruction into the chat and letting the assistant write the SKILL.md file for you, which takes roughly the same time as making dinner, testing included. The example here is a skill called daily brief, and it reads a plain notes file and answers with a short summary of whatever you left unfinished.

It helps to see the finished thing first, because it is smaller than most people expect. A skill is a folder with one file inside, and the whole file fits on one screen.

---
name: daily-brief
description: Reads my notes file and returns a short brief when I ask for my brief
---

# Daily brief

When I ask for my brief, read the file at ~/notes/today.txt.
Answer with at most 5 short lines, starting with today's date.

The 3 dashes mark the frontmatter, the name is the identifier, the description is the line the assistant reads when it decides whether to use this, and everything under the second set of dashes is your instruction in plain English. Nothing in that file is code, and you could have written it in a notes app.

Now the block you actually copy. Open the chat you got from the dashboard command, paste this in one go and send it. It is numbered because the assistant works through it in order, and every numbered line ends in something you can see with your own eyes.

You are going to create my first OpenClaw skill with me, step by step, and you check each step before moving to the next one.

1. Create a skill named daily-brief in my workspace skills folder, so the file ends up at ~/.openclaw/workspace/skills/daily-brief/SKILL.md
2. Give it frontmatter with exactly 2 fields. The name is daily-brief. The description is one line under 160 characters saying that it reads my notes file and returns a short brief when I ask for my brief.
3. In the body, write in plain English what to do when I ask for my brief. Read the file at ~/notes/today.txt, then answer with at most 5 short lines, the first being today's date and the rest being anything in that file that is not finished.
4. If ~/notes/today.txt does not exist, create it with 2 example lines so the skill has something to read, and tell me you created it.
5. Explain to me in one sentence what the description field is for, before you save anything, so I understand what I am approving.
6. Show me the finished file in the chat and wait for me to say yes before you write it to disk.
7. After I say yes, save it, reload the skills, and confirm that daily-brief now appears in the skills list.
8. Test it yourself by asking for my brief, then show me the exact answer you got back.
9. If a step fails, tell me which one failed and what you would change, and do not retry more than twice.
10. Finish by telling me the single line I can type tomorrow to run this again.

Here is what you should see, in order. It tells you it made the folder, shows you the file and waits for your yes, saves it, reloads, then confirms the name appears in the skills list. Then it tests itself and prints the answer it got. If it skips the approval step and saves anyway, say so and ask it to show you the file, because reading what an assistant is about to write is a habit worth having from day one.

2 commands let you check the result yourself rather than trusting the assistant on it, and they are worth running once so you know what a healthy answer looks like.

openclaw skills list
openclaw agent --message "give me my brief"

The first prints your new skill among the others. The second sends a message from the command line and prints the answer, which is the same thing the chat window does with fewer moving pieces. You can also call the skill by name inside the chat, which is how you prove the skill fired rather than the assistant improvising an answer from thin air.

/skill daily-brief

Are OpenClaw skills from strangers safe to install?

An OpenClaw skill can tell the assistant to run commands on your machine, so installing one from a stranger is closer to running a script than to reading a document. ClawHub runs automated checks on published skills, and OpenClaw ships a command that checks one before you trust it, but the last check is you reading the file.

The scale of the registry is the problem here. The VoltAgent awesome list, which pulls its entries from ClawHub, claims more than 5,300 published skills. Nobody has read all of those. A skill is markdown, which sounds harmless enough, until you notice that the body can instruct the assistant to use its exec tool, and exec runs shell commands on your machine.

So before installing something from an owner you don't recognise, do 2 things. Run the verify command first, because it is the check OpenClaw gives you for a published skill.

openclaw skills verify @owner/slug

Then open the SKILL.md file and read it with your own eyes. You are looking for 2 things above all, a line that fetches something off the internet and runs it, and a line that touches the file where your credentials live. Then check whether the skill acts on text arriving from outside, such as an email or a web page. The documentation itself warns that prompts must not allow arbitrary command injection from untrusted input, which is the polite way of saying that a skill which reads your email and follows instructions found inside it will eventually follow somebody else's.

None of that means avoid the registry. It means treating a skill as a small program written by a stranger, because that is what it is, and 2 minutes of reading is cheap next to handing an assistant with shell access a set of instructions you never looked at. If you want the same reasoning applied to connecting tools rather than to instructions, our walkthrough on how to build an MCP server without writing code covers the other half of this picture.

What breaks first, and how do you know which piece failed?

Most first attempts fail in 1 of 4 places, and each one has a visible symptom, so you can name the wall instead of guessing at it. The 4 are a skill that never appears, a skill that appears but never fires, a provider that was never finished, and a name that isn't what you think it is.

Your skill does not appear in the list. This is almost always the session rather than the file. OpenClaw reads skills when a session starts, so a chat that was already open before you saved the file has no idea the file exists. Type /new in the chat to archive it and start a fresh one, or restart the gateway from the terminal and try again.

openclaw gateway restart

Your skill appears but the assistant never uses it. The description is the problem, essentially every time. It is the only line the assistant reads when deciding, so it has to contain the words you will actually type. Change a description reading "a helper for notes" into one reading "reads my notes file and returns a short brief when I ask for my brief", reload the session, and try the same request again.

The assistant answers nothing at all, or complains about a model. You have no provider set up, or the credential you pasted is wrong. Run the doctor command, read the row that fails, then run onboarding again and give it the credential properly. This one is common and it isn't really your fault, because it happens to anybody who closed a wizard early.

The name isn't what you assume. The documentation is explicit that a skill is named by the SKILL.md frontmatter and not by the folder path, so a folder called notes holding a file whose name line says brief gives you a skill called brief. Check the name line before hunting for a bug that was never there. And if you end up with a long list installed, remember there is a limit on how much of that list fits in the prompt, and when it is exceeded OpenClaw keeps the identities and drops the descriptions, which is exactly when a skill stops firing for no visible reason.

What to do in your first week with OpenClaw skills

Keep the first week small, because the failure here isn't technical. People install a pile of skills in an evening, watch the assistant get worse at choosing between them, and conclude the whole idea doesn't work. Start with the single skill you wrote yourself, use it every day for a week, and fix the description each time it fails to fire.

Then add a second skill for a job you do by hand at least twice a week, and write it the same way, by describing the job to the assistant rather than typing the file yourself. Your effort goes into the description and almost nowhere else. The body underneath can be 3 lines of plain English and still work perfectly well.

Read every skill you take from the registry before you install it, and keep a note of which ones you still used after a month. Most people find the answer is 3 or 4 of them, and that the rest were curiosity rather than need. When a skill does something you would rather approve first, say so inside the body, because an instruction to ask before acting is as legitimate as any other instruction in the file.

The whole build above is free if you run a local model, and it runs from an empty machine to a working skill in under an hour. What you have at the end isn't a chatbot with a hat on. It is a folder of plain files you can read, edit and delete with a text editor, which is a rarer property in this software than it ought to be, and the reason skills spread this fast in the first place.