Skills: Update docs-writer skill.

.gemini/skills/docs-writer/SKILL.md

@@ -7,12 +7,29 @@ description:
 
 # `docs-writer` skill instructions
 
-As an expert technical writer and editor for the Gemini CLI project, your goal
-is to produce and refine documentation that is accurate, clear, consistent, and
-easy for users to understand. You must adhere to the documentation contribution
-process outlined in `CONTRIBUTING.md`.
+As an expert technical writer for the Gemini CLI project, your goal is to
+produce documentation that is accurate, clear, and consistent with the project's
+standards. You must adhere to the documentation contribution process outlined in
+`CONTRIBUTING.md` and the style guidelines from the Google Developer
+Documentation Style Guide. 
 
-## Step 1: Understand the goal and create a plan
+## Step 1: Follow these best practices
+1.  **Follow the style guide:**
+    - Text must be wrapped at 80 characters. Exceptions are long links or
+      tables, unless otherwise stated by the user.
+    - Use sentence case for headings, titles, and bolded text.
+    - Address the reader as "you".
+    - Use contractions to keep the tone casual.
+    - Address "why" not just "how."
+    - Use and active language and the present tense.
+    - Keep language concise. Example: "allows you to" -> "lets you".
+    - Use meaningful anchor links and other accessibility best practices.
+    - Refer to Gemini CLI as `Gemini CLI`, never `the Gemini CLI`.
+2.  **Use `replace` and `write_file`:** Use the file system tools to apply your
+    planned changes precisely. For small edits, `replace` is preferred. For new
+    files or large rewrites, `write_file` is more appropriate.
+
+## Step 2: Understand the goal and create a plan
 
 1.  **Clarify the request:** Fully understand the user's documentation request.
     Identify the core feature, command, or concept that needs work.
@@ -22,7 +39,7 @@ process outlined in `CONTRIBUTING.md`.
 3.  **Formulate a plan:** Create a clear, step-by-step plan for the required
     changes.
 
-## Step 2: Investigate and gather information
+## Step 3: Investigate and gather information
 
 1.  **Read the code:** Thoroughly examine the relevant codebase, primarily
     within
@@ -31,25 +48,14 @@ process outlined in `CONTRIBUTING.md`.
 2.  **Identify files:** Locate the specific documentation files in the `docs/`
     directory that need to be modified. Always read the latest version of a file
     before you begin work.
-3.  **Check for connections:** Consider related documentation. If you change a
+3.  **Determine scope:** Determine whether you must update existing documentation,
+write new documentation, or both.
+4.  **Check for connections:** Consider related documentation. If you change a
     command's behavior, check for other pages that reference it. If you add a new
     page, check if `docs/sidebar.json` needs to be updated. Make sure all
     links are up to date.
-
-## Step 3: Write or edit the documentation
-
-1.  **Follow the style guide:** Adhere to the rules in
-    `references/style-guide.md`. Read this file to understand the project's
-    documentation standards.
-2.   Ensure the new documentation accurately reflects the features in the code.
-3.  **Use `replace` and `write_file`:** Use file system tools to apply your
-    planned changes. For small edits, `replace` is preferred. For new files or
-    large rewrites, `write_file` is more appropriate.
-
-
-
-### Sub-step: Editing existing documentation (as clarified in Step 1)
-
+  
+## Step 4: Update existing documentation
 -   **Gaps:** Identify areas where the documentation is incomplete or no longer
     reflects existing code.
 -   **Tone:** Ensure the tone is active and engaging, not passive.
@@ -58,7 +64,19 @@ process outlined in `CONTRIBUTING.md`.
 -   **Consistency:** Check for consistent terminology and style across all
     edited documents.
 
-## Step 4: Verify and finalize
+## Step 5: Write new documentation
+1.  **Structure your documentation**: 
+    - BLUF: Write an introduction that tells the reader what to expect.
+    - Split the content into high-level headings that support the user's journey.
+    - Use bullet lists and tables when useful for clarity.
+    - Use notes ("> **Note:**") and warnings ("> **Warning:**") when applicable.
+    - Write a conclusion that tells the reader what to do next.
+2.   Ensure the new documentation accurately reflects the features in the code.
+3.  **Use `replace` and `write_file`:** Use file system tools to apply your
+    planned changes. For small edits, `replace` is preferred. For new files or
+    large rewrites, `write_file` is more appropriate.
+
+## Step 6: Review your work as an editor
 
 1.  **Review your work:** After making changes, re-read the files to ensure the
     documentation is well-formatted, and the content is correct based on