openclaw/docs/tools/skills-config.md

title, sidebarTitle, summary, read_when

title	sidebarTitle	summary	read_when
Skills config	Skills config	Full reference for the skills.* config schema, agent allowlists, workshop settings, and sandbox env var handling.	Configuring skill loading, install, or gating behavior Setting per-agent skill visibility Adjusting Skill Workshop limits or approval policy

Most skills configuration lives under skills in ~/.openclaw/openclaw.json. Agent-specific visibility lives under agents.defaults.skills and agents.list[].skills.

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
      allowUploadedArchives: false,
    },
    workshop: {
      autonomous: { enabled: false },
      approvalPolicy: "pending",
      maxPending: 50,
      maxSkillBytes: 40000,
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

For built-in image generation, use `agents.defaults.imageGenerationModel` plus the core `image_generate` tool instead of `skills.entries`. Skill entries are for custom or third-party skill workflows only.

Loading (skills.load)

Additional skill directories to scan, at the lowest precedence (after bundled and plugin skills). Paths are expanded with `~` support. Trusted real target directories that symlinked skill folders may resolve into, even when the symlink lives outside the configured root. Use this for intentional sibling-repo layouts such as `/skills/manager -> ~/Projects/manager/skills`. Keep this list narrow — do not point at broad roots like `~` or `~/Projects`. Watch skill folders and refresh the skills snapshot when `SKILL.md` files change. Covers nested files under grouped skill roots. Debounce window for skill watcher events in milliseconds.

Install (skills.install)

Prefer Homebrew installers when `brew` is available. Node package manager preference for skill installs. This only affects skill installs — the Gateway runtime should still use Node (Bun is not recommended for WhatsApp/Telegram). Use `openclaw setup --node-manager` for npm, pnpm, or bun; set `"yarn"` manually for Yarn-backed skill installs. Allow trusted `operator.admin` Gateway clients to install private zip archives staged through `skills.upload.*`. Normal ClawHub installs do not need this setting.

Bundled skill allowlist

Optional allowlist for **bundled** skills only. When set, only bundled skills in the list are eligible. Managed, agent-level, and workspace skills are unaffected.

Per-skill entries (skills.entries)

Keys under entries match the skill name by default. If a skill defines metadata.openclaw.skillKey, use that key instead. Quote hyphenated names (JSON5 allows quoted keys).

`false` disables the skill even when bundled or installed. The `coding-agent` bundled skill is opt-in — set it to `true` and ensure one of `claude`, `codex`, `opencode`, or another supported CLI is installed and authenticated. Convenience field for skills that declare `metadata.openclaw.primaryEnv`. Supports a plaintext string or a SecretRef: `{ source: "env", provider: "default", id: "VAR_NAME" }`. Environment variables injected for the agent run. Only injected when the variable is not already set in the process. Optional bag for custom per-skill configuration fields.

Agent allowlists (agents)

Use agent config when you want the same machine/workspace skill roots but a different visible skill set per agent.

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

Shared baseline allowlist inherited by agents that omit `agents.list[].skills`. Omit entirely to leave skills unrestricted by default. Explicit final skill set for that agent. Explicit lists **replace** inherited defaults — they do not merge. Set to `[]` to expose no skills for that agent.

Workshop (skills.workshop)

When `true`, agents can create pending proposals from durable conversation signals after successful turns. User-prompted skill creation always goes through Skill Workshop regardless of this setting. `pending` requires operator approval before agent-initiated apply, reject, or quarantine. `auto` allows those actions without approval. Maximum pending and quarantined proposals retained per workspace. Maximum proposal body size in bytes. Proposal descriptions are hard-capped at 160 bytes because they appear in discovery and listing output.

Symlinked skill roots

By default, workspace, project-agent, extra-dir, and bundled skill roots are containment boundaries. A symlinked skill folder under <workspace>/skills that resolves outside the root is skipped with a log message.

To allow an intentional symlink layout, declare the trusted target:

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

With this config, <workspace>/skills/manager -> ~/Projects/manager/skills is accepted after realpath resolution. extraDirs scans the sibling repo directly; allowSymlinkTargets preserves the symlinked path for existing layouts.

Managed ~/.openclaw/skills and personal ~/.agents/skills directories already accept skill-directory symlinks (per-skill SKILL.md containment still applies).

Sandboxed skills and env vars

`skills.entries..env` and `apiKey` apply to **host** runs only. Inside a sandbox they have no effect — a skill that depends on `GEMINI_API_KEY` will fail with `apiKey not configured` unless the sandbox is given the variable separately.

Pass secrets into a Docker sandbox with:

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          env: { GEMINI_API_KEY: "your-key-here" },
        },
      },
    },
  },
}

Users with Docker daemon access can inspect `sandbox.docker.env` values through Docker metadata. Use a mounted secret file, a custom image, or another delivery path when that exposure is not acceptable.

Loading order reminder

workspace/skills      (highest)
workspace/.agents/skills
~/.agents/skills
~/.openclaw/skills
bundled skills
skills.load.extraDirs (lowest)

Changes to skills and config take effect on the next new session when the watcher is enabled, or on the next agent turn when the watcher detects a change.

Related

What skills are, loading order, gating, and SKILL.md format. Authoring custom workspace skills. Proposal queue for agent-drafted skills. Native slash-command catalog and chat directives.