OpenClaw skills, explained

If you run an agent in OpenClaw and keep bumping into "skills," here's the short, practical version: what a skill is in this runtime, how the agent decides to load one, the real reasons a skill never fires, and a checklist for writing ones that hold up under a cold start.

1. What an OpenClaw skill is

In OpenClaw a skill is a folder containing a SKILL.md file. That file carries a one-line description of when the skill applies and a body of instructions the agent reads only when the situation actually comes up. The runtime lists every available skill's name, description and on-disk location to the agent up front — but it does not paste the full bodies into context.

This matters because it's the whole point: a skill is not code that executes. It is context that loads on demand. The agent treats the descriptions as a table of contents, picks the most specific match for the task in front of it, and only then opens that one skill's body. Write the description so it loads at the right moment and the body so following it produces a reliable result, and the skill works.

2. How a skill gets loaded

The decision happens before the agent answers, in three steps:

1. Scan. The agent reads the list of skill descriptions injected at the top of its context.
2. Select. If exactly one clearly applies, it picks that. If several could apply, it chooses the most specific. If none clearly apply, it loads nothing — and that's fine.
3. Read. Only after selecting does it open that skill's SKILL.md at the exact location the runtime gave it, then follows the steps inside.

The practical takeaway: your description is doing almost all the work. It is the only part of the skill that influences whether the skill is ever read. A brilliant body behind a vague description is dead weight.

3. The anatomy of a SKILL.md

A minimal, well-formed skill looks like this:

---
name: standup-writer
description: Use when the user wants yesterday/today/blockers
  turned into a clean daily standup update from rough notes.
---

# Standup writer

## When this applies
The user has scrappy notes about what they did and what's
next, and wants a tidy standup message, not a rewrite of
their whole week.

## Steps
1. Group the notes into Yesterday / Today / Blockers.
2. One concise bullet per item; cut filler.
3. Flag anything that reads like a blocker explicitly.
4. Output the finished update, nothing else.

## Rules
- Never invent progress that isn't in the notes.
- If there are no blockers, say "No blockers" — don't omit
  the section.

Two parts carry the weight:

• The frontmatter description is the trigger. Write it as "Use when…" and name the concrete situation plus the words the user will actually say — not the topic in the abstract.
• The body is the procedure. The best bodies read like a runbook from a careful colleague: numbered steps, explicit rules, and the awkward edge cases called out by name.

4. Why your skill never fires

The most common failure isn't bad instructions — it's that the skill is never selected. Reliable fixes:

• Start the description with "Use when…" and describe the user's situation, not your skill's subject. "Use when the user wants to summarise a long article or webpage" beats "A summarisation skill."
• Name the artifacts and verbs the user will say out loud: "standup," "changelog," "invoice," "PDF." Those exact words are what the agent matches against.
• One job per skill. A skill that claims five jobs competes badly against five focused skills, and the agent can't tell when to pick it.
• Don't overlap descriptions. If two skills both say "use for documents," selection becomes a coin flip. Make the boundaries sharp and mutually exclusive.
• Keep it discoverable on disk. The body must live at the location the runtime advertises; if you move or rename it, the path the agent was told to open no longer resolves.

5. Scope, paths and safety

Two things trip people up once a skill does fire:

None of this is OpenClaw-specific theory — it's the difference between a skill that demos well and one that survives being used by someone who isn't you.

6. A build checklist

Before you call a skill done, run it against this:

1. Description starts with "Use when" and names a concrete situation + the words the user will say.
2. One job per skill. If "and" appears twice in the description, consider splitting it.
3. Numbered steps in the body — an agent follows a sequence far more reliably than a paragraph.
4. Explicit rules and refusals. Say what not to do and when to stop and ask.
5. Paths resolved against the skill directory, stated absolutely.
6. No placeholders left behind (TODO, FIXME, <your value>). Grep for them.
7. Tested from a cold start, on a task you didn't write the skill around.

That last point is where most skills quietly fail: they work for the author who already knows the intent, and fall apart for everyone else. Test from cold.

Once the free pack makes sense, the OpenClaw power skills pack goes further — a set of production-minded skills built and QA'd exactly the way this guide describes. Building on Claude Code too? There's a Claude Code dev skills bundle, and for automations an n8n workflow set. The whole toolkit lives at ai-max.dev.

Want the deeper Claude-side mechanics, or to wire skills into automations? See the companion guides: Claude Skills, explained and n8n AI agent workflows, without the breakage. Curious how crowded the niche is? See the live AI-agent niche density tracker.