docs: document .agents/skills alias and discovery precedence (#19166)

Author: kevmoo

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,22 +75,23 @@ 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
 
 # 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

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`