From 68e275fd4756b4c24e3d148828d3c5ac0da3bb0c Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Fri, 27 Feb 2026 09:17:06 -0800
Subject: [PATCH] docs(skills): add normalized capability shape and mappings

---
 docs/tools/skills.md | 52 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/docs/tools/skills.md b/docs/tools/skills.md
index d74358a8913..b044ebaf1d5 100644
--- a/docs/tools/skills.md
+++ b/docs/tools/skills.md
@@ -328,6 +328,58 @@ Fields under `metadata.openclaw`:
 
   No capabilities declared = read-only, model-only skill. Community skills with undeclared capabilities that attempt to use dangerous tools will be blocked at runtime. See [Tool enforcement matrix](#tool-enforcement-matrix) below and [Security](/gateway/security) for full details.
 
+### Capability shape and normalization
+
+OpenClaw accepts both styles under the same `capabilities` key:
+
+Flat list:
+
+```json
+{
+  "openclaw": {
+    "capabilities": ["shell", "network", "sessions"]
+  }
+}
+```
+
+Two-layer object with optional constraints:
+
+```jsonc
+{
+  "openclaw": {
+    "capabilities": {
+      "shell": { "mode": "restricted", "allow": ["git", "gh"] }, // key/value constraints
+      "network": { "web_search": true, "web_fetch": true }, // granular switches
+      "sessions": { "maxDepth": 2 }, // future-safe metadata
+    },
+  },
+}
+```
+
+Array-of-objects also works:
+
+```json
+{
+  "openclaw": {
+    "capabilities": [
+      { "type": "network.search", "constraints": { "provider": "brave" } },
+      { "name": "shell.exec", "constraints": { "mode": "restricted" } }
+    ]
+  }
+}
+```
+
+Normalization behavior:
+
+- OpenClaw normalizes external naming to canonical values (`shell`, `filesystem`, `network`, `browser`, `sessions`, `messaging`, `scheduling`).
+- Examples:
+  - `web_fetch`, `web_search`, `webfetch` -> `network`
+  - `terminal`, `bash`, `exec` -> `shell`
+  - `subagent`, `sessions_spawn` -> `sessions`
+  - `message` -> `messaging`
+  - `cron`, `schedule` -> `scheduling`
+- Constraints are currently advisory metadata (not enforced by the runtime gate yet). Keep them simple key/value pairs for forward compatibility.
+
 - `requires.bins` — list; each must exist on `PATH`.
 - `requires.anyBins` — list; at least one must exist on `PATH`.
 - `requires.env` — list; env var must exist **or** be provided in config.