docs/tools/creating-skills.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.
OpenClaw loads skills from several roots in a defined precedence order.
```bash
mkdir -p ~/.openclaw/workspace/skills/hello-world
```
You can group skills in subfolders for organization — the skill is still
named by the `SKILL.md` frontmatter, not the folder path:
```bash
mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
# skill name is still "hello-world", invoked as /hello-world
```
```markdown
---
name: hello-world
description: A simple skill that prints a greeting.
---
# Hello World
When the user asks for a greeting, use the `exec` tool to run:
```bash
echo "Hello from your custom skill!"
```
```
Naming rules:
- Use lowercase letters, digits, and hyphens for `name`.
- Keep the directory name and frontmatter `name` aligned.
- `description` is shown to the agent and in slash-command discovery —
keep it one line and under 160 characters.
OpenClaw watches `SKILL.md` files under skills roots by default. If the
watcher is disabled or you are continuing an existing session, start a new
one so the agent receives the refreshed list:
```bash
# From chat — archive current session and start fresh
/new
# Or restart the gateway
openclaw gateway restart
```
```bash
openclaw agent --message "give me a greeting"
```
Or open a chat and ask the agent directly. Use `/skill hello-world` to
invoke it explicitly by name.
| Field | Description |
|---|---|
name | Unique slug using lowercase letters, digits, and hyphens |
description | One-line description shown to the agent and in discovery output |
| Field | Default | Description |
|---|---|---|
user-invocable | true | Expose the skill as a user slash command |
disable-model-invocation | false | Keep the skill out of the agent's system prompt (still runs via /skill) |
command-dispatch | — | Set to tool to route the slash command directly to a tool, bypassing the model |
command-tool | — | Tool name to invoke when command-dispatch: tool is set |
command-arg-mode | raw | For tool dispatch, forwards the raw args string to the tool |
homepage | — | URL shown as "Website" in the macOS Skills UI |
For gating fields (requires.bins, requires.env, etc.) see
Skills — Gating.
{baseDir}Use {baseDir} in the skill body to reference files inside the skill
directory without hardcoding paths:
Run the helper script at `{baseDir}/scripts/run.sh`.
Gate your skill so it only loads when its dependencies are available:
---
name: gemini-search
description: Search using Gemini CLI.
metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }
---
Full reference: [Skills — Gating](/tools/skills#gating).
```json5
{
skills: {
entries: {
"gemini-search": {
enabled: true,
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
},
},
},
}
```
The key is injected into the host process for that agent turn only.
It does not reach the sandbox — see
[sandboxed env vars](/tools/skills-config#sandboxed-skills-and-env-vars).
For agent-drafted skills or when you want operator review before a skill goes
live, use Skill Workshop proposals instead of writing
SKILL.md directly.
# Propose a brand-new skill
openclaw skills workshop propose-create \
--name "hello-world" \
--description "A simple skill that prints a greeting." \
--proposal ./PROPOSAL.md
# Propose an update to an existing skill
openclaw skills workshop propose-update hello-world \
--proposal ./PROPOSAL.md \
--description "Updated greeting skill"
Use --proposal-dir when the proposal includes support files:
openclaw skills workshop propose-create \
--name "hello-world" \
--description "A simple skill that prints a greeting." \
--proposal-dir ./hello-world-proposal/
The directory must contain PROPOSAL.md. Support files can go in assets/,
examples/, references/, scripts/, or templates/.
After review:
openclaw skills workshop inspect <proposal-id>
openclaw skills workshop apply <proposal-id>
See Skill Workshop for the full proposal lifecycle.
```bash
openclaw skills install clawhub-publish
```
See [ClawHub — Publishing](/clawhub/publishing) for the full flow.