diff --git a/.gemini/skills/docs-writer/SKILL.md b/.gemini/skills/docs-writer/SKILL.md index e9c49d119c..0c0505a2e5 100644 --- a/.gemini/skills/docs-writer/SKILL.md +++ b/.gemini/skills/docs-writer/SKILL.md @@ -1,6 +1,6 @@ --- name: docs-writer -description: Expert technical documentation suite for Gemini CLI. Use when asked to write, review, or edit .md files in the repository. Also supports a "Deep Content Update Workflow" for comprehensive audits and system-wide documentation refreshes. +description: Expert technical documentation suite for Gemini CLI. Use when asked to write, review, or edit .md files. Supports a "Deep content update workflow" for comprehensive audits and a "Report-only mode" for documentation analysis without making changes. --- # `docs-writer` skill instructions @@ -12,11 +12,11 @@ contribution process in `CONTRIBUTING.md` and the --- -## Standard Workflow: Writing and Reviewing +## Standard workflow: writing and reviewing Use this workflow for standard requests to write new content or review/edit existing documentation. -### Phase 1: Preparation +### Phase 1: preparation Before modifying any documentation, thoroughly investigate the request and the surrounding context. @@ -30,7 +30,7 @@ surrounding context. `docs/sidebar.json` needs updates. 5. **Plan:** Create a step-by-step plan before making changes. -### Phase 2: Execution +### Phase 2: execution Implement your plan by either updating existing files or creating new ones using the appropriate file system tools. Use `replace` for small edits and `write_file` for new files or large rewrites. @@ -48,7 +48,7 @@ using the appropriate file system tools. Use `replace` for small edits and - **Consistency:** Check for consistent terminology and style across all edited documents. -### Phase 3: Verification and finalization +### Phase 3: verification and finalization 1. **Accuracy:** Ensure content accurately reflects the implementation and technical behavior. 2. **Self-review:** Re-read changes for formatting, correctness, and flow. @@ -58,11 +58,12 @@ using the appropriate file system tools. Use `replace` for small edits and --- -## Feature: Deep Content Update Workflow -When specifically asked for a **"deep audit," "comprehensive update,"** or -**"interactively audit"** the docset, you MUST follow the multi-role procedural -guidance in [docs-auditing.md](references/docs-auditing.md). +## Feature: deep content update workflow +When specifically asked for a **"deep audit," "comprehensive update,"** +**"interactively audit,"** or a **"report-only audit"** of the docset, you MUST +follow the multi-role procedural guidance in +[docs-auditing.md](references/docs-auditing.md). -This workflow involves iterating through the roles of **Strategist, Engineer, -Writer, and Editor** to perform a systematic review and update of the entire -documentation set. +- **Standard audit:** Iterate through strategist, engineer, writer, and editor. +- **Report-only mode:** Iterate through strategist and engineer only, and + output a final `audit-report-YYYY-MM-DD.md`. diff --git a/.gemini/skills/docs-writer/references/docs-auditing.md b/.gemini/skills/docs-writer/references/docs-auditing.md index 6d29a94381..b23078fe7f 100644 --- a/.gemini/skills/docs-writer/references/docs-auditing.md +++ b/.gemini/skills/docs-writer/references/docs-auditing.md @@ -1,12 +1,14 @@ -# Deep Content Update Workflow: Docs Auditing +# Deep content update workflow: docs auditing Perform this workflow when asked for a "deep audit," "comprehensive update," or to "interactively audit" the docset. You will iterate through this workflow performing the roles of strategist, engineer, writer, and editor. -**Interactive Mode:** IF you have been asked to do this “interactively,” you will ask questions when you are uncertain. +**Report-only mode:** If you have been asked for a "report-only audit" or "documentation report," follow only the strategist and engineer roles. Finalize the `audit-report-YYYY-MM-DD.md` with findings and recommendations, then stop without making any changes to the documentation files. + +**Interactive mode:** If you have been asked to do this “interactively,” you will ask questions when you are uncertain. --- -## Role 1: Strategist +## Role 1: strategist You are an expert content strategist experienced in technical documentation. ### Rules @@ -26,65 +28,67 @@ Our information architecture is user-focused with the goal of getting our users 4. Review each piece of existing documentation for content that must be updated, added, or removed, in addition to areas in which the content does not meet our [style-guide.md](style-guide.md). ### Deliverable -Create a temporary file `content-plan.md` (or a dated `audit-plan-YYYY-MM-DD.md`) that includes: +Create a temporary, dated file `audit-plan-YYYY-MM-DD.md` that includes: - Existing content that needs to be updated. - Existing content that needs to be deprecated. - Net-new content that needs to be added. --- -## Role 2: Engineer +## Role 2: engineer You are an expert Gemini CLI engineer. Your role is to augment the content strategist’s content plan. ### Rules -- When possible, we should include code samples. -- These code samples should be specific and easy to follow rather than placeholders or generic snippets. -- When multiple environments (Powershell, macOS) are involved, we should include both directions. +- Include code samples when possible. +- Ensure code samples are specific and easy to follow rather than placeholders or generic snippets. +- Include both directions when multiple environments (Powershell, macOS) are involved. ### Tasks -1. Review the ’content-plan.md’. +1. Review the `audit-plan-YYYY-MM-DD.md`. 2. Iterate through the content that must be updated and added, looking for areas that require engineering examples. 3. Correct any misunderstandings in the content plan about the way that functions work within the codebase. ### Deliverable -Under each content change in `content-plan.md`, add your relevant code samples or clarifications. Save `content-plan.md`. +Under each content change in `audit-plan-YYYY-MM-DD.md`, add your relevant code samples or clarifications. Save `audit-plan-YYYY-MM-DD.md`. + +**Note:** If in **Report-only mode**, rename this file to `audit-report-YYYY-MM-DD.md`, provide a final summary of findings, and end the task. --- -## Role 3: Writer +## Role 3: writer You are an expert technical writer specialized in Gemini CLI. You will take the content plan created by the strategist and the engineer and you will write the content. ### Rules -- You will follow our [style-guide.md](style-guide.md). -- You will follow our existing content structures, e.g. ‘Use Gemini CLI’ contains user-focused guide, whereas ‘Features’ contains feature references. +- Follow our [style-guide.md](style-guide.md). +- Follow our existing content structures, e.g. ‘Use Gemini CLI’ contains user-focused guides, whereas ‘Features’ contains feature references. ### Tasks -1. You will iterate through ‘content-plan.md’. -2. You will create the net-new content outlined in the style guide. -3. You will perform the updates outlined in the content plan. -4. You will perform the deprecations outlined in the content plan. +1. Iterate through `audit-plan-YYYY-MM-DD.md`. +2. Create the net-new content outlined in the style guide. +3. Perform the updates outlined in the content plan. +4. Perform the deprecations outlined in the content plan. ### Deliverable -Update the ‘content-plan.md’ with reports regarding each element of content. Save the ‘content-plan.md’. +Update the `audit-plan-YYYY-MM-DD.md` with reports regarding each element of content. Save the `audit-plan-YYYY-MM-DD.md`. --- -## Role 4: Editor +## Role 4: editor You are an expert editor specialized in Gemini CLI. You will review the content written by the content writer to ensure that it meets the specifications of the content plan. ### Rules -- You will follow our [style-guide.md](style-guide.md). -- Our content must be clear and user-focused. -- You will thoroughly review all content. +- Follow our [style-guide.md](style-guide.md). +- Ensure content is clear and user-focused. +- Thoroughly review all content. ### Tasks -1. You will iterate through the content-plan to ensure that it has been followed and completed. -2. You will then go through our documentation set, including the updates: - - For each piece of content, you will ensure that it fits the [style-guide.md](style-guide.md) and that there are no errors. - - You will check to ensure that all internal links are relative and valid and that our external links are absolute. - - You will check for any style errors, such as removing “Table of Contents” sections. - - You will fix grammar issues, typos, and clarity issues. +1. Iterate through the `audit-plan-YYYY-MM-DD.md` to ensure that it has been followed and completed. +2. Go through our documentation set, including the updates: + - For each piece of content, ensure that it fits the [style-guide.md](style-guide.md) and that there are no errors. + - Check to ensure that all internal links are relative and valid and that our external links are absolute. + - Check for any style errors, such as removing “Table of Contents” sections. + - Fix grammar issues, typos, and clarity issues. 3. Run the link-checking script: `node scripts/find_broken_links.cjs docs/` ### Deliverable -You will update `content-plan.md` with your changes and finalize the audit. +Update `audit-plan-YYYY-MM-DD.md` with your changes and finalize the audit. diff --git a/.gemini/skills/docs-writer/references/style-guide.md b/.gemini/skills/docs-writer/references/style-guide.md index 9340072c08..3592b7897d 100644 --- a/.gemini/skills/docs-writer/references/style-guide.md +++ b/.gemini/skills/docs-writer/references/style-guide.md @@ -1,52 +1,86 @@ -# Gemini CLI Documentation Style Guide +# Gemini CLI documentation style guide -As an expert technical writer and editor for the Gemini CLI project, you must ensure the content strictly adheres to these standards. +As an expert technical writer and editor for the Gemini CLI project, you must +ensure the content strictly adheres to these standards. This guide provides +detailed instructions on voice, language, formatting, and structure. -## Voice and Tone -Adopt a tone that balances professionalism with a helpful, conversational approach. +## Voice and tone +Adopt a tone that balances professionalism with a helpful, conversational +approach. This ensures the documentation is accessible and engaging for all +users. -- **Perspective and tense:** Address the reader as "you." Use active voice and present tense (e.g., "The API returns..."). -- **Tone:** Professional, friendly, and direct. +- **Perspective and tense:** Address the reader as "you." Use active voice and + present tense (e.g., "The API returns..."). Avoid "will" (second-person + future). +- **Tone:** Maintain a professional, friendly, and direct tone. - **Clarity:** Use simple vocabulary. Avoid jargon, slang, and marketing hype. -- **Global Audience:** Write in standard US English. Avoid idioms and cultural references. -- **Requirements:** Be clear about requirements ("must") vs. recommendations ("we recommend"). Avoid "should." -- **Word Choice:** Avoid "please" and anthropomorphism (e.g., "the server thinks"). Use contractions (don't, it's). +- **Global audience:** Write in standard US English. Avoid idioms, cultural + references, and region-specific analogies. +- **Requirements:** Be clear about requirements ("must") vs. recommendations + ("we recommend"). Avoid the word "should." +- **Word choice:** Avoid "please" and anthropomorphism (e.g., "the server + thinks"). Use common contractions (don't, it's). -## Language and Grammar -Write precisely to ensure your instructions are unambiguous. +## Language and grammar +Write precisely to ensure your instructions are unambiguous. Consistency in +grammar and punctuation helps users follow technical procedures correctly. -- **Abbreviations:** Avoid Latin abbreviations; use "for example" (not "e.g.") and "that is" (not "i.e."). -- **Punctuation:** Use the serial comma. Place periods and commas inside quotation marks. +- **Abbreviations:** Avoid Latin abbreviations. Use "for example" (not "e.g.") + and "that is" (not "i.e."). +- **Punctuation:** Use the serial comma. Place periods and commas inside + quotation marks. - **Dates:** Use unambiguous formats (e.g., "January 22, 2026"). -- **Conciseness:** Use "lets you" instead of "allows you to." Use precise, specific verbs. -- **Examples:** Use meaningful names in examples; avoid placeholders like "foo" or "bar." -- **Quota and limit terminology:** For any content involving resource capacity or using the word "quota" or "limit", strictly adhere to the guidelines in the [quota-limit-style-guide.md](quota-limit-style-guide.md) resource file. +- **Conciseness:** Use "lets you" instead of "allows you to." Use precise, + specific verbs. +- **Examples and placeholders:** + - Use meaningful names in examples; avoid "foo" or "bar." + - Format placeholders in `ITALIC_ALL_CAPS` (e.g., `YOUR_API_KEY`). +- **Quota and limit terminology:** For any content involving resource capacity, + strictly adhere to the guidelines in + [quota-limit-style-guide.md](quota-limit-style-guide.md). -## Formatting and Syntax -Apply consistent formatting to make documentation visually organized and accessible. +## Formatting and syntax +Apply consistent formatting to make documentation visually organized and +accessible. These rules help users distinguish between UI elements, code, and +narrative text. -- **Overview paragraphs:** Every heading must be followed by at least one introductory overview paragraph before any lists or sub-headings. +- **Overview paragraphs:** Follow every heading with at least one + introductory overview paragraph before any lists or sub-headings. - **Text wrap:** Wrap text at 80 characters (except long links or tables). - **Casing:** Use sentence case for headings, titles, and bolded text. -- **Naming:** Always refer to the project as `Gemini CLI` (never `the Gemini CLI`). -- **Lists:** Use numbered lists for sequential steps and bulleted lists otherwise. Keep list items parallel in structure. -- **UI and code:** Use **bold** for UI elements and `code font` for filenames, snippets, commands, and API elements. Focus on the task when discussing interaction. -- **Links:** Use descriptive anchor text; avoid "click here." Ensure the link makes sense out of context. -- **Accessibility:** Use semantic HTML elements correctly (headings, lists, tables). -- **Media:** Use lowercase hyphenated filenames. Provide descriptive alt text for all images. +- **Naming:** Always refer to the project as `Gemini CLI` (never + `the Gemini CLI`). +- **Lists:** Use numbered lists for sequential steps and bulleted lists + otherwise. Keep list items parallel in structure and start with imperative + verbs. +- **UI and code:** Use **bold** for UI elements and `code font` for filenames, + snippets, commands, and API elements. +- **Links:** Use descriptive anchor text that makes sense out of context. + Avoid "click here" or "here." +- **Accessibility:** Use semantic HTML elements correctly (headings, lists, + tables). Provide descriptive alt text for all images. +- **Media:** Use lowercase hyphenated filenames for all assets. ## Structure -- **BLUF:** Start with an introduction explaining what to expect. -- **Experimental features:** If a feature is clearly noted as experimental, add the following note immediately after the introductory paragraph: +Follow a consistent structure to support the user journey from introduction to +next steps. This hierarchy helps users find information quickly. + +- **BLUF:** Start every page with an introduction (Bottom Line Up Front) + explaining what the reader can expect to learn. +- **Experimental features:** If a feature is experimental, add this note + immediately after the introductory paragraph: `> **Note:** This is a preview feature currently under active development.` -- **Headings:** Use hierarchical headings to support the user journey. +- **Headings:** Use hierarchical headings (H1, H2, H3) to organize content. - **Procedures:** - Introduce lists of steps with a complete sentence. - Start each step with an imperative verb. - Number sequential steps; use bullets for non-sequential lists. - - Put conditions before instructions (e.g., "On the Settings page, click..."). + - Put conditions before instructions (e.g., "On the **Settings** page, + click..."). - Provide clear context for where the action takes place. - Indicate optional steps clearly (e.g., "Optional: ..."). -- **Elements:** Use bullet lists, tables, notes (`> **Note:**`), and warnings (`> **Warning:**`). -- **Avoid using a table of contents:** If a table of contents is present, remove it. -- **Next steps:** Conclude with a "Next steps" section if applicable. +- **Visual elements:** Use bullet lists, tables, notes (`> **Note:**`), and + warnings (`> **Warning:**`) to break up dense text. +- **Table of contents:** Do not include a manual table of contents. +- **Next steps:** Conclude with a "Next steps" section if applicable to guide + the user's next action. diff --git a/docs-writer.skill b/docs-writer.skill index 3b7028fe57..ee24e3a00e 100644 Binary files a/docs-writer.skill and b/docs-writer.skill differ