openclaw/docs/tools/creating-skills.md

summary, title, read_when

summary	title	read_when
Build and test custom workspace skills with SKILL.md	Creating skills	You are creating a new custom skill in your workspace You need a quick starter workflow for SKILL.md-based 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

Skills live in your workspace. Create a new folder:

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

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 leaf 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. Verify the skill loaded:

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

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.

Propose before applying

For agent-generated procedures, use a Skill Workshop proposal instead of writing SKILL.md directly:

openclaw skills workshop propose-create \
  --name "hello-world" \
  --description "A simple skill that says hello." \
  --proposal ./PROPOSAL.md

Use --proposal-dir when the proposal also has support files:

openclaw skills workshop propose-create \
  --name "hello-world" \
  --description "A simple skill that says hello." \
  --proposal-dir ./hello-world-proposal

The draft is stored under <OPENCLAW_STATE_DIR>/skill-workshop/proposals/<proposal-id>/PROPOSAL.md and stays inactive until an operator reviews and applies it. The default state directory is ~/.openclaw. Proposal directories must contain PROPOSAL.md. Support files can be included under assets/, examples/, references/, scripts/, or templates/; OpenClaw stores and scans them with the proposal:

openclaw skills workshop inspect <proposal-id>
openclaw skills workshop revise <proposal-id> --proposal ./PROPOSAL.md
openclaw skills workshop apply <proposal-id>

When applied, OpenClaw writes the final SKILL.md into the workspace skills/ root, writes approved support files beside it, and removes proposal-only frontmatter such as status: proposal, proposal version, and proposal date.

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

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