harry/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Replace personal writing skill with Google style

Browse Source
This commit is contained in:
harry
2026-08-18 18:05:18 +01:00
parent f10f53a6dc
commit 5adb8686e2
28 changed files with 167 additions and 1567 deletions
Download Patch File Download Diff File Expand all files Collapse all files
google-developer-style/SKILL.md
+167
View File
@@ -0,0 +1,167 @@
---
name: google-developer-style
description: Use for all technical writing, including user responses, documentation, README files, tutorials, procedures, API references, code comments, release notes, commit messages, pull request descriptions, issue descriptions, reviews, and technical plans. Applies the Google developer documentation style guide with British English spelling.
---
# Google developer style
Use the [Google developer documentation style guide](https://developers.google.com/style)
for all technical writing. This requirement includes short responses, not only formal
documentation.
## Precedence
Apply guidance in this order:
1. Follow explicit instructions from the user.
2. Follow project-specific terminology, templates, and writing requirements.
3. Follow this skill.
4. Consult the current Google guide when this skill does not answer a style question.
Depart from the guide when doing so makes the content more accurate, clear, consistent,
or appropriate for its readers. Apply one deliberate exception throughout the text:
use British English spelling instead of American English spelling. For example, use
_behaviour_, _customise_, _organisation_, and _licence_ as appropriate. Do not change
code, API names, quoted text, product names, commands, file paths, or established
project terminology to British spelling.
## Core principles
- Put the reader's goal and the important result first.
- Write for a technical reader who might be in a hurry.
- Be clear, concise, accurate, and consistent.
- Use a conversational, friendly, and respectful tone without slang or frivolity.
- Prefer familiar, precise words. Remove filler, jargon, buzzwords, clichés, and
culturally specific references.
- Preserve necessary technical detail. Define unfamiliar terms and abbreviations at
first use.
- Write for a global audience. Avoid idioms, humour that depends on culture, and
figurative or directional language.
- Use inclusive and accessible language. Do not describe tasks as easy, simple, quick,
obvious, or trivial.
- Make claims specific and supportable. Avoid superlatives, marketing language, and
promises about unreleased features.
- Keep content timeless where practical. Avoid phrases such as _currently_, _at this
time_, and _new_ when a concrete version or date is more useful.
## Voice and grammar
- Address the reader as _you_. Do not use _we_ to mean the reader or _let's_ to give an
instruction.
- Use active voice and name the actor when it is not clear.
- Use present tense for current behaviour and imperative verbs for instructions.
- Put conditions and context before the action: "If the build fails, inspect the log."
- Put the purpose before the action when it helps: "To validate the file, run..."
- Keep sentences focused on one main idea. Split long or heavily qualified sentences.
- Use contractions when they sound natural and do not create ambiguity.
- Use the serial comma.
- Avoid exclamation marks, semicolons where a full stop works, excessive parentheses,
and unnecessary dashes.
- Do not use _please_ in instructions or placeholder phrases such as _please note_.
- Do not make software anthropomorphic. State what a system or component does.
## Structure
- Use the smallest structure that makes the content easy to scan. Do not add headings,
summaries, or lists to short content without a clear need.
- Use sentence case for titles and headings.
- Start each section with useful information, not a restatement of its heading.
- Keep paragraphs short and focused. Put one topic in each paragraph.
- Use numbered lists for ordered steps and bulleted lists for unordered items.
- Make list items grammatically parallel. Introduce a list when the context is not clear.
- Use descriptive link text that explains the destination. Do not use "click here" or
expose a URL when a useful label is available.
- Use unambiguous dates. Include the year when readers might need it.
- Provide alt text for meaningful images. Do not rely only on colour, position, or shape
to communicate information.
## Procedures
- State prerequisites and required context before the steps.
- Prefer the shortest accessible procedure that completes the task. Do not document
several equivalent methods unless readers need them.
- Use one numbered step for each substantial action. Use a bullet for a single-step
procedure.
- Begin each step with an imperative verb and use complete sentences.
- State where the reader performs an action before stating the action.
- Write actions in the order in which the reader performs them.
- Put `Optional:` at the start of an optional step.
- State an action before its result or justification.
- Explain placeholders immediately after the command that contains them.
- Avoid "run the following command". State what the command accomplishes.
- Do not use _above_, _below_, _left_, or _right_ to locate content or controls.
## Technical formatting
- Use backticks for filenames, paths, commands, flags, environment variables, code
elements, literal values, HTTP methods and status codes, console output in prose, and
text that the reader enters.
- Use fenced code blocks with a language identifier for multiline code or commands.
- Use bold only for UI elements and short run-in headings. If a UI value is code, use
bold and code formatting together.
- Use italics sparingly for introduced terms or semantic emphasis. Do not underline
text except through link rendering.
- Preserve the exact spelling and capitalisation of code symbols, products, and UI
labels.
- Use all-capital descriptive placeholders such as `PROJECT_ID`. Explain each
placeholder.
- Do not turn code elements into English verbs or inflect them. Write "send a `POST`
request", not "`POST` the data".
- Refer to an HTTP value as a status code, for example, HTTP `404 Not Found` status code.
- Give code samples enough context to run, use realistic but safe values, and keep them
focused on the point being explained.
## Content-specific guidance
For responses:
- Answer the question directly. Include only context that helps the reader act or decide.
- Report facts, changes, verification, limitations, and next steps precisely.
- Do not add generic acknowledgements, conclusions, or offers of more help.
For pull requests and commits:
- Use an imperative, specific title that describes the outcome.
- Explain the problem, the material change, and how it was verified.
- Separate motivation from implementation detail. Mention risks or follow-up work only
when they are concrete.
- Do not reproduce the diff or use promotional language.
For issues and bug reports:
- Use an outcome- or symptom-focused title.
- Include the observed behaviour, expected behaviour, reproduction steps, relevant
environment, and evidence when available.
- Distinguish facts from hypotheses. Do not present an unverified cause as certain.
- State acceptance criteria as observable outcomes.
For reviews:
- Lead with actionable findings ordered by severity.
- Identify the location, consequence, and required correction.
- Use direct, respectful language. Critique the change, not the author.
- Do not dilute concrete findings with generic praise or low-value style comments.
For reference documentation:
- Describe what an API element does in present tense.
- State requirements, defaults, ranges, units, side effects, errors, and return values
explicitly.
- Use consistent terminology and parallel descriptions across related elements.
## Final check
Before sending or publishing technical writing, check that it:
- Answers the reader's likely question first.
- Uses British English spelling outside literal or official names.
- Uses active voice, present tense, and second person where appropriate.
- Removes filler, vague claims, repeated context, and unnecessary structure.
- Formats code, UI labels, links, lists, and headings consistently.
- Gives procedures in executable order with prerequisites and placeholders explained.
- Separates verified facts from assumptions.
- Remains accurate when read without hidden conversational context.
For a question not covered here, consult the relevant page in the current
[Google developer documentation style guide](https://developers.google.com/style),
then apply the British English spelling exception.