docs: clarify per-agent vs shared skills

docs/concepts/multi-agent.md

@@ -17,6 +17,9 @@ An **agent** is a fully scoped brain with its own:
 - **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config.
 - **Session store** (chat history + routing state) under `~/.clawdbot/agents/<agentId>/sessions`.
 
+Skills are per-agent via each workspace’s `skills/` folder, with shared skills
+available from `~/.clawdbot/skills`. See [Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills).
+
 The Gateway can host **one agent** (default) or **many agents** side-by-side.
 
 ## Paths (quick map)

docs/tools/skills.md

@@ -23,6 +23,19 @@ If a skill name conflicts, precedence is:
 Additionally, you can configure extra skill folders (lowest precedence) via
 `skills.load.extraDirs` in `~/.clawdbot/clawdbot.json`.
 
+## Per-agent vs shared skills
+
+In **multi-agent** setups, each agent has its own workspace. That means:
+
+- **Per-agent skills** live in `<workspace>/skills` for that agent only.
+- **Shared skills** live in `~/.clawdbot/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 managed/local, then bundled.
+
 ## Format (AgentSkills + Pi-compatible)
 
 `SKILL.md` must include at least: