Creating skills

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

Create the skill directory
Skills live in your workspace. Create a new folder:
Terminal window
```
mkdir -p ~/.openclaw/workspace/skills/hello-world
```
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.
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.
Load the skill
Start a new session so OpenClaw picks up the skill:
Terminal window
```
# From chat
/new

# Or restart the gateway
openclaw gateway restart
```
Verify the skill loaded:
Terminal window
```
openclaw skills list
```
Test it
Send a message that should trigger the skill:
Terminal window
```
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:

Field	Required	Description
`name`	Yes	Unique identifier using lowercase letters, digits, and hyphens
`description`	Yes	One-line description shown to the agent
`metadata.openclaw.os`	No	OS filter (`["darwin"]`, `["linux"]`, etc.)
`metadata.openclaw.requires.bins`	No	Required binaries on PATH
`metadata.openclaw.requires.config`	No	Required config keys

Advanced features

Once a basic skill works, these fields help make it reliable and portable:

Conditional activation — use requires.bins, requires.env, or requires.config to load the skill only when required dependencies are available. See Skills reference: gating.
Environment and API-key wiring — use skills.entries.<name>.env and skills.entries.<name>.apiKey to inject host-side environment for a skill turn. See Skills reference: config wiring.
Invocation control — set user-invocable: false to hide a slash command, or disable-model-invocation: true to keep a command-style skill out of the model prompt. See Skills reference: frontmatter.
Direct command dispatch — use command-dispatch: tool with command-tool when a slash command should call a tool directly instead of routing through the model.
Portable paths — use {baseDir} in SKILL.md when referencing scripts or assets inside the skill directory.
Publishing — use the ClawHub skill when preparing a skill for publication. It documents the current clawhub publish command shape and required metadata.

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

Location	Precedence	Scope
`\<workspace\>/skills/`	Highest	Per-agent
`\<workspace\>/.agents/skills/`	High	Per-workspace agent
`~/.agents/skills/`	Medium	Shared agent profile
`~/.openclaw/skills/`	Medium	Shared (all agents)
Bundled (shipped with OpenClaw)	Low	Global
`skills.load.extraDirs`	Lowest	Custom shared folders

Skills reference — loading, precedence, and gating rules
Skills config — skills.* config schema
ClawHub — public skill registry
Building Plugins — plugins can ship skills