Update docs-writer skill for editing and add style guide for reference. (#17669)

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

@@ -1,63 +1,72 @@
+
 ---
 name: docs-writer
 description:
-  Use this skill when asked to write documentation (`/docs` directory)
-  for Gemini CLI.
+  Use this skill for writing, reviewing, and editing documentation (`/docs`
+  directory or any .md file) for Gemini CLI.
 ---
 
 # `docs-writer` skill instructions
 
-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.
+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`.
 
 ## Step 1: 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 to be documented.
-2.  **Ask questions:** If the request is ambiguous or lacks detail, ask
-    clarifying questions. Don't invent or assume. It's better to ask than to
-    write incorrect documentation.
+    Identify the core feature, command, or concept that needs work.
+2.  **Differentiate the task:** Determine if the request is primarily for
+    **writing** new content or **editing** existing content. If the request is
+    ambiguous (e.g., "fix the docs"), ask the user for clarification.
 3.  **Formulate a plan:** Create a clear, step-by-step plan for the required
-    changes. If requested or necessary, store this plan in a temporary file or
-    a file identified by the user.
+    changes.
 
 ## Step 2: Investigate and gather information
 
-1.  **Read the code:** Thoroughly examine the relevant codebase, primarily within
-    the `packages/` directory, to ensure your writing is backed by the
-    implementation.
+1.  **Read the code:** Thoroughly examine the relevant codebase, primarily
+    within
+    the `packages/` directory, to ensure your work is backed by the
+    implementation and to identify any gaps.
 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 to edit it.
-3.  **Check for connections:** Consider related documentation. If you add a new
-    page, check if `docs/sidebar.json` needs to be updated. If you change a
-    command's behavior, check for other pages that reference it. Make sure links
-    in these pages are up to date.
+    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
+    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: Draft the documentation
+## Step 3: Write or edit the documentation
 
-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 more casual.
-    - Use simple, direct, and active language and the present tense.
-    - Keep paragraphs short and focused.
-    - Always 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.
+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)
+
+-   **Gaps:** Identify areas where the documentation is incomplete or no longer
+    reflects existing code.
+-   **Tone:** Ensure the tone is active and engaging, not passive.
+-   **Clarity:** Correct awkward wording, spelling, and grammar. Rephrase
+    sentences to make them easier for users to understand.
+-   **Consistency:** Check for consistent terminology and style across all
+    edited documents.
 
 ## Step 4: Verify and finalize
 
 1.  **Review your work:** After making changes, re-read the files to ensure the
-    documentation is well-formatted, content is correct and based on existing
-    code, and that all new links are valid.
-2.  **Offer to run npm format:** Once all changes are complete and the user
-    confirms they have no more requests, offer to run the project's formatting
-    script to ensure consistency. Propose the following command:
+    documentation is well-formatted, and the content is correct based on
+    existing code.
+2.  **Link verification:** Verify the validity of all links in the new content.
+    Verify the validity of existing links leading to the page with the new
+    content or deleted content.
+2.  **Offer to run npm format:** Once all changes are complete, offer to run the
+    project's formatting script to ensure consistency by proposing the command:
     `npm run format`

.gemini/skills/docs-writer/references/style-guide.md

@@ -0,0 +1,95 @@
+# Documentation style guide
+
+## I. Core principles
+
+1.  **Clarity:** Write for easy understanding. Prioritize clear, direct, and
+    simple language.
+2.  **Consistency:** Use consistent terminology, formatting, and style
+    throughout the documentation.
+3.  **Accuracy:** Ensure all information is technically correct and up-to-date.
+4.  **Accessibility:** Design documentation to be usable by everyone. Focus on
+    semantic structure, clear link text, and image alternatives.
+5.  **Global audience:** Write in standard US English. Avoid slang, idioms, and
+    cultural references.
+6.  **Prescriptive:** Guide the reader by recommending specific actions and
+    paths, especially for complex tasks.
+
+## II. Voice and tone
+
+- **Professional yet friendly:** Maintain a helpful, knowledgeable, and
+  conversational tone without being frivolous.
+- **Direct:** Get straight to the point. Keep paragraphs short and focused.
+- **Second person:** Address the reader as "you."
+- **Present tense:** Use the present tense to describe functionality (e.g., "The
+  API returns a JSON object.").
+- **Avoid:** Jargon, slang, marketing hype, and overly casual language.
+
+## III. Language and grammar
+
+- **Active voice:** Prefer active voice over passive voice.
+  - _Example:_ "The system sends a notification." (Not: "A notification is sent
+    by the system.")
+- **Contractions:** Use common contractions (e.g., "don't," "it's") to maintain
+  a natural tone.
+- **Simple vocabulary:** Use common words. Define technical terms when
+  necessary.
+- **Conciseness:** Keep sentences short and focused.
+- **"Please":** Avoid using the word "please."
+
+## IV. Procedures and steps
+
+- Start each step with an imperative verb (e.g., "Connect to the database").
+- Number steps sequentially.
+- Introduce lists of steps with a complete sentence.
+- Put conditions before instructions, not after.
+- Provide clear context for where the action takes place (e.g., "In the
+  administration console...").
+- Indicate optional steps clearly (e.g., "Optional: ...").
+
+## V. Formatting and punctuation
+
+- **Text wrap:** Wrap all text at 80 characters, with exceptions for long links
+  or tables.
+- **Headings, titles, and bold text:** Use sentence case. Structure headings
+  hierarchically.
+- **Lists:** Use numbered lists for sequential steps and bulleted lists for all
+  other lists. Keep list items parallel in structure.
+- **Serial comma:** Use the serial comma (e.g., "one, two, and three").
+- **Punctuation:** Use standard American punctuation. Place periods inside
+  quotation marks.
+- **Dates:** Use unambiguous date formatting (e.g., "January 22, 2026").
+
+## VI. UI, code, and links
+
+- **UI elements:** Put UI elements in **bold**. Focus on the task when
+  discussing interaction.
+- **Code:** Use `code font` for filenames, code snippets, commands, and API
+  elements. Use code blocks for multi-line samples.
+- **Links:** Use descriptive link text that indicates what the link leads to.
+  Avoid "click here."
+
+## VII. Word choice and terminology
+
+- **Consistent naming:** Use product and feature names consistently. Always
+  refer to Gemini CLI as `Gemini CLI`, never `the Gemini CLI`.
+- **Specific verbs:** Use precise verbs.
+- **Avoid:**
+  - Latin abbreviations (e.g., use "for example" instead of "e.g.").
+  - Placeholder names like "foo" and "bar" in examples; use meaningful names
+    instead.
+  - Anthropomorphism (e.g., "The server thinks...").
+  - "Should": Be clear about requirements ("must") vs. recommendations ("we
+    recommend").
+
+## VIII. Files and media
+
+- **Filenames:** Use lowercase letters, separate words with hyphens (-), and use
+  standard ASCII characters.
+- **Images:** Provide descriptive alt text for all images. Provide
+  high-resolution or vector images when practical.
+
+## IX. Accessibility quick check
+
+- Provide descriptive alt text for images.
+- Ensure link text makes sense out of context.
+- Use semantic HTML elements correctly (headings, lists, tables).