From 1f660bf9301ecf89ad8395d81117d2d22d6e6be1 Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Fri, 3 Apr 2026 14:22:55 -0400 Subject: [PATCH] Docs: document agent skill allowlists --- docs/cli/agents.md | 6 ++++ docs/concepts/multi-agent.md | 8 +++-- docs/concepts/system-prompt.md | 4 +++ docs/gateway/configuration-examples.md | 24 +++++++++++++++ docs/gateway/configuration-reference.md | 26 ++++++++++++++++ docs/gateway/configuration.md | 27 +++++++++++++++++ docs/help/faq.md | 8 ++--- docs/tools/skills-config.md | 37 ++++++++++++++++++++++- docs/tools/skills.md | 40 +++++++++++++++++++++++++ 9 files changed, 173 insertions(+), 7 deletions(-) diff --git a/docs/cli/agents.md b/docs/cli/agents.md index 5bdc8a68bf2..320b7f1e136 100644 --- 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 diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md index 62ac53634a0..2614f05b6b1 100644 --- 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. diff --git a/docs/concepts/system-prompt.md b/docs/concepts/system-prompt.md index a1d1b482fb2..eaf7dde50fe 100644 --- 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. + ``` diff --git a/docs/gateway/configuration-examples.md b/docs/gateway/configuration-examples.md index 6087ba64d36..fe9d9edd067 100644 --- 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 diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index bf9db746e2c..6a2137cbb47 100644 --- 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. diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 9ade239ff89..6e1669a4af2 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -175,6 +175,33 @@ When validation fails: + + 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). + + + Control how aggressively the gateway restarts channels that look stale: diff --git a/docs/help/faq.md b/docs/help/faq.md index 5cf6e13b924..fc534bf1de6 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -946,11 +946,11 @@ for usage/billing and raise limits as needed. - Use managed overrides instead of editing the repo copy. Put your changes in `~/.openclaw/skills//SKILL.md` (or add a folder via `skills.load.extraDirs` in `~/.openclaw/openclaw.json`). Precedence is `/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//SKILL.md` (or add a folder via `skills.load.extraDirs` in `~/.openclaw/openclaw.json`). Precedence is `/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. - Yes. Add extra directories via `skills.load.extraDirs` in `~/.openclaw/openclaw.json` (lowest precedence). Default precedence remains: `/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` installs into `./skills` by default, which OpenClaw treats as `/skills` on the next session. + Yes. Add extra directories via `skills.load.extraDirs` in `~/.openclaw/openclaw.json` (lowest precedence). Default precedence remains: `/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` installs into `./skills` by default, which OpenClaw treats as `/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`. @@ -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. @@ -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//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//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). diff --git a/docs/tools/skills-config.md b/docs/tools/skills-config.md index 28a88f1a865..4d958c7f34f 100644 --- 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.`: 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: diff --git a/docs/tools/skills.md b/docs/tools/skills.md index c2fa3e24918..c0d15a70090 100644 --- 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`.