mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-05-16 23:02:51 -07:00
Docs: First draft.
This commit is contained in:
Jenna Inouye
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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 <directory>
|
||||
*/
|
||||
|
||||
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).`);
|
||||
}
|
||||
@@ -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
|
||||
Binary file not shown.
Reference in New Issue
Block a user