Docs Writer

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.

Phase 1: Documentation standards

Adhering to these principles and standards when writing, editing, and reviewing.

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.

• Accessibility: Use semantic HTML elements correctly (headings, lists,

tables).

• Media: Use lowercase hyphenated filenames. Provide descriptive alt text

for all images.

• Details section: Use the <details> tag to create a collapsible section.

This is useful for supplementary or data-heavy information that isn't critical to the main flow.

Example:

<details> <summary>Title</summary>

• First entry
• Second entry

</details>

• Callouts: Use GitHub-flavored markdown alerts to highlight important

information. To ensure the formatting is preserved by npm run format, place an empty line, then a prettier ignore comment directly before the callout block. Use <!-- prettier-ignore --> for standard Markdown files (.md) and {/* prettier-ignore */} for MDX files (.mdx). The callout type ([!TYPE]) should be on the first line, followed by a newline, and then the content, with each subsequent line of content starting with >. Available types are NOTE, TIP, IMPORTANT, WARNING, and CAUTION.

Example (.md):

<!-- prettier-ignore -->

[!NOTE]

This is an example of a multi-line note that will be preserved

by Prettier.

Example (.mdx):

{/ prettier-ignore /}

[!NOTE]

This is an example of a multi-line note that will be preserved

by Prettier.

Links

• Accessibility: Use descriptive anchor text; avoid "click here." Ensure the

link makes sense out of context, such as when being read by a screen reader.

• Use relative links in docs: Use relative links in documentation (/docs/)

to ensure portability. Use paths relative to the current file's directory (for example, ../tools/ from docs/cli/). Do not include the /docs/ section of a path, but do verify that the resulting relative link exists. This does not apply to meta files such as README.MD and CONTRIBUTING.MD.

• When changing headings, check for deep links: If a user is changing a

heading, check for deep links to that heading in other pages and update accordingly.

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:

<!-- prettier-ignore -->

[!NOTE]

This is an experimental feature currently under active development.

(Note: Use {/* prettier-ignore */} if editing an .mdx file.)

• 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, details, and callouts.
• 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

Before modifying any documentation, thoroughly investigate the request and the surrounding context.

1. Clarify: Understand the core request. Differentiate between writing new content and editing existing content. If the request is ambiguous (e.g., "fix the docs"), ask for clarification. 2. Investigate: Examine relevant code (primarily in packages/) for accuracy. 3. Audit: Read the latest versions of relevant files in docs/. 4. Connect: Identify all referencing pages if changing behavior. Check if docs/sidebar.json needs updates. 5. Plan: Create a step-by-step plan before making changes. 6. Audit Docset: If asked to audit the documentation, follow the procedural guide in docs-auditing.md.

Phase 3: 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.

• Gaps: Identify areas where the documentation is incomplete or no longer

reflects existing code.

• Structure: Apply "Structure (New Docs)" 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

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

sentences to make them easier for users to understand.

• 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.

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: If npm run format fails, it may be necessary to run npm install first to ensure all formatting dependencies are available. 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.

Style Guide: Quota vs. Limit

This guide defines the usage of "quota," "limit," and related terms in user-facing interfaces.

TL;DR

• `quota`: The administrative "bucket." Use for settings, billing, and

requesting increases. (e.g., "Adjust your storage quota.")

• `limit`: The real-time numerical "ceiling." Use for error messages when a

user is blocked. (e.g., "You've reached your request limit.")

• When blocked, combine them: Explain the limit that was hit and the

quota that is the remedy. (e.g., "You've reached the request limit for your developer quota.")

• Related terms: Use usage for consumption tracking, restriction for

fixed rules, and reset for when a limit refreshes.

---

Detailed Guidelines

Definitions

• Quota is the "what": It identifies the category of resource being managed

(e.g., storage quota, GPU quota, request/prompt quota).

• Limit is the "how much": It defines the numerical boundary.

Use quota when referring to the administrative concept or the request for more. Use limit when discussing the specific point of exhaustion.

When to use "quota"

Use this term for account management, billing, and settings. It describes the entitlement the user has purchased or been assigned.

Examples:

• Navigation label: Quota and usage
• Contextual help: Your usage quota is managed by your organization. To

request an increase, contact your administrator.

When to use "limit"

Use this term for real-time feedback, notifications, and error messages. It identifies the specific wall the user just hit.

Examples:

• Error message: You’ve reached the 50-request-per-minute limit.
• Inline warning: Input exceeds the 32k token limit.

How to use both together

When a user is blocked, combine both terms to explain the event (limit) and the remedy (quota).

Example:

• Heading: Daily usage limit reached
• Body: You've reached the maximum daily capacity for your developer quota.

To continue working today, upgrade your quota.

Procedural Guide: Auditing the Docset

This guide outlines the process for auditing the Gemini CLI documentation for correctness and adherence to style guidelines. This process involves both an "Editor" and "Technical Writer" phase.

Objective

To ensure all public-facing documentation is accurate, up-to-date, adheres to the Gemini CLI documentation style guide, and reflects the current state of the codebase.

Phase 1: Editor Audit

Role: The editor is responsible for identifying potential issues based on style guide violations and technical inaccuracies.

Steps

1. Identify Documentation Scope:

• Read docs/sidebar.json to get a list of all viewable documentation

pages.

• For each entry with a slug, convert it into a file path (e.g., docs ->

docs/index.md, docs/get-started -> docs/get-started.md). Ignore entries with link properties.

2. Prepare Audit Results File:

• Create a new Markdown file named audit-results-[YYYY-MM-DD].md (e.g.,

audit-results-2026-03-13.md). This file will contain all identified violations and recommendations.

3. Retrieve Style Guidelines:

• Familiarize yourself with the docs-writer skill instructions and the

included style guidelines.

4. Audit Each Document:

• For each documentation file identified in Step 1, read its content.
• Review against Style Guide:
• Voice and Tone Violations:
• Unprofessional Tone: Identify phrasing that is overly casual,

defensive, or lacks a professional and friendly demeanor.

• Indirectness or Vagueness: Identify sentences that are

unnecessarily wordy or fail to be concise and direct.

• Incorrect Pronoun: Identify any use of third-person pronouns

(e.g., "we," "they," "the user") when referring to the reader, instead of the second-person pronoun "you".

• Passive Voice: Identify sentences written in the passive voice.
• Incorrect Tense: Identify the use of past or future tense verbs,

instead of the present tense.

• Poor Vocabulary: Identify the use of jargon, slang, or overly

informal language.

• Language and Grammar Violations:
• Lack of Conciseness: Identify unnecessarily long phrases or

sentences.

• Punctuation Errors: Identify incorrect or missing punctuation.
• Ambiguous Dates: Identify dates that could be misinterpreted

(e.g., "next Monday" instead of "April 15, 2026").

• Abbreviation Usage: Identify the use of abbreviations that should

be spelled out (e.g., "e.g." instead of "for example").

• Terminology: Check for incorrect or inconsistent use of

product-specific terms (e.g., "quota" vs. "limit").

• Formatting and Syntax Violations:
• Missing Overview: Check for the absence of a brief overview

paragraph at the start of the document.

• Line Length: Identify any lines of text that exceed **80

characters** (text wrap violation).

• Casing: Identify incorrect casing for headings, titles, or named

entities (e.g., product names like Gemini CLI).

• List Formatting: Identify incorrectly formatted lists (e.g.,

inconsistent indentation or numbering).

• Incorrect Emphasis: Identify incorrect use of bold text (should

only be used for UI elements) or code font (should be used for code, file names, or command-line input).

• Link Quality: Identify links with non-descriptive anchor text

(e.g., "click here").

• Image Alt Text: Identify images with missing or poor-quality

(non-descriptive) alt text.

• Structure Violations:
• Missing BLUF: Check for the absence of a "Bottom Line Up Front"

summary at the start of complex sections or documents.

• Experimental Feature Notes: Identify experimental features that

are not clearly labeled with a standard note.

