Skills and Plugins in OpenClaw

Prerequisites

• ✓An existing OpenClaw install (npm package or OpenClaw.app) so bundled skills are available.
• ✓At least one configured OpenClaw workspace where `<workspace>/skills` can be created and managed.
• ✓Any external CLIs or APIs your skills require, such as `gemini` when using the `gemini` skill or `uv` for skills that declare it in `requires.bins`.

Steps

1. 1

   Understand where OpenClaw loads skills from

   Before you add or override skills, you need to know which folders OpenClaw scans and which one wins on conflicts. This is what decides whether your workspace copy or a bundled/plugin copy of a skill actually runs.

   textCopy

   OpenClaw loads skills from these sources:
   1.   **Extra skill folders**: configured with `skills.load.extraDirs`
   2.   **Bundled skills**: shipped with the install (npm package or OpenClaw.app)
   3.   **Managed/local skills**: `~/.openclaw/skills`
   4.   **Personal agent skills**: `~/.agents/skills`
   5.   **Project agent skills**: `<workspace>/.agents/skills`
   6.   **Workspace skills**: `<workspace>/skills`
   
   If a skill name conflicts, precedence is:`<workspace>/skills` (highest) → `<workspace>/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled skills → `skills.load.extraDirs` (lowest)

2. 2

   Organize per-agent and shared skills

   In multi-agent setups, each agent has its own workspace, so where you drop a skill controls which agents see it. Use workspace and agent-specific folders when you want isolation, and shared folders when you want a common toolbox.

   textCopy

   In **multi-agent** setups, each agent has its own workspace. That means:
   *   **Per-agent skills** live in `<workspace>/skills` for that agent only.
   *   **Project agent skills** live in `<workspace>/.agents/skills` and apply to that workspace before the normal workspace `skills/` folder.
   *   **Personal agent skills** live in `~/.agents/skills` and apply across workspaces on that machine.
   *   **Shared skills** live in `~/.openclaw/skills` (managed/local) and are visible to **all agents** on the same machine.
   *   **Shared folders** can also be added via `skills.load.extraDirs` (lowest precedence) if you want a common skills pack used by multiple agents.
   
   If the same skill name exists in more than one place, the usual precedence applies: workspace wins, then project agent skills, then personal agent skills, then managed/local, then bundled, then extra dirs.

3. 3

   Control which skills each agent can use with allowlists

   Location decides which copy of a skill wins, but allowlists decide whether an agent can use it at all. Use defaults for a shared baseline and then lock down or specialize individual agents with explicit skill lists.

   jsonCopy

   {
     agents: {
       defaults: {
         skills: ["github", "weather"],
       },
       list: [
         { id: "writer" }, // inherits github, weather
         { id: "docs", skills: ["docs-search"] }, // replaces defaults
         { id: "locked-down", skills: [] }, // no skills
       ],
     },
   }

4. 4

   Install and update skills from ClawHub

   ClawHub is the public registry for skills, and the `openclaw skills` and `clawhub` CLIs handle install and sync. Install into your workspace when you want a skill scoped to that project, and update or sync when you need the latest versions.

   bashCopy

   Common flows:
   *   Install a skill into your workspace: 
       *   `openclaw skills install <skill-slug>`
   
   *   Update all installed skills: 
       *   `openclaw skills update --all`
   
   *   Sync (scan + publish updates): 
       *   `clawhub sync --all`

5. 5

   Wire skills to plugins and external binaries

   Plugins can ship skills, and skills can depend on external CLIs or env/config gates. requires` to ensure a skill only loads when its dependencies are present.

   textCopy

   Plugins can ship their own skills by listing `skills` directories in `openclaw.plugin.json` (paths relative to the plugin root). Plugin skills load when the plugin is enabled. Today those directories are merged into the same low-precedence path as `skills.load.extraDirs`, so a same-named bundled, managed, agent, or workspace skill overrides them. You can gate them via `metadata.openclaw.requires.config` on the plugin’s config entry.

6. 6

   Define SKILL.md metadata and gating rules

   md that describes it and encodes gating rules. openclaw` to control OS, required binaries, env vars, and installer hints.

   textCopy

   ---
   name: image-lab
   description: Generate or edit images via a provider-backed image workflow
   metadata:
     {
       "openclaw":
         {
           "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
           "primaryEnv": "GEMINI_API_KEY",
         },
     }
   ---

7. 7

   Configure skills, API keys, and env in openclaw.json

   json` to toggle bundled/managed skills, inject API keys, and pass per-skill config. This keeps secrets out of prompts and lets you override behavior without editing the skill itself.

   jsonCopy

   {
     skills: {
       entries: {
         "image-lab": {
           enabled: true,
           apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
           env: {
             GEMINI_API_KEY: "GEMINI_KEY_HERE",
           },
           config: {
             endpoint: "https://example.invalid",
             model: "nano-pro",
           },
         },
         peekaboo: { enabled: true },
         sag: { enabled: false },
       },
     },
   }

8. 8

   Enable automatic skill reloads with the skills watcher

   md files, you want OpenClaw to pick up changes without restarting everything. The skills watcher bumps the skills snapshot when files change so new metadata and instructions apply on the next turn.

   jsonCopy

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

Configuration

Troubleshooting

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

Frequently asked questions