Creating skills

Build and test custom workspace skills with SKILL.md

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](/docs/openclaw-docs/tools/skills.

Create your first skill

Skills live in your workspace. Create a new folder: 
```bash
mkdir -p ~/.openclaw/workspace/skills/hello-world
```
Create `SKILL.md` inside that directory. The frontmatter defines metadata, and the markdown body contains instructions for the agent. 
```markdown
---
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.
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. Start a new session so OpenClaw picks up the skill: 
```bash
# From chat
/new

# Or restart the gateway
openclaw gateway restart
```

Verify the skill loaded:

```bash
openclaw skills list
```
Send a message that should trigger the skill: 
```bash
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
  • [Skills reference](/docs/openclaw-docs/tools/skills — loading, precedence, and gating rules
  • [Skills config](/docs/openclaw-docs/tools/skills-config — skills.* config schema
  • [ClawHub](/docs/openclaw-docs/clawhub — public skill registry
  • [Building Plugins](/docs/openclaw-docs/plugins/building-plugins — plugins can ship skills