From 778de55fd8c312b9e8a5cc39cc8d666ff043f21b Mon Sep 17 00:00:00 2001
From: "N. Taylor Mullen" <ntaylormullen@google.com>
Date: Tue, 13 Jan 2026 16:03:45 -0800
Subject: [PATCH] docs(skills): clarify skill directory structure and file
 location (#16532)

---
 docs/cli/skills.md | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/docs/cli/skills.md b/docs/cli/skills.md
index f7ddf003df..5aebf00cb5 100644
--- a/docs/cli/skills.md
+++ b/docs/cli/skills.md
@@ -98,7 +98,20 @@ gemini skills disable my-expertise --scope project
 A skill is a directory containing a `SKILL.md` file at its root. This file uses
 YAML frontmatter for metadata and Markdown for instructions.
 
-### Basic Structure
+### Folder Structure
+
+Skills are self-contained directories. At a minimum, a skill requires a
+`SKILL.md` file, but can include other resources:
+
+```text
+my-skill/
+├── SKILL.md       (Required) Instructions and metadata
+├── scripts/       (Optional) Executable scripts/tools
+├── references/    (Optional) Static documentation and examples
+└── assets/        (Optional) Templates and binary resources
+```
+
+### Basic Structure (SKILL.md)
 
 ```markdown
 ---
@@ -117,6 +130,8 @@ description: <what the skill does and when Gemini should use it>
 
 ### Example: Team Code Reviewer
 
+Create `~/.gemini/skills/code-reviewer/SKILL.md`:
+
 ```markdown
 ---
 name: code-reviewer