• Heading Hierarchy: Check for skipped heading levels (e.g., going

from ## to ####).

• Procedure Clarity: Check for procedural steps that do not start

with an imperative verb or where a condition is placed _after_ the instruction.

• Element Misuse: Identify the incorrect or inappropriate use of

special elements (e.g., Notes, Warnings, Cautions).

• Table of Contents: Identify the presence of a dynamically

generated or manually included table of contents.

• Missing Next Steps: Check for procedural documents that lack a

"Next steps" section (if applicable).

• Verify Code Accuracy (if applicable):
• If the document contains code snippets (e.g., shell commands, API calls,

file paths, Docker image versions), use grep_search and read_file within the packages/ directory (or other relevant parts of the codebase) to ensure the code is still accurate and up-to-date. Pay close attention to version numbers, package names, and command syntax.

• Record Findings: For each violation or inaccuracy found:
• Note the file path.
• Describe the violation (e.g., "Violation (Language and Grammar): Uses

'e.g.'").

• Provide a clear and actionable recommendation to correct the issue.

(e.g., "Recommendation: Replace 'e.g.' with 'for example'." or "Recommendation: Replace '...' with '...' in active voice.).

• Append these findings to audit-results-[YYYY-MM-DD].md.

Phase 2: Software Engineer Audit

Role: The software engineer is responsible for finding undocumented features by auditing the codebase and recent changelogs, and passing these findings to the technical writer.

Steps

1. Proactive Codebase Audit:

• Audit high-signal areas of the codebase to identify undocumented features.

You MUST review:

• packages/cli/src/commands/
• packages/core/src/tools/
• packages/cli/src/config/settings.ts

2. Review Recent Updates:

• Check recent changelogs in stable and announcements within the

documentation to see if newly introduced features are documented properly.

3. Evaluate and Record Findings:

• Determine if these features are adequately covered in the docs. They do

not need to be documented word for word, but major features that customers should care about probably should have an article.

• Append your findings to the audit-results-[YYYY-MM-DD].md file,

providing a brief description of the feature and where it should be documented.

Phase 3: Technical Writer Implementation

Role: The technical writer handles input from both the editor and the software engineer, makes appropriate decisions about what to change, and implements the approved changes.

Steps

1. Review Audit Results:

• Read audit-results-[YYYY-MM-DD].md to understand all identified issues,

undocumented features, and recommendations from both the Editor and Software Engineer phases.

2. Make Decisions and Log Reasoning:

• Create or update an implementation log (e.g.,

audit-implementation-log-[YYYY-MM-DD].md).

• Make sure the logs are updated for all steps, documenting your reasoning

for each recommendation (why it was accepted, modified, or rejected). This is required for a final check by a human in the PR.

3. Implement Changes:

• For each approved recommendation:
• Read the target documentation file.
• Apply the recommended change using the replace tool. Pay close

attention to old_string for exact matches, including whitespace and newlines. For multiple occurrences of the same simple string (e.g., "e.g."), use allow_multiple: true.

• String replacement safeguards: When applying these fixes across the

docset, you must verify the following:

• Preserve Code Blocks: Explicitly verify that no code blocks,

inline code snippets, terminal commands, or file paths have been erroneously capitalized or modified.

• Preserve Literal Strings: Never alter the wording of literal error

messages, UI quotes, or system logs. For example, if a style rule says to remove the word "please", you must NOT remove it if it appears inside a quoted error message (e.g., Error: Please contact your administrator).

• Verify Sentence Casing: When removing filler words (like "please")

from the beginning of a sentence or list item, always verify that the new first word of the sentence is properly capitalized.

• For structural changes (e.g., adding an overview paragraph), use

replace or write_file as appropriate.

• For broken links, determine the correct new path or update the link

text.

• For creating new files (e.g., docs/get-started.md to fix a broken

link, or a new feature article), use write_file.

4. Execute Auto-Generation Scripts:

• Some documentation pages are auto-generated from the codebase and should

be updated using npm scripts rather than manual edits. After implementing manual changes (especially if you edited settings or configurations based on SWE recommendations), ensure you run:

• npm run docs:settings to generate/update the configuration reference.
• npm run docs:keybindings to generate/update the keybindings reference.

5. Format Code:

• Dependencies: If npm run format fails, it may be necessary to run

npm install first to ensure all formatting dependencies are available.

• After all changes have been implemented, run npm run format to ensure

consistent formatting across the project.