The Developer's Guide to OpenClaw Agent Skills

Agent Skills are the backbone of OpenClaw's extensibility, allowing developers to teach the AI how to use new tools and integrate with external systems. They are self-contained units that define both how a tool works and when it should be used.

What is an Agent Skill?

An Agent Skill is a folder containing at least one file: SKILL.md. This file uses YAML frontmatter to declare metadata (name, description, requirements) and markdown body to document usage. Skills are compatible with the AgentSkills.io open standard, making them portable across AI platforms.

OpenClaw loads skills from three locations, in order of precedence:

1. Workspace skills (<workspace>/skills) — Highest priority, per-project overrides
2. Managed skills (~/.openclaw/skills) — Shared across agents on a machine
3. Bundled skills — Shipped with OpenClaw (e.g. github, calendar, browser)

Skills in your workspace override system ones, allowing safe experimentation.

Anatomy of a SKILL.md

Every skill starts with structured frontmatter:

---
name: github
 description: Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
---

The frontmatter supports optional metadata for load-time gating:

metadata:
 {
   "openclaw":
     {
       "requires": { "bins": ["gh"], "env": ["GITHUB_TOKEN"] },
       "install": [
         {"kind": "brew", "formula": "github/gh/gh", "bins": ["gh"]}
       ]
     },
 }

This ensures the skill only loads if gh is installed and GITHUB_TOKEN is set. It also offers a one-click install via Homebrew in the macOS app.

How Skills Are Used

When OpenClaw starts a session, it scans all eligible skills and injects a compact XML list into the AI's system prompt. This allows the agent to reason about available tools.

Environment variables (skills.entries.<name>.env) and API keys are injected per agent run, not globally. They’re restored afterward for safety.

Skills are snapshot at session start. Changes require a new session unless the skills watcher is enabled.

Skill Discovery and Installation

The ClawHub registry hosts public skills. Use the clawhub CLI to install:

 clawhub install github

This places the skill in your workspace. You can update all skills with:

 clawhub update --all

Security and Best Practices

• Treat third-party skills as untrusted code. Always review SKILL.md.
• Prefer sandboxed execution for risky commands.
• Avoid hardcoding secrets. Use metadata.openclaw.primaryEnv and config injection.
• For macOS-specific skills (e.g. thing-mac), the gateway can delegate to paired nodes if the tool is locally available.

Building Your Own Skill

Start by forking an existing skill. Define name, description, and metadata.requires for your tool. In the body, document:

• Tool purpose and common use cases
• Required binaries and env vars
• Example invocations
• Any setup steps

Test locally, then publish to ClawHub for others to use.

Skills empower OpenClaw to move beyond chat into automation. Master them, and you unlock the full potential of your AI workspace.