How to Build Your First OpenClaw Skill in 15 Minutes

Hello builders,

The fastest way to make an idle OpenClaw install useful is one custom skill, and your first one takes about 15 minutes and a text editor. The format most tutorials still show, a config.yaml with trigger, context, action and output sections registered in skills.json, is not what the product loads, so people write it, restart everything and decide skills are broken. This OpenClaw custom skill tutorial builds the real thing: one SKILL.md file with two lines of front matter, checked with two commands.

So what does a skill actually need? The OpenClaw docs list exactly two required fields: name, a “Unique slug using lowercase letters, digits, and hyphens,” and description, a “One-line description shown to the agent and in discovery output.” Everything under the second --- is plain English, written the way you would brief a new colleague. There is no schema to learn and no registry to add it to.

The picture is the whole format. The name line is the slug the agent calls it by. The description line is the one that decides when the agent uses it, and it is the line I would spend the most time on. Below the fences are instructions, not code. Write the file and the count moves, with nothing to register.

Write the notes skill

We are building a skill that reads your local notes and answers “what did I write about X?” Run this, then change ~/Documents/Obsidian to wherever your notes actually live.

mkdir -p ~/.openclaw/workspace/skills/notes-reader
cat > ~/.openclaw/workspace/skills/notes-reader/SKILL.md <<'EOF'
---
name: notes-reader
description: Read the user's local markdown notes and answer questions about them.
---

# Notes Reader

Use when the user asks what they wrote about a topic.

1. Search `~/Documents/Obsidian` for markdown files matching the topic.
2. Read the matches.
3. Answer with the note title and date, quoting the relevant passage.
EOF
openclaw skills list
openclaw skills info notes-reader

We watch the header on openclaw skills list. On the book’s machine it went from Skills (51/85 ready) to Skills (52/86 ready). On a clean 2026.9.6 test install mine went from Skills (25/57 ready) to Skills (26/58 ready), because the totals depend on which command-line tools you happen to have installed. The part that matters is that both numbers go up by one. Then openclaw skills info notes-reader should end with these lines.

Details:
  Source: openclaw-workspace
  Path: ~/.openclaw/workspace/skills/notes-reader/SKILL.md
  Visible to model: yes
  Available as command: yes

Visible to model: yes is the line we are after, since a skill can be present and still invisible to the agent. If you already run a second agent, add --agent main to both commands; on 2026.9.6 the bare form refuses once there are two. Now open Telegram and ask “What did I write about pricing last week?” about a topic you know is in there.

When it never fires

Three things go wrong here, and we fix each one differently.

If the skill doesn’t appear in the list at all, the file is in the wrong folder or the front matter is broken. The --- has to be the very first line, and the two fields sit between the fences.

If it’s listed and ready but the agent ignores it, your description is too vague. The model reads that one line to decide whether the skill is relevant, so “Reads notes” loses to “Read the user’s local markdown notes and answer questions about them,” which names the situation and the action. I rewrite that line more than any other.

If it fires and comes back empty, the agent can’t reach the folder. When you hardened OpenClaw and set tools.fs.workspaceOnly to true, you confined the agent to its workspace, so a skill reading ~/Documents is blocked by design. Move the notes inside ~/.openclaw/workspace or relax that setting knowingly.

What if you’re mid-conversation and the new skill still isn’t picked up? The docs cover that case, and the fix is one word.

OpenClaw watches SKILL.md files under skills roots by default. If the watcher is disabled or you are continuing an existing session, start a new one so the agent receives the refreshed list

In practice we send /new in the chat and carry on.

One number worth doing before you point this at a big vault: two megabytes of markdown is roughly half a million tokens, about fifty cents a question on Kimi K2.6 if the agent reads all of it. That is why step 1 searches and step 2 reads only the matches, which brings it down to around a cent.

Improving the skill is a matter of writing better instructions. We add one line under the numbered steps and the agent starts reading dates the way we mean them.

Prefer files modified in the last 30 days. If the user says “last week,” restrict to the last 7 days by file modification date and say so in your answer.

A tag filter or a folder it must never open goes in the same way, one sentence each. When it works, keep it: openclaw skills install ~/.openclaw/workspace/skills/notes-reader --as notes-reader --global copies it into the shared skills folder, and openclaw backup create --verify puts it in a backup. I ran that install on 2026.9.6 and it landed in the managed skills folder first time.

Here’s why I’d do this tonight. Every project after it, the inbox triage, the research analyst, the content engine, is the same shape: a folder, a SKILL.md, two lines of front matter and instructions. Once we’ve written one, we’ve learned the only format there is, and the rest is deciding what to write inside it.

Now go build something this weekend!

John Cook