From d1ca8c0c80b45ae14e884336eaeefe065ef6f08a Mon Sep 17 00:00:00 2001
From: Kevin Moore <kevmoo@users.noreply.github.com>
Date: Sun, 15 Feb 2026 20:18:36 -0800
Subject: [PATCH] docs: document .agents/skills alias and discovery precedence
 (#19166)

---
 docs/cli/skills.md                           | 23 +++++++++++++-------
 docs/cli/tutorials/skills-getting-started.md |  5 +++--
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/docs/cli/skills.md b/docs/cli/skills.md
index c6ef9f75ff..d3e8d4e84f 100644
--- a/docs/cli/skills.md
+++ b/docs/cli/skills.md
@@ -35,16 +35,22 @@ the full instructions and resources required to complete the task using the
 
 Gemini CLI discovers skills from three primary locations:
 
-1.  **Workspace Skills** (`.gemini/skills/`): Workspace-specific skills that are
-    typically committed to version control and shared with the team.
-2.  **User Skills** (`~/.gemini/skills/`): Personal skills available across all
-    your workspaces.
+1.  **Workspace Skills**: Located in `.gemini/skills/` or the `.agents/skills/`
+    alias. Workspace skills are typically committed to version control and
+    shared with the team.
+2.  **User Skills**: Located in `~/.gemini/skills/` or the `~/.agents/skills/`
+    alias. These are personal skills available across all your workspaces.
 3.  **Extension Skills**: Skills bundled within installed
     [extensions](../extensions/index.md).
 
 **Precedence:** If multiple skills share the same name, higher-precedence
 locations override lower ones: **Workspace > User > Extension**.
 
+Within the same tier (user or workspace), the `.agents/skills/` alias takes
+precedence over the `.gemini/skills/` directory. This generic alias provides an
+intuitive path for managing agent-specific expertise that remains compatible
+across different AI agent tools.
+
 ## Managing Skills
 
 ### In an Interactive Session
@@ -69,14 +75,15 @@ The `gemini skills` command provides management utilities:
 gemini skills list
 
 # Link agent skills from a local directory via symlink
-# Discovers skills (SKILL.md or */SKILL.md) and creates symlinks in ~/.gemini/skills (user)
+# Discovers skills (SKILL.md or */SKILL.md) and creates symlinks in ~/.gemini/skills
+# (or ~/.agents/skills)
 gemini skills link /path/to/my-skills-repo
 
-# Link to the workspace scope (.gemini/skills)
+# Link to the workspace scope (.gemini/skills or .agents/skills)
 gemini skills link /path/to/my-skills-repo --scope workspace
 
 # Install a skill from a Git repository, local directory, or zipped skill file (.skill)
-# Uses the user scope by default (~/.gemini/skills)
+# Uses the user scope by default (~/.gemini/skills or ~/.agents/skills)
 gemini skills install https://github.com/user/repo.git
 gemini skills install /path/to/local/skill
 gemini skills install /path/to/local/my-expertise.skill
@@ -84,7 +91,7 @@ gemini skills install /path/to/local/my-expertise.skill
 # Install a specific skill from a monorepo or subdirectory using --path
 gemini skills install https://github.com/my-org/my-skills.git --path skills/frontend-design
 
-# Install to the workspace scope (.gemini/skills)
+# Install to the workspace scope (.gemini/skills or .agents/skills)
 gemini skills install /path/to/skill --scope workspace
 
 # Uninstall a skill by name
diff --git a/docs/cli/tutorials/skills-getting-started.md b/docs/cli/tutorials/skills-getting-started.md
index 40d4e678cb..2614a679ef 100644
--- a/docs/cli/tutorials/skills-getting-started.md
+++ b/docs/cli/tutorials/skills-getting-started.md
@@ -68,8 +68,9 @@ Skills can bundle resources like scripts.
 
 ## How to verify discovery
 
-Gemini CLI automatically discovers skills in the `.gemini/skills` directory.
-Check that it found your new skill.
+Gemini CLI automatically discovers skills in the `.gemini/skills` directory. You
+can also use `.agents/skills` as a more generic alternative. Check that it found
+your new skill.
 
 **Command:** `/skills list`