Building Custom OpenClaw Skills: A Developer's Guide

Your OpenClaw agent comes with a solid set of built-in skills — browser automation, GitHub, weather, TTS, image generation. But the real power is building your own. Custom skills let you teach your agent exactly how to use the tools and workflows specific to your setup.

I've built dozens of custom skills for my own operations — deploy notifications, health checks, content pipelines, SEO automation. Here's everything I've learned about creating skills that actually work in production.

What Is a Skill, Exactly?

A skill is a directory containing a SKILL.md file. That's it. No SDK to learn, no build step, no compilation. The SKILL.md has YAML frontmatter (metadata) and markdown body (instructions). OpenClaw reads these at session start and injects the instructions into the agent's system prompt when the skill is eligible.

Think of skills as specialized instruction sets. They don't add new tools to the agent — they teach the agent how and when to use existing tools for specific tasks. Your agent already has exec, web_fetch, message, browser, and dozens more. Skills wire those tools into domain-specific workflows.

Your First Custom Skill

Let's build a deploy notification skill. When you tell your agent you've deployed something, it should grab the latest commit info and post a notification to your chat channel.

Step 1: Create the Directory

Skills live in your workspace's skills/ folder. That's the highest-precedence location — it overrides everything else:

mkdir -p ~/.openclaw/workspace/skills/deploy-notify

Step 2: Write SKILL.md

Create SKILL.md inside that directory:

---
name: deploy_notify
description: "Post deploy notifications to Slack and Discord after a successful deployment."
---

# Deploy Notify Skill

When the user says they've deployed something, or a deploy event fires:

1. Use the `exec` tool to run: `git log -1 --format="%h %s"` in the project directory
2. Use the `message` tool to post to the configured channel:
   "✅ Deployed `{commit_hash}`: {commit_message}"
3. If the user specified a URL, include it in the notification.

Keep messages to one line. No fluff.

That's a complete, functional skill. The name is a unique identifier (snake_case). The description tells the agent when this skill is relevant. The markdown body contains the actual instructions.

Step 3: Load and Test

Start a new session so OpenClaw picks up the skill — either send /new in chat or restart the gateway. Then verify it loaded:

# List all skills visible to your agent
openclaw skills list

# Show only eligible skills (passed all gates)
openclaw skills list --eligible

# Get details about a specific skill
openclaw skills info deploy_notify

# Run diagnostics on skill loading
openclaw skills check

Now tell your agent "I just deployed the API" and watch it execute the workflow you defined.

Adding Metadata Gates

Not every skill should load in every environment. Maybe your database backup skill only makes sense on Linux, or your image processing skill needs ffmpeg on the PATH. OpenClaw's gating system handles this with the metadata frontmatter.

Here's a weather skill that only loads on macOS and Linux, and requires curl:

---
name: weather_brief
description: Get current weather and forecast for a location using wttr.in
metadata: {"openclaw": {"requires": {"bins": ["curl"]}, "os": ["darwin", "linux"]}}
---

# Weather Brief

When the user asks about weather:

1. Use `exec` to run: `curl -s "wttr.in/{location}?format=3"`
2. For detailed forecasts: `curl -s "wttr.in/{location}?format=j1"`
3. Parse the JSON and report temperature, conditions, and forecast.

If no location specified, ask the user.

The gating fields live under metadata.openclaw:

• requires.bins — list of binaries that must exist on PATH. If any is missing, the skill won't load.
• requires.anyBins — at least one of these must exist (for tools with alternatives).
• requires.env — environment variables that must be set (or provided via config).
• requires.config — config paths in openclaw.json that must be truthy.
• os — restrict to specific platforms: darwin, linux, or win32.
• primaryEnv — the main env var this skill needs, used with skills.entries.*.apiKey in config.

A fully gated production skill might look like this:

---
name: db_backup
description: Run PostgreSQL backups and upload to S3
metadata: {"openclaw": {"requires": {"bins": ["pg_dump", "aws"]}, "env": ["DATABASE_URL", "S3_BUCKET"], "primaryEnv": "DATABASE_URL", "os": ["linux"]}}
---

This skill only loads on Linux, only when pg_dump and aws CLI are installed, and only when DATABASE_URL and S3_BUCKET environment variables are set. If any gate fails, the skill silently drops from the eligible list.

Environment Injection

Skills often need API keys or configuration values. You could set these as system environment variables, but OpenClaw offers a cleaner approach — per-skill env injection through openclaw.json:

{
  "skills": {
    "entries": {
      "api-health": {
        "enabled": true,
        "env": {
          "HEALTHCHECK_URLS": "https://api.example.com/health,https://app.example.com/ping"
        }
      },
      "deploy-notify": {
        "enabled": true
      }
    }
  }
}

Key behaviors:

• env values are injected only if the variable isn't already set in the process environment.
• apiKey is a convenience shortcut for skills that declare a primaryEnv — it maps to that env var automatically.
• Environment injection is scoped to the agent run, not a global shell change. After the run ends, the original environment is restored.
• In sandboxed sessions, host-side env injection doesn't reach the container. Use agents.defaults.sandbox.docker.env instead.

Writing Good Instructions

The markdown body of your SKILL.md is where skill quality lives or dies. Here's what I've learned works:

Be Specific About Tool Usage

Don't say "fetch the URL." Say "Use the web_fetch tool to get the page content as markdown." The agent has many tools — tell it which one to use:

---
name: summarize_url
description: Fetch a URL and summarize its content in 2-3 sentences
metadata: {"openclaw": {"requires": {"bins": ["curl", "python3"]}}}
---

# URL Summarizer

When the user asks to summarize a URL:

