diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md
index 56a0521c8..8a3323418 100644
--- a/docs/concepts/multi-agent.md
+++ b/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)
diff --git a/docs/tools/skills.md b/docs/tools/skills.md
index 784028ae8..a5ab6ccef 100644
--- a/docs/tools/skills.md
+++ b/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: