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

```bash
mkdir -p ~/.openclaw/workspace/skills/hello-world
```

You can group skills in subfolders when your library grows:

```bash
mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
```

Group folders are only organizational. The skill is still named by
`SKILL.md` frontmatter, so `name: hello-world` is invoked as
`/hello-world`.

```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 leaf folder name and frontmatter `name` aligned.

```bash
openclaw skills list
```

OpenClaw watches nested `SKILL.md` files under skills roots. If the watcher
is disabled or you are continuing an existing session, start a new session
so the model receives the refreshed skills list:

```bash
# From chat
/new

# Or restart the gateway
openclaw gateway restart
```

```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:

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

Each skills root can contain direct skill folders such as skills/hello-world/SKILL.md or grouped folders such as skills/personal/hello-world/SKILL.md.

Related

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