1. Use the `web_fetch` tool to get the page content as markdown
2. Analyze the content and produce a 2-3 sentence summary
3. Include: what the page is about, key takeaway, and relevance

If the URL is behind a paywall or returns an error, report that clearly.
Don't hallucinate content — only summarize what you actually retrieved.

Include Error Handling

The last line is important: "Don't hallucinate content — only summarize what you actually retrieved." Without this, the agent might fill in gaps with generated content when a fetch partially fails.

Use {baseDir} for Relative Paths

If your skill ships helper scripts or templates, reference them with {baseDir} in the instructions. OpenClaw replaces this with the skill's directory path at load time:

skills/
├── deploy-notify/
│   └── SKILL.md
├── api-health/
│   ├── SKILL.md
│   └── check.sh          # Helper script referenced in instructions
└── weekly-report/
    ├── SKILL.md
    └── template.md        # Report template

In your SKILL.md, you'd write: "Read the template from {baseDir}/template.md" and OpenClaw resolves it to the actual path.

Skill Precedence and Overrides

OpenClaw loads skills from multiple locations. Understanding precedence matters when you want to override a bundled skill or share skills across agents:

1. <workspace>/skills/ — highest priority, per-agent
2. <workspace>/.agents/skills/ — project agent skills
3. ~/.agents/skills/ — personal agent skills, shared across workspaces
4. ~/.openclaw/skills/ — managed/local skills, shared across all agents
5. Bundled skills — shipped with OpenClaw
6. skills.load.extraDirs — lowest priority, custom shared folders

If a skill name exists in multiple locations, the highest-precedence version wins. This means you can override a bundled skill by creating a same-named skill in your workspace — no need to modify the OpenClaw installation.

In multi-agent setups, each agent has its own workspace. Skills in <workspace>/skills/ are per-agent. Skills in ~/.openclaw/skills/ are shared across all agents on the machine. Choose the right location based on whether the skill is agent-specific or universal.

Plugins Can Ship Skills Too

If you're building a plugin (a more advanced extension that adds tools, channels, or providers), you can bundle skills alongside it. List skill directories in your openclaw.plugin.json manifest, and they'll load automatically when the plugin is enabled.

Plugin skills have the same precedence as skills.load.extraDirs — lowest. Any same-named workspace or managed skill overrides them. This is intentional: users should always be able to customize or replace vendor-provided instructions.

The Skills Watcher

By default, OpenClaw watches your skill directories for changes. Edit a SKILL.md and the updated instructions are picked up on the next agent turn — no restart needed.

This is enabled by default, but you can configure it:

{
  "skills": {
    "load": {
      "watch": true,
      "watchDebounceMs": 250
    }
  }
}

The debounce prevents rapid-fire reloads if you're editing multiple files at once. In practice, you rarely need to touch this.

ClawHub: Share and Discover Skills

Once you've built something useful, share it. ClawHub is the public skill registry for OpenClaw. You can browse, install, and publish skills directly from the CLI:

# Search ClawHub for calendar skills
openclaw skills search "calendar"

# Install a skill from ClawHub
openclaw skills install daily-standup

# Update all installed skills
openclaw skills update --all

Installing from ClawHub puts the skill in your workspace's skills/ directory. Updates are pulled the same way. If you've built a skill that solves a real problem, consider publishing it — the community benefits from practical, battle-tested skills more than theoretical frameworks.

Token Cost Awareness

Every eligible skill adds to your system prompt. The cost is predictable: about 97 characters per skill plus the length of the name, description, and location. With a rough estimate of 4 characters per token, that's roughly 24+ tokens per skill.

For most setups with 10-20 skills, this is negligible. But if you're loading 50+ skills, consider:

• Using metadata gates to limit eligibility to relevant contexts
• Setting enabled: false in config for skills you rarely need
• Using skills.allowBundled to restrict which bundled skills load

Real-World Patterns

After building skills for months, here are patterns that consistently work:

• One skill, one workflow. Don't create a "do everything" skill. A deploy-notify skill and a deploy-rollback skill are better than a deploy-everything skill.
• Gate aggressively. If a skill needs docker, gate on it. Don't let the agent try to use Docker commands on a machine without Docker — it'll waste tokens on errors.
• Include safety rails. If your skill touches production systems, add explicit warnings: "NEVER run this against the production database without user confirmation."
• Test with openclaw agent --message. Quick one-shot testing from the CLI before relying on the skill in real workflows.
• Use {baseDir} for assets. Ship templates, scripts, and reference files alongside the skill. They're portable and self-contained.

Security Considerations

Skills are powerful — they directly influence what your agent does. A few rules:

• Treat third-party skills as untrusted code. Read the SKILL.md before enabling any skill from ClawHub or other sources.
• Keep secrets in config, not in skill files. Use skills.entries.*.env and skills.entries.*.apiKey to inject secrets. Never hardcode API keys in SKILL.md.
• Sandbox risky skills. If a skill instructs the agent to run arbitrary commands from untrusted input, run it in a sandboxed session.
• Workspace-origin skills are disabled by default. This is intentional — you must explicitly enable them in config. It prevents accidental loading of skills from cloned repos.

What's Next

Skills are the simplest extension point in OpenClaw — just a markdown file. But they're also the most impactful. A well-written skill turns a general-purpose AI agent into a specialist for your exact workflow.

Start with one skill that automates something you do daily. Test it. Refine the instructions. Then build another. Before long, your agent knows your entire operational playbook.

---

Want the complete system? The OpenClaw Playbook ($9.99) covers skills, workspace architecture, memory systems, cron automation, sub-agent delegation, and production deployment — everything you need to run an AI agent as a real team member.

Originally published at openclawplaybook.ai.