Docs: document agent skill allowlists

2026-04-10 16:51:13 +00:00 · 2026-04-03 14:22:55 -04:00
parent 5c3dc40794
commit 1f660bf930
9 changed files with 173 additions and 7 deletions
--- a/docs/cli/agents.md
+++ b/docs/cli/agents.md
@@ -13,6 +13,7 @@ Related:

 - Multi-agent routing: [Multi-Agent Routing](/concepts/multi-agent)
 - Agent workspace: [Agent workspace](/concepts/agent-workspace)
+- Skill visibility config: [Skills config](/tools/skills-config)

 ## Examples

@@ -31,6 +32,11 @@ openclaw agents delete work

 Use routing bindings to pin inbound channel traffic to a specific agent.

+If you also want different visible skills per agent, configure
+`agents.defaults.skills` and `agents.list[].skills` in `openclaw.json`. See
+[Skills config](/tools/skills-config) and
+[Configuration Reference](/gateway/configuration-reference#agentsdefaultsskills).
+
 List bindings:

 ```bash
--- a/docs/concepts/multi-agent.md
+++ b/docs/concepts/multi-agent.md
@@ -27,8 +27,12 @@ Main agent credentials are **not** shared automatically. Never reuse `agentDir`
 across agents (it causes auth/session collisions). If you want to share creds,
 copy `auth-profiles.json` into the other agent's `agentDir`.

-Skills are per-agent via each workspace’s `skills/` folder, with shared skills
-available from `~/.openclaw/skills`. See [Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills).
+Skills are loaded from each agent workspace plus shared roots such as
+`~/.openclaw/skills`, then filtered by the effective agent skill allowlist when
+configured. Use `agents.defaults.skills` for a shared baseline and
+`agents.list[].skills` for per-agent replacement. See
+[Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills) and
+[Skills: agent skill allowlists](/tools/skills#agent-skill-allowlists).

 The Gateway can host **one agent** (default) or **many agents** side-by-side.

--- a/docs/concepts/system-prompt.md
+++ b/docs/concepts/system-prompt.md
@@ -110,6 +110,10 @@ prompt instructs the model to use `read` to load the SKILL.md at the listed
 location (workspace, managed, or bundled). If no skills are eligible, the
 Skills section is omitted.

+Eligibility includes skill metadata gates, runtime environment/config checks,
+and the effective agent skill allowlist when `agents.defaults.skills` or
+`agents.list[].skills` is configured.
+
 ```
 <available_skills>
  <skill>
--- a/docs/gateway/configuration-examples.md
+++ b/docs/gateway/configuration-examples.md
@@ -250,6 +250,7 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
        "openai/gpt-5.2": { alias: "gpt" },
      },
+      skills: ["github", "weather"], // inherited by agents that omit list[].skills
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
@@ -308,12 +309,14 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
      {
        id: "main",
        default: true,
+        // inherits defaults.skills -> github, weather
        thinkingDefault: "high", // per-agent thinking override
        reasoningDefault: "on", // per-agent reasoning visibility
        fastModeDefault: false, // per-agent fast mode
      },
      {
        id: "quick",
+        skills: [], // no skills for this agent
        fastModeDefault: true, // this agent always runs fast
        thinkingDefault: "off",
      },
@@ -462,6 +465,27 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.

 ## Common patterns

+### Shared skill baseline with one override
+
+```json5
+{
+  agents: {
+    defaults: {
+      workspace: "~/.openclaw/workspace",
+      skills: ["github", "weather"],
+    },
+    list: [
+      { id: "main", default: true },
+      { id: "docs", workspace: "~/.openclaw/workspace-docs", skills: ["docs-search"] },
+    ],
+  },
+}
+```
+
+- `agents.defaults.skills` is the shared baseline.
+- `agents.list[].skills` replaces that baseline for one agent.
+- Use `skills: []` when an agent should see no skills.
+
 ### Multi-platform setup

 ```json5
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@@ -818,6 +818,30 @@ Optional repository root shown in the system prompt's Runtime line. If unset, Op
 }
 ```

+### `agents.defaults.skills`
+
+Optional default skill allowlist for agents that do not set
+`agents.list[].skills`.
+
+```json5
+{
+  agents: {
+    defaults: { skills: ["github", "weather"] },
+    list: [
+      { id: "writer" }, // inherits github, weather
+      { id: "docs", skills: ["docs-search"] }, // replaces defaults
+      { id: "locked-down", skills: [] }, // no skills
+    ],
+  },
+}
+```
+
+- Omit `agents.defaults.skills` for unrestricted skills by default.
+- Omit `agents.list[].skills` to inherit the defaults.
+- Set `agents.list[].skills: []` for no skills.
+- A non-empty `agents.list[].skills` list is the final set for that agent; it
+  does not merge with defaults.
+
 ### `agents.defaults.skipBootstrap`

 Disables automatic creation of workspace bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
