Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Skills teach the agent how and when to use tools. Each skill is a directory containing a SKILL.md file with YAML frontmatter and markdown instructions. For how skills are loaded and prioritized, see Skills.

​
Create your first skill

1

Create the skill directory

Skills live in your workspace. Create a new folder:
mkdir -p ~/.openclaw/workspace/skills/hello-world
2

Write SKILL.md

Create SKILL.md inside that directory. The frontmatter defines metadata, and the markdown body contains instructions for the agent.
---
name: hello-world
description: A simple skill that says hello.
---

# Hello World Skill

When the user asks for a greeting, use the `echo` tool to say
"Hello from your custom skill!".
Use hyphen-case with lowercase letters, digits, and hyphens for the skill name. Keep the folder name and frontmatter name aligned.
3

Add tools (optional)

You can define custom tool schemas in the frontmatter or instruct the agent to use existing system tools (like exec or browser). Skills can also ship inside plugins alongside the tools they document.
4

Load the skill

Start a new session so OpenClaw picks up the skill:
# From chat
/new

# Or restart the gateway
openclaw gateway restart
Verify the skill loaded:
openclaw skills list
5

Test it

Send a message that should trigger the skill:
openclaw agent --message "give me a greeting"
Or just chat with the agent and ask for a greeting.

​
Skill metadata reference

The YAML frontmatter supports these fields:
FieldRequiredDescription
nameYesUnique identifier using lowercase letters, digits, and hyphens
descriptionYesOne-line description shown to the agent
metadata.openclaw.osNoOS filter (["darwin"], ["linux"], etc.)
metadata.openclaw.requires.binsNoRequired binaries on PATH
metadata.openclaw.requires.configNoRequired config keys

​
Best practices

  • Be concise — instruct the model on what to do, not how to be an AI
  • Safety first — if your skill uses exec, ensure prompts don’t allow arbitrary command injection from untrusted input
  • Test locally — use openclaw agent --message "..." to test before sharing
  • Use ClawHub — browse and contribute skills at ClawHub

​
Where skills live

LocationPrecedenceScope
\<workspace\>/skills/HighestPer-agent
\<workspace\>/.agents/skills/HighPer-workspace agent
~/.agents/skills/MediumShared agent profile
~/.openclaw/skills/MediumShared (all agents)
Bundled (shipped with OpenClaw)LowGlobal
skills.load.extraDirsLowestCustom shared folders