From 72f0733d98b66049c47954ca245c9b8dcc872e3f Mon Sep 17 00:00:00 2001
From: g-samroberts <158088236+g-samroberts@users.noreply.github.com>
Date: Wed, 28 Jan 2026 08:15:53 -0800
Subject: [PATCH] Fix docs-writer skill issues (#17734)

---
 .gemini/skills/docs-writer/SKILL.md                  | 1 -
 .gemini/skills/docs-writer/references/style-guide.md | 3 ++-
 GEMINI.md                                            | 5 +++--
 docs/cli/skills.md                                   | 5 +++--
 4 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/.gemini/skills/docs-writer/SKILL.md b/.gemini/skills/docs-writer/SKILL.md
index e2770d0bb8..41bbb45775 100644
--- a/.gemini/skills/docs-writer/SKILL.md
+++ b/.gemini/skills/docs-writer/SKILL.md
@@ -1,4 +1,3 @@
-
 ---
 name: docs-writer
 description:
diff --git a/.gemini/skills/docs-writer/references/style-guide.md b/.gemini/skills/docs-writer/references/style-guide.md
index c8eab11ae8..d3d219378a 100644
--- a/.gemini/skills/docs-writer/references/style-guide.md
+++ b/.gemini/skills/docs-writer/references/style-guide.md
@@ -33,7 +33,8 @@
   a natural tone.
 - **Simple vocabulary:** Use common words. Define technical terms when
   necessary.
-- **Conciseness:** Keep sentences short and focused.
+- **Conciseness:** Keep sentences short and focused, but don't omit
+  helpful information.
 - **"Please":** Avoid using the word "please."
 
 ## IV. Procedures and steps
diff --git a/GEMINI.md b/GEMINI.md
index ed9ba8ac25..000e71e3a3 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -72,7 +72,8 @@ powerful tool for developers.
 
 ## Documentation
 
+- Always use the `docs-writer` skill when you are asked to write, edit, or
+  review any documentation.
+- Documentation is located in the `docs/` directory.
 - Suggest documentation updates when code changes render existing documentation
   obsolete or incomplete.
-- Located in the `docs/` directory.
-- Use the `docs-writer` skill.
diff --git a/docs/cli/skills.md b/docs/cli/skills.md
index 0b001b017e..3b3519121c 100644
--- a/docs/cli/skills.md
+++ b/docs/cli/skills.md
@@ -91,8 +91,9 @@ gemini skills disable my-expertise --scope workspace
 
 ## Creating a Skill
 
-A skill is a directory containing a `SKILL.md` file at its root. This file uses
-YAML frontmatter for metadata and Markdown for instructions.
+A skill is a directory containing a `SKILL.md` file at its root. This file
+serves as the entry point for your skill and uses YAML frontmatter for metadata
+and Markdown for instructions.
 
 ### Folder Structure