@@ -1425,6 +1449,7 @@ scripts/sandbox-browser-setup.sh   # optional browser image
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
+        skills: ["docs-search"], // replaces agents.defaults.skills when set
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
@@ -1459,6 +1484,7 @@ scripts/sandbox-browser-setup.sh   # optional browser image
 - `default`: when multiple are set, first wins (warning logged). If none set, first list entry is default.
 - `model`: string form overrides `primary` only; object form `{ primary, fallbacks }` overrides both (`[]` disables global fallbacks). Cron jobs that only override `primary` still inherit default fallbacks unless you set `fallbacks: []`.
 - `params`: per-agent stream params merged over the selected model entry in `agents.defaults.models`. Use this for agent-specific overrides like `cacheRetention`, `temperature`, or `maxTokens` without duplicating the whole model catalog.
+- `skills`: optional per-agent skill allowlist. If omitted, the agent inherits `agents.defaults.skills` when set; an explicit list replaces defaults instead of merging, and `[]` means no skills.
 - `thinkingDefault`: optional per-agent default thinking level (`off | minimal | low | medium | high | xhigh | adaptive`). Overrides `agents.defaults.thinkingDefault` for this agent when no per-message or session override is set.
 - `reasoningDefault`: optional per-agent default reasoning visibility (`on | off | stream`). Applies when no per-message or session reasoning override is set.
 - `fastModeDefault`: optional per-agent default for fast mode (`true | false`). Applies when no per-message or session fast-mode override is set.
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -175,6 +175,33 @@ When validation fails:

  </Accordion>

+  <Accordion title="Restrict skills per agent">
+    Use `agents.defaults.skills` for a shared baseline, then override specific
+    agents with `agents.list[].skills`:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          skills: ["github", "weather"],
+        },
+        list: [
+          { id: "writer" }, // inherits github, weather
+          { id: "docs", skills: ["docs-search"] }, // replaces defaults
+          { id: "locked-down", skills: [] }, // no skills
+        ],
+      },
+    }
+    ```
+
+    - Omit `agents.defaults.skills` for unrestricted skills by default.
+    - Omit `agents.list[].skills` to inherit the defaults.
+    - Set `agents.list[].skills: []` for no skills.
+    - See [Skills](/tools/skills), [Skills config](/tools/skills-config), and
+      the [Configuration Reference](/gateway/configuration-reference#agentsdefaultsskills).
+
+  </Accordion>
+
  <Accordion title="Tune gateway channel health monitoring">
    Control how aggressively the gateway restarts channels that look stale:

--- a/docs/help/faq.md
+++ b/docs/help/faq.md
@@ -946,11 +946,11 @@ for usage/billing and raise limits as needed.

 <AccordionGroup>
  <Accordion title="How do I customize skills without keeping the repo dirty?">
-    Use managed overrides instead of editing the repo copy. Put your changes in `~/.openclaw/skills/<name>/SKILL.md` (or add a folder via `skills.load.extraDirs` in `~/.openclaw/openclaw.json`). Precedence is `<workspace>/skills` > `~/.openclaw/skills` > bundled, so managed overrides win without touching git. Only upstream-worthy edits should live in the repo and go out as PRs.
+    Use managed overrides instead of editing the repo copy. Put your changes in `~/.openclaw/skills/<name>/SKILL.md` (or add a folder via `skills.load.extraDirs` in `~/.openclaw/openclaw.json`). Precedence is `<workspace>/skills` > `~/.openclaw/skills` > bundled, so managed overrides win without touching git. If you need the skill installed globally but only visible to some agents, keep the shared copy in `~/.openclaw/skills` and control visibility with `agents.defaults.skills` and `agents.list[].skills`. Only upstream-worthy edits should live in the repo and go out as PRs.
  </Accordion>

  <Accordion title="Can I load skills from a custom folder?">
-    Yes. Add extra directories via `skills.load.extraDirs` in `~/.openclaw/openclaw.json` (lowest precedence). Default precedence remains: `<workspace>/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` installs into `./skills` by default, which OpenClaw treats as `<workspace>/skills` on the next session.
+    Yes. Add extra directories via `skills.load.extraDirs` in `~/.openclaw/openclaw.json` (lowest precedence). Default precedence remains: `<workspace>/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` installs into `./skills` by default, which OpenClaw treats as `<workspace>/skills` on the next session. If the skill should only be visible to certain agents, pair that with `agents.defaults.skills` or `agents.list[].skills`.
  </Accordion>

  <Accordion title="How can I use different models for different tasks?">
@@ -1030,7 +1030,7 @@ for usage/billing and raise limits as needed.
    openclaw skills update --all
    ```

-    Install the separate `clawhub` CLI only if you want to publish or sync your own skills.
+    Install the separate `clawhub` CLI only if you want to publish or sync your own skills. For shared installs across agents, put the skill under `~/.openclaw/skills` and use `agents.defaults.skills` or `agents.list[].skills` if you want to narrow which agents can see it.

  </Accordion>

