MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-05-16 23:02:51 -07:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Build audit skill

Browse Source
This commit is contained in:
Jenna Inouye
2026-03-17 13:05:51 -07:00
parent 076a154030
commit b2c0117e1d
4 changed files with 112 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gemini/skills/docs-writer/SKILL.md
+13 -12
View File
@@ -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`.
.gemini/skills/docs-writer/references/docs-auditing.md
+33 -29
View File
@@ -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.
.gemini/skills/docs-writer/references/style-guide.md
+66 -32
View File
@@ -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.
docs-writer.skill
BIN
View File
Binary file not shown.