From 0e3d47273fe9a8bc749a6e928b8e7d9f102c1956 Mon Sep 17 00:00:00 2001
From: Andrey Nering <andreynering@users.noreply.github.com>
Date: Tue, 24 Mar 2026 15:33:49 -0300
Subject: [PATCH] docs(readme): update skill docs with updates and new paths

---
 README.md | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 46d5da5413ac3e30aaec094dbfb12d832d8647d5..183104803429ed200aeca2ac89cac76178d741f2 100644
--- a/README.md
+++ b/README.md
@@ -388,11 +388,23 @@ extending agent capabilities with reusable skill packages. Skills are folders
 containing a `SKILL.md` file with instructions that Crush can discover and
 activate on demand.
 
-Skills are discovered from:
-
-- `~/.config/crush/skills/` on Unix (default, can be overridden with `CRUSH_SKILLS_DIR`)
-- `%LOCALAPPDATA%\crush\skills\` on Windows (default, can be overridden with `CRUSH_SKILLS_DIR`)
-- Additional paths configured via `options.skills_paths`
+The global paths we looks for skills are:
+
+* `$CRUSH_SKILLS_DIR`
+* `$XDG_CONFIG_HOME/agents/skills` or `~/.config/agents/skills/`
+* `$XDG_CONFIG_HOME/crush/skills` or `~/.config/crush/skills/`
+* On Windows, we _also_ look at
+  * `%LOCALAPPDATA%\agents\skills\` or `%USERPROFILE%\AppData\Local\agents\skills\`
+  * `%LOCALAPPDATA%\crush\skills\` or `%USERPROFILE%\AppData\Local\crush\skills\`
+* Additional paths configured via `options.skills_paths`
+
+On top of that, we _also_ load skills in your project from the following
+relative paths:
+
+* `.agents/skills`
+* `.crush/skills`
+* `.claude/skills`
+* `.cursor/skills`
 
 ```jsonc
 {