@@ -1106,7 +1106,7 @@ for usage/billing and raise limits as needed.
    openclaw skills update --all
    ```

-    Native installs land in the active workspace `skills/` directory. For shared skills across agents, place them in `~/.openclaw/skills/<name>/SKILL.md`. Some skills expect binaries installed via Homebrew; on Linux that means Linuxbrew (see the Homebrew Linux FAQ entry above). See [Skills](/tools/skills) and [ClawHub](/tools/clawhub).
+    Native installs land in the active workspace `skills/` directory. For shared skills across agents, place them in `~/.openclaw/skills/<name>/SKILL.md`. If only some agents should see a shared install, configure `agents.defaults.skills` or `agents.list[].skills`. Some skills expect binaries installed via Homebrew; on Linux that means Linuxbrew (see the Homebrew Linux FAQ entry above). See [Skills](/tools/skills), [Skills config](/tools/skills-config), and [ClawHub](/tools/clawhub).

  </Accordion>

--- a/docs/tools/skills-config.md
+++ b/docs/tools/skills-config.md
@@ -8,7 +8,9 @@ title: "Skills Config"

 # Skills Config

-All skills-related configuration lives under `skills` in `~/.openclaw/openclaw.json`.
+Most skills loader/install configuration lives under `skills` in
+`~/.openclaw/openclaw.json`. Agent-specific skill visibility lives under
+`agents.defaults.skills` and `agents.list[].skills`.

 ```json5
 {
@@ -51,6 +53,35 @@ Examples:
 - Native Nano Banana-style setup: `agents.defaults.imageGenerationModel.primary: "google/gemini-3-pro-image-preview"`
 - Native fal setup: `agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"`

+## Agent skill allowlists
+
+Use agent config when you want the same machine/workspace skill roots, but a
+different visible skill set per agent.
+
+```json5
+{
+  agents: {
+    defaults: {
+      skills: ["github", "weather"],
+    },
+    list: [
+      { id: "writer" }, // inherits defaults -> github, weather
+      { id: "docs", skills: ["docs-search"] }, // replaces defaults
+      { id: "locked-down", skills: [] }, // no skills
+    ],
+  },
+}
+```
+
+Rules:
+
+- `agents.defaults.skills`: shared baseline allowlist for agents that omit
+  `agents.list[].skills`.
+- Omit `agents.defaults.skills` to leave skills unrestricted by default.
+- `agents.list[].skills`: explicit final skill set for that agent; it does not
+  merge with defaults.
+- `agents.list[].skills: []`: expose no skills for that agent.
+
 ## Fields

 - Built-in skill roots always include `~/.openclaw/skills`, `~/.agents/skills`,
@@ -65,6 +96,10 @@ Examples:
  This only affects **skill installs**; the Gateway runtime should still be Node
  (Bun not recommended for WhatsApp/Telegram).
 - `entries.<skillKey>`: per-skill overrides.
+- `agents.defaults.skills`: optional default skill allowlist inherited by agents
+  that omit `agents.list[].skills`.
+- `agents.list[].skills`: optional per-agent final skill allowlist; explicit
+  lists replace inherited defaults instead of merging.

 Per-skill fields:

--- a/docs/tools/skills.md
+++ b/docs/tools/skills.md
@@ -43,6 +43,42 @@ 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.

+## Agent skill allowlists
+
+Skill **location** and skill **visibility** are separate controls.
+
+- Location/precedence decides which copy of a same-named skill wins.
+- Agent allowlists decide which visible skills an agent can actually use.
+
+Use `agents.defaults.skills` for a shared baseline, then override per agent with
+`agents.list[].skills`:
+
+```json5
+{
+  agents: {
+    defaults: {
+      skills: ["github", "weather"],
+    },
+    list: [
+      { id: "writer" }, // inherits github, weather
+      { id: "docs", skills: ["docs-search"] }, // replaces defaults
+      { id: "locked-down", skills: [] }, // no skills
+    ],
+  },
+}
+```
+
+Rules:
+
+- Omit `agents.defaults.skills` for unrestricted skills by default.
+- Omit `agents.list[].skills` to inherit `agents.defaults.skills`.
+- Set `agents.list[].skills: []` for no skills.
+- A non-empty `agents.list[].skills` list is the final set for that agent; it
+  does not merge with defaults.
+
+OpenClaw applies the effective agent skill set across prompt building, skill
+slash-command discovery, sandbox sync, and skill snapshots.
+
 ## Plugins + skills

 Plugins can ship their own skills by listing `skills` directories in
@@ -267,6 +303,10 @@ OpenClaw snapshots the eligible skills **when a session starts** and reuses that

 Skills can also refresh mid-session when the skills watcher is enabled or when a new eligible remote node appears (see below). Think of this as a **hot reload**: the refreshed list is picked up on the next agent turn.

+If the effective agent skill allowlist changes for that session, OpenClaw
+refreshes the snapshot so the visible skills stay aligned with the current
+agent.
+
 ## Remote macOS nodes (Linux gateway)

 If the Gateway is running on Linux but a **macOS node** is connected **with `system.run` allowed** (Exec approvals security not set to `deny`), OpenClaw can treat macOS-only skills as eligible when the required binaries are present on that node. The agent should execute those skills via the `exec` tool with `host=node`.