How OpenClaw Skills Actually Work — The SKILL.md Architecture Explained

Every capability in OpenClaw is a skill. Understanding how skills are built helps you use them better, evaluate new ones wisely and build your own when needed.

When OpenClaw receives your message and decides to use the file-organiser skill or the web-search skill, what actually happens? Understanding the mechanics helps you configure skills better, evaluate ClawHub skills before installing them, and build your own when the existing library does not cover your use case.

The Three Components of Every Skill

Every skill lives in a directory under ~/.openclaw/skills/. The directory name is the skill name. Inside, three components work together:

SKILL.md is the instructions document that the LLM reads before deciding whether to invoke the skill. It describes what the skill does, when to use it versus when not to, what inputs it expects and what output to report to the user. The quality of the SKILL.md determines how reliably the agent uses the skill and in what situations.

scripts/ is the folder containing the executable code. This can be shell scripts (bash), Python scripts, JavaScript (Node.js) or a combination. The scripts run on your machine when the skill is invoked — they are the actual mechanism by which OpenClaw takes real-world action.

YAML frontmatter at the top of SKILL.md contains metadata: skill name, version, author, tags, and dependencies. Dependencies are automatically installed when you install the skill — if a Python skill requires the requests library, it is installed for you.

How the Agent Selects Skills

You do not need to invoke skills by name. The agent reads all installed skills' SKILL.md files and decides which ones are relevant to your current request. If you ask "check if my website is down", it looks for skills related to website monitoring or URL checking and uses whichever is most relevant.

This means that well-written SKILL.md files with clear, specific descriptions of use cases produce more reliable skill selection than vague or overly general descriptions. When evaluating a ClawHub skill before installing, read its SKILL.md first — the quality of that document tells you a lot about the quality of the skill overall.

Chaining Skills in a Single Request

The agent can use multiple skills in sequence for a single request. "Research the top 3 news stories about [company] and email me a summary" uses web-search to find the stories, then email-manager to compose and send the message. The agent plans the sequence, executes each step and feeds the output of one step as input to the next.