diff --git a/.gemini/skills/docs-writer/SKILL.md b/.gemini/skills/docs-writer/SKILL.md index d7cf7b81be..e9c49d119c 100644 --- a/.gemini/skills/docs-writer/SKILL.md +++ b/.gemini/skills/docs-writer/SKILL.md @@ -1,97 +1,22 @@ --- name: docs-writer -description: - Always use this skill when the task involves writing, reviewing, or editing - files in the `/docs` directory or any `.md` files in the repository. +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. --- # `docs-writer` skill instructions As an expert technical writer and editor for the Gemini CLI project, you produce -accurate, clear, and consistent documentation. When asked to write, edit, or -review documentation, you must ensure the content strictly adheres to the -provided documentation standards and accurately reflects the current codebase. -Adhere to the contribution process in `CONTRIBUTING.md` and the following -project standards. +accurate, clear, and consistent documentation. You must adhere to the +contribution process in `CONTRIBUTING.md` and the +[style-guide.md](references/style-guide.md). -## Phase 1: Documentation standards +--- -Adhering to these principles and standards when writing, editing, and reviewing. +## Standard Workflow: Writing and Reviewing +Use this workflow for standard requests to write new content or review/edit +existing documentation. -### Voice and tone -Adopt a tone that balances professionalism with a helpful, conversational -approach. - -- **Perspective and tense:** Address the reader as "you." Use active voice and - present tense (e.g., "The API returns..."). -- **Tone:** Professional, friendly, and direct. -- **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). - -### Language and grammar -Write precisely to ensure your instructions are unambiguous. - -- **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` resource file. Generally, Use "quota" for the - administrative bucket and "limit" for the numerical ceiling. - -### Formatting and syntax -Apply consistent formatting to make documentation visually organized and -accessible. - -- **Overview paragraphs:** Every heading must be followed by 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. - -### 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: - `> **Note:** This is a preview feature currently under active development.` -- **Headings:** Use hierarchical headings to support the user journey. -- **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..."). - - 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. - -## Phase 2: Preparation +### Phase 1: Preparation Before modifying any documentation, thoroughly investigate the request and the surrounding context. @@ -105,20 +30,17 @@ surrounding context. `docs/sidebar.json` needs updates. 5. **Plan:** Create a step-by-step plan before making changes. -## Phase 3: 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. -### Editing existing documentation -Follow these additional steps when asked to review or update existing -documentation. - +#### Editing existing documentation - **Gaps:** Identify areas where the documentation is incomplete or no longer reflects existing code. -- **Structure:** Apply "Structure (New Docs)" rules (BLUF, headings, etc.) when +- **Structure:** Apply style guide rules (BLUF, headings, etc.) when adding new sections to existing pages. -- **Headers**: If you change a header, you must check for links that lead to +- **Headers:** If you change a header, you must check for links that lead to that header and update them. - **Tone:** Ensure the tone is active and engaging. Use "you" and contractions. - **Clarity:** Correct awkward wording, spelling, and grammar. Rephrase @@ -126,17 +48,21 @@ documentation. - **Consistency:** Check for consistent terminology and style across all edited documents. - -## Phase 4: Verification and finalization -Perform a final quality check to ensure that all changes are correctly formatted -and that all links are functional. - +### 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. 3. **Link check:** Verify all new and existing links leading to or from modified - pages. If you changed a header, ensure that any links that lead to it are - updated. -4. **Format:** Once all changes are complete, ask to execute `npm run format` - to ensure consistent formatting across the project. If the user confirms, - execute the command. + pages. +4. **Format:** Once all changes are complete, ask to execute `npm run format`. + +--- + +## 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). + +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. diff --git a/.gemini/skills/docs-writer/references/docs-auditing.md b/.gemini/skills/docs-writer/references/docs-auditing.md new file mode 100644 index 0000000000..6d29a94381 --- /dev/null +++ b/.gemini/skills/docs-writer/references/docs-auditing.md @@ -0,0 +1,90 @@ +# 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. + +--- + +## Role 1: Strategist +You are an expert content strategist experienced in technical documentation. + +### Rules +Our information architecture is user-focused with the goal of getting our users to the necessary information with the fewest clicks. We have the following areas of our site: +- **Get started:** This is our most essential “getting started” material. Content should rarely be added to this section. +- **Use Gemini CLI:** This section contains user-focused guides based on user journeys, which may touch one or more features. +- **Features:** This section contains feature documentation and should include all important features. +- **Configuration:** This section contains configuration options for Gemini CLI. Content should rarely be added to this section. +- **Development:** This section contains development information for Gemini CLI. Content should rarely be added to this section. +- **Reference:** This section contains reference information. Net-new pages should rarely be added to this section, but pages may be frequently updated. +- **Resources:** This section contains resources such as Terms of Service and privacy policies. Content should rarely be added to this section. + +### Tasks +1. Use ‘sidebar.json’ and the content of the /docs/ page to review the current documentation set. +2. Review the current codebase to identify gaps in the current documentation set. +3. Review the documentation for outdated content that no longer exists within the codebase. +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: +- 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 +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. + +### Tasks +1. Review the ’content-plan.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`. + +--- + +## 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. + +### 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. + +### Deliverable +Update the ‘content-plan.md’ with reports regarding each element of content. Save the ‘content-plan.md’. + +--- + +## 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. + +### 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. +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. diff --git a/.gemini/skills/docs-writer/quota-limit-style-guide.md b/.gemini/skills/docs-writer/references/quota-limit-style-guide.md similarity index 100% rename from .gemini/skills/docs-writer/quota-limit-style-guide.md rename to .gemini/skills/docs-writer/references/quota-limit-style-guide.md diff --git a/.gemini/skills/docs-writer/references/style-guide.md b/.gemini/skills/docs-writer/references/style-guide.md new file mode 100644 index 0000000000..9340072c08 --- /dev/null +++ b/.gemini/skills/docs-writer/references/style-guide.md @@ -0,0 +1,52 @@ +# 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. + +## Voice and Tone +Adopt a tone that balances professionalism with a helpful, conversational approach. + +- **Perspective and tense:** Address the reader as "you." Use active voice and present tense (e.g., "The API returns..."). +- **Tone:** Professional, friendly, and direct. +- **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). + +## Language and Grammar +Write precisely to ensure your instructions are unambiguous. + +- **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. + +## Formatting and Syntax +Apply consistent formatting to make documentation visually organized and accessible. + +- **Overview paragraphs:** Every heading must be followed by 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. + +## 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: + `> **Note:** This is a preview feature currently under active development.` +- **Headings:** Use hierarchical headings to support the user journey. +- **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..."). + - 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. diff --git a/.gemini/skills/docs-writer/scripts/find_broken_links.cjs b/.gemini/skills/docs-writer/scripts/find_broken_links.cjs new file mode 100644 index 0000000000..8c4c690680 --- /dev/null +++ b/.gemini/skills/docs-writer/scripts/find_broken_links.cjs @@ -0,0 +1,63 @@ +#!/usr/bin/env node +/** + * Simple script to find broken internal Markdown links in a directory. + * Usage: node find_broken_links.cjs + */ + +const fs = require('fs'); +const path = require('path'); + +const targetDir = process.argv[2]; +if (!targetDir) { + console.error('Error: Please provide a directory path.'); + process.exit(1); +} + +function findFiles(dir, ext, fileList = []) { + const files = fs.readdirSync(dir); + files.forEach(file => { + const filePath = path.join(dir, file); + if (fs.statSync(filePath).isDirectory()) { + findFiles(filePath, ext, fileList); + } else if (filePath.endsWith(ext)) { + fileList.push(filePath); + } + }); + return fileList; +} + +const mdFiles = findFiles(targetDir, '.md'); +const linkRegex = /\[([^\]]+)\]\(([^)]+)\)/g; +let brokenLinksFound = 0; + +mdFiles.forEach(file => { + const content = fs.readFileSync(file, 'utf8'); + const dir = path.dirname(file); + let match; + + while ((match = linkRegex.exec(content)) !== null) { + const linkPath = match[2]; + + // Only check relative, internal links (not http, mailto, etc.) + if (linkPath.startsWith('http') || linkPath.startsWith('mailto:') || linkPath.startsWith('#')) { + continue; + } + + // Strip anchor from link path + const cleanLinkPath = linkPath.split('#')[0]; + if (!cleanLinkPath) continue; + + const absoluteLinkPath = path.resolve(dir, cleanLinkPath); + + if (!fs.existsSync(absoluteLinkPath)) { + console.log(`Broken link in ${path.relative(targetDir, file)}: [${match[1]}](${linkPath}) -> Not found at: ${path.relative(targetDir, absoluteLinkPath)}`); + brokenLinksFound++; + } + } +}); + +if (brokenLinksFound === 0) { + console.log('Success: No broken internal links found.'); +} else { + console.log(`\nFinished: Found ${brokenLinksFound} broken link(s).`); +} diff --git a/.github/workflows/weekly-docs-audit.yaml b/.github/workflows/weekly-docs-audit.yaml new file mode 100644 index 0000000000..735584f6e1 --- /dev/null +++ b/.github/workflows/weekly-docs-audit.yaml @@ -0,0 +1,52 @@ +name: 'Weekly Docs Audit' + +on: + schedule: + # Runs every Monday at 00:00 UTC + - cron: '0 0 * * MON' + workflow_dispatch: + +jobs: + audit-docs: + runs-on: 'ubuntu-latest' + permissions: + contents: 'write' + pull-requests: 'write' + + steps: + - name: 'Checkout repository' + uses: 'actions/checkout@v4' + with: + fetch-depth: 0 + ref: 'main' + + - name: 'Set up Node.js' + uses: 'actions/setup-node@v4' + with: + node-version: '20' + + - name: 'Run Docs Audit with Gemini' + uses: 'google-github-actions/run-gemini-cli@v0' # Use a specific tag or SHA for stability + with: + gemini_api_key: '${{ secrets.GEMINI_API_KEY }}' + prompt: | + Activate the 'docs-writer' skill. + + **Task:** Audit the entire documentation set for correctness and adherence to style guidelines, as defined in your 'docs-auditing.md' reference. + + When you are done, please output your thought process and the steps you took for future debugging purposes, and save the audit results to 'audit-results-${{ github.run_id }}.md'. + + - name: 'Create Pull Request with Audit Results' + uses: 'peter-evans/create-pull-request@v6' + with: + token: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}' + commit-message: 'docs: weekly audit results for ${{ github.run_id }}' + title: 'Docs Audit for Week of ${{ github.event.schedule }}' + body: | + This PR contains the auto-generated documentation audit for the week. It includes a new `audit-results-*.md` file with findings and any direct fixes applied by the agent. + + Please review the suggestions and merge. + branch: 'docs-audit-${{ github.run_id }}' + base: 'main' + team-reviewers: 'gemini-cli-docs, gemini-cli-maintainers' + delete-branch: true diff --git a/docs-writer.skill b/docs-writer.skill new file mode 100644 index 0000000000..3b7028fe57 Binary files /dev/null and b/docs-writer.skill differ