MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-03-10 14:10:37 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs-writer skill: Update docs writer skill (#17928)

Browse Source
This commit is contained in:
Jenna Inouye
2026-02-02 10:07:25 -08:00
committed by GitHub
parent ae672881d1
commit 85dd6ef773
2 changed files with 120 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
.gemini/skills/docs-writer/SKILL.md
View File

@@ -1,71 +1,136 @@
---
name: docs-writer
description:
Use this skill for writing, reviewing, and editing documentation (`/docs`
directory or any .md file) for Gemini CLI.
Always use this skill when the task involves writing, reviewing, or editing
documentation, specifically for any files in the `/docs` directory or any
`.md` files in the repository.
---
# `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 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.
## Step 1: Understand the goal and create a plan
## Phase 1: Documentation standards
1. **Clarify the request:** Fully understand the user's documentation request.
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.
Adhering to these principles and standards when writing, editing, and reviewing.
## Step 2: Investigate and gather information
### Voice and tone
Adopt a tone that balances professionalism with a helpful, conversational
approach.
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 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.
- **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).
## Step 3: Write or edit the documentation
### Language and grammar
Write precisely to ensure your instructions are unambiguous.
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.
- **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."
### 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
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.
## 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.
- **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.
### 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, 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`
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.
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.

96
.gemini/skills/docs-writer/references/style-guide.md
View File

@@ -1,96 +0,0 @@
# 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, but don't omit helpful
information.
- **"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).