mirror of
https://github.com/openclaw/openclaw.git
synced 2026-06-05 09:22:55 +00:00
198 lines
7.2 KiB
Markdown
198 lines
7.2 KiB
Markdown
---
|
|
summary: "Build and test custom workspace skills with SKILL.md"
|
|
title: "Creating skills"
|
|
read_when:
|
|
- 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](/tools/skills).
|
|
|
|
## Create your first skill
|
|
|
|
<Steps>
|
|
<Step title="Create the skill directory">
|
|
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`.
|
|
|
|
</Step>
|
|
|
|
<Step title="Write SKILL.md">
|
|
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.
|
|
|
|
</Step>
|
|
|
|
<Step title="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.
|
|
|
|
</Step>
|
|
|
|
<Step title="Load the skill">
|
|
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
|
|
```
|
|
|
|
</Step>
|
|
|
|
<Step title="Test it">
|
|
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.
|
|
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Propose before applying
|
|
|
|
For agent-generated procedures, use a Skill Workshop proposal instead of
|
|
writing `SKILL.md` directly:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](/tools/skills#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](/tools/skills#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](/tools/skills#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](https://clawhub.ai)
|
|
|
|
## 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](/tools/skills) — loading, precedence, and gating rules
|
|
- [Skills config](/tools/skills-config) — `skills.*` config schema
|
|
- [ClawHub](/clawhub) — public skill registry
|
|
- [Building Plugins](/plugins/building-plugins) — plugins can ship skills
|