Docs: document skill source precedence

docs/tools/skills-config.md

@@ -53,8 +53,10 @@ Examples:
 
 ## Fields
 
+- Built-in skill roots always include `~/.openclaw/skills`, `~/.agents/skills`,
+  `<workspace>/.agents/skills`, and `<workspace>/skills`.
 - `allowBundled`: optional allowlist for **bundled** skills only. When set, only
-  bundled skills in the list are eligible (managed/workspace skills unaffected).
+  bundled skills in the list are eligible (managed, agent, and workspace skills unaffected).
 - `load.extraDirs`: additional skill directories to scan (lowest precedence).
 - `load.watch`: watch skill folders and refresh the skills snapshot (default: true).
 - `load.watchDebounceMs`: debounce for skill watcher events in milliseconds (default: 250).
@@ -75,6 +77,9 @@ Per-skill fields:
 
 - Keys under `entries` map to the skill name by default. If a skill defines
   `metadata.openclaw.skillKey`, use that key instead.
+- Load precedence is `<workspace>/skills` → `<workspace>/.agents/skills` →
+  `~/.agents/skills` → `~/.openclaw/skills` → bundled skills →
+  `skills.load.extraDirs`.
 - Changes to skills are picked up on the next agent turn when the watcher is enabled.
 
 ### Sandboxed skills + env vars

docs/tools/skills.md

@@ -12,37 +12,44 @@ OpenClaw uses **[AgentSkills](https://agentskills.io)-compatible** skill folders
 
 ## Locations and precedence
 
-Skills are loaded from **three** places:
+OpenClaw loads skills from these sources:
 
-1. **Bundled skills**: shipped with the install (npm package or OpenClaw.app)
-2. **Managed/local skills**: `~/.openclaw/skills`
-3. **Workspace skills**: `<workspace>/skills`
+1. **Extra skill folders**: configured with `skills.load.extraDirs`
+2. **Bundled skills**: shipped with the install (npm package or OpenClaw.app)
+3. **Managed/local skills**: `~/.openclaw/skills`
+4. **Personal agent skills**: `~/.agents/skills`
+5. **Project agent skills**: `<workspace>/.agents/skills`
+6. **Workspace skills**: `<workspace>/skills`
 
 If a skill name conflicts, precedence is:
 
-`<workspace>/skills` (highest) → `~/.openclaw/skills` → bundled skills (lowest)
-
-Additionally, you can configure extra skill folders (lowest precedence) via
-`skills.load.extraDirs` in `~/.openclaw/openclaw.json`.
+`<workspace>/skills` (highest) → `<workspace>/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled skills → `skills.load.extraDirs` (lowest)
 
 ## 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.
+- **Project agent skills** live in `<workspace>/.agents/skills` and apply to
+  that workspace before the normal workspace `skills/` folder.
+- **Personal agent skills** live in `~/.agents/skills` and apply across
+  workspaces on that machine.
 - **Shared skills** live in `~/.openclaw/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.
+applies: workspace wins, then project agent skills, then personal agent skills,
+then managed/local, then bundled, then extra dirs.
 
 ## Plugins + skills
 
 Plugins can ship their own skills by listing `skills` directories in
 `openclaw.plugin.json` (paths relative to the plugin root). Plugin skills load
-when the plugin is enabled and participate in the normal skill precedence rules.
+when the plugin is enabled. Today those directories are merged into the same
+low-precedence path as `skills.load.extraDirs`, so a same-named bundled,
+managed, agent, or workspace skill overrides them.
 You can gate them via `metadata.openclaw.requires.config` on the plugin’s config
 entry. See [Plugins](/tools/plugin) for discovery/config and [Tools](/tools) for the
 tool surface those skills teach.