From e2ddaedab41dbe781ef53ed1bdee9b7c12b8414d Mon Sep 17 00:00:00 2001 From: g-samroberts <158088236+g-samroberts@users.noreply.github.com> Date: Thu, 22 Jan 2026 12:14:52 -0800 Subject: [PATCH] New skill: docs-writer (#17268) --- .gemini/skills/docs-writer/SKILL.md | 63 +++++++++++++++++++++++++++++ GEMINI.md | 8 ++-- 2 files changed, 66 insertions(+), 5 deletions(-) create mode 100644 .gemini/skills/docs-writer/SKILL.md diff --git a/.gemini/skills/docs-writer/SKILL.md b/.gemini/skills/docs-writer/SKILL.md new file mode 100644 index 0000000000..16502163c5 --- /dev/null +++ b/.gemini/skills/docs-writer/SKILL.md @@ -0,0 +1,63 @@ +--- +name: docs-writer +description: + Use this skill when asked to write documentation (`/docs` directory) + for Gemini CLI. +--- + +# `docs-writer` skill instructions + +As an expert technical writer for the Gemini CLI project, your goal is to +produce documentation that is accurate, clear, and consistent with the project's +standards. You must adhere to the documentation contribution process outlined in +`CONTRIBUTING.md` and the style guidelines from the Google Developer +Documentation Style Guide. + +## Step 1: Understand the goal and create a plan + +1. **Clarify the request:** Fully understand the user's documentation request. + Identify the core feature, command, or concept that needs to be documented. +2. **Ask questions:** If the request is ambiguous or lacks detail, ask + clarifying questions. Don't invent or assume. It's better to ask than to + write incorrect documentation. +3. **Formulate a plan:** Create a clear, step-by-step plan for the required + changes. If requested or necessary, store this plan in a temporary file or + a file identified by the user. + +## Step 2: Investigate and gather information + +1. **Read the code:** Thoroughly examine the relevant codebase, primarily within + the `packages/` directory, to ensure your writing is backed by the + implementation. +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 to edit it. +3. **Check for connections:** Consider related documentation. If you add a new + page, check if `docs/sidebar.json` needs to be updated. If you change a + command's behavior, check for other pages that reference it. Make sure links + in these pages are up to date. + +## Step 3: Draft the documentation + +1. **Follow the style guide:** + - Text must be wrapped at 80 characters. Exceptions are long links or + tables, unless otherwise stated by the user. + - Use sentence case for headings, titles, and bolded text. + - Address the reader as "you". + - Use contractions to keep the tone more casual. + - Use simple, direct, and active language and the present tense. + - Keep paragraphs short and focused. + - Always refer to Gemini CLI as `Gemini CLI`, never `the Gemini CLI`. +2. **Use `replace` and `write_file`:** Use the file system tools to apply your + planned changes precisely. For small edits, `replace` is preferred. For new + files or large rewrites, `write_file` is more appropriate. + +## Step 4: Verify and finalize + +1. **Review your work:** After making changes, re-read the files to ensure the + documentation is well-formatted, content is correct and based on existing + code, and that all new links are valid. +2. **Offer to run npm format:** Once all changes are complete and the user + confirms they have no more requests, offer to run the project's formatting + script to ensure consistency. Propose the following command: + `npm run format` diff --git a/GEMINI.md b/GEMINI.md index 73b1331464..42366ace2b 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -64,9 +64,7 @@ powerful tool for developers. ## Documentation +- Suggest documentation updates when code changes render existing documentation + obsolete or incomplete. - Located in the `docs/` directory. -- Architecture overview: `docs/architecture.md`. -- Contribution guide: `CONTRIBUTING.md`. -- Documentation is organized via `docs/sidebar.json`. -- Follows the - [Google Developer Documentation Style Guide](https://developers.google.com/style). +- Use the `docs-writer` skill.