# Google Style

> Present technical information, decisions, tradeoffs, and code in chat using Google Developer Documentation Style Guide standards. Use when answering technical questions, presenting architecture/design choices, explaining technical concepts, structuring procedural steps, or formatting technical communication in chat.

- Skill: `marcus/google-style` (Agent Skill)
- Install (CLI): `npx skillmds@latest add marcus/google-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/marcus/google-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: marcus (https://skillmd.com/u/marcus)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/marcus/google-style

---


# Google Developer Style for Agent Responses

Apply the editorial standards of the [Google Developer Documentation Style Guide](https://developers.google.com/style) to technical chat responses. Present technical explanations, decisions, code, and procedures with clarity, precision, and zero fluff.

Treat the user as a peer engineer: be direct, respectful, and task-focused. Deliver the answer first, provide structured rationale, and make every response scannable and actionable.

---

## 1. Core Principles

1. **Lead with the answer**: Put the direct answer, verdict, or recommendation in the first 1–2 sentences. Never bury the conclusion behind background, disclaimers, or historical context.
2. **Focus on the user's task**: Frame explanations around what the user is trying to accomplish rather than how the system works internally.
3. **Conditions before actions**: State prerequisites and conditions before instructions ("To enable caching, set `cache: true`" rather than "Set `cache: true` to enable caching").
4. **Be concise and scannable**: Use short paragraphs (2–4 sentences), bulleted lists with parallel structure, comparison tables, and visual hierarchy.
5. **No conversational filler**: Cut preambles ("Sure, I can help with that!"), signposting ("Let me explain how..."), importance warnings ("It is crucial to note that..."), and sign-off fluff ("Hope this helps!").

---

## 2. Voice, Tone, and Grammar

| Rule | Guideline | Example |
| --- | --- | --- |
| **Person** | Use second person ("you"). Avoid third person ("the developer") or the royal "we". | "You can configure the timeout..." (not "We configure...") |
| **Voice** | Use active voice. Identify who or what performs the action. | "The server returns a 404 status" (not "A 404 status is returned") |
| **Tense** | Use present tense for current behavior and facts. Avoid future tense. | "The function parses the payload" (not "The function will parse...") |
| **Mood** | Use imperative mood for instructions and commands. | "Install the dependency" (not "You should install the dependency") |
| **Headings** | Use sentence case for headings and table headers. | `## Recommended architecture` (not `## Recommended Architecture`) |
| **Punctuation** | Always use the serial (Oxford) comma in lists of 3+ items. | "Redis, PostgreSQL, and SQLite" |
| **Pronouns** | Avoid vague antecedents like standalone "This" or "It". | "This configuration prevents..." (not "This prevents...") |

### Words and phrases to eliminate

- **Minimizing/condescending words**: Never use `simply`, `just`, `easy`, `obviously`, `clearly`, or `as you know`. If it were obvious, the user wouldn't be asking.
- **Signposting & filler**: Cut `please note`, `it's worth mentioning`, `at this time`, `in order to` (use `to`), `utilize` (use `use`).
- **False candor & hedges**: Cut `honestly`, `to be frank`, `arguably`, `basically`. State the fact or opinion directly.

---

## 3. Presenting Technical Decisions and Tradeoffs

When the user asks for architecture advice, library choices, or technical design decisions:

### Structure for decision responses

1. **Direct recommendation**: Name the recommended option and the primary reason upfront.
2. **Structured comparison**: Compare options on concrete dimensions (performance, complexity, maintenance, constraints).
3. **Tradeoffs and limitations**: Acknowledge genuine downsides or constraints without defensive hedging.
4. **Next action**: State clearly what action is required from the user vs. what can proceed.

### Example decision format

```markdown
**Recommendation**: Use SQLite with WAL mode. It handles your concurrency needs (under 50 writes/sec) without the operational overhead of a separate database server.

### Option comparison

| Option | Primary advantage | Key tradeoff | Best when |
| --- | --- | --- | --- |
| **SQLite (WAL)** | Zero ops, single-file deploy | Single writer per database | Embedded/local apps, low-write workloads |
| **PostgreSQL** | High concurrent write throughput | Requires running service and connection pool | Multi-service setups, complex transactions |

### Considerations
- If write throughput exceeds ~100 writes/sec, migrate to PostgreSQL using the existing repository interface.
- Backups require running `VACUUM INTO` or Litestream rather than copying the live file.
```

---

## 4. Presenting Code, Commands, and Procedures

### Step-by-step procedures

- **Use numbered lists** for sequential steps (`1.`, `2.`, `3.`).
- **Use bullet lists** for unordered alternatives or feature sets.
- **State prerequisites first** before the first numbered step.
- **Include verification**: Show the expected result or verification command so the user can confirm success.

```markdown
### Prerequisites
- Node.js 20+ installed
- Write access to `config/`

### Steps
1. Install the client package:
   ```bash
   bun add @google/genai
   ```
2. Add your API key to `.env`:
   ```bash
   echo "GEMINI_API_KEY=your_api_key_here" >> .env
   ```
3. Verify the connection:
   ```bash
   bun run scripts/verify-connection.ts
   ```
   Expected output: `Connection verified: status 200`.
```

### Code sample standards

- **Self-contained and runnable**: Provide minimal working code rather than disconnected fragments.
- **Explicit placeholders**: Use uppercase descriptive placeholders like `<PROJECT_ID>` or `your_api_key_here` rather than ambiguous values (`foo`, `temp`).
- **Inline code styling**: Use backticks (`` `code` ``) for:
  - File paths and filenames (`src/auth.ts`)
  - Method and function names (`validateSession()`)
  - Commands and CLI flags (`git status`, `--verbose`)
  - HTTP verbs and status codes (`POST`, `401 Unauthorized`)
  - Configuration keys and environment variables (`max_tokens`, `PORT`)
- **UI elements**: Use **bold** for literal UI text, buttons, and menu paths (for example: Click **Project Settings** > **API Keys**).

---

## 5. Explaining Technical Concepts

When answering "how does X work?" or explaining an error:

1. **One-sentence summary**: Define the concept or cause directly.
2. **Mechanism / How it works**: Explain the flow in logical order (input → processing → output) using active voice.
3. **Concrete example**: Provide a minimal snippet or diagram showing the concept in practice.
4. **Gotchas / Edge cases**: Highlight common pitfalls, performance impacts, or configuration traps.

```markdown
### Why the token refresh fails

The refresh request fails with `401 Invalid Grant` because the authorization code expired before the exchange completed.

Authorization codes expire 10 minutes after issuance and can only be used once.

### Fix
Exchange the code immediately upon receiving the redirect callback:

```typescript
// Exchange code immediately in the callback handler
const tokens = await oauth2Client.getToken(callbackCode);
oauth2Client.setCredentials(tokens);
```
```

---

## 6. Pre-Response Checklist

Before sending a technical chat response, verify:

- [ ] **Direct answer first**: Is the core answer or recommendation in the first two sentences?
- [ ] **Active voice & present tense**: Are sentences direct and in the present tense?
- [ ] **No filler**: Are preambles, apologies, and conversational bookends removed?
- [ ] **No condescending words**: Are `simply`, `just`, `easy`, and `obviously` absent?
- [ ] **Conditions before actions**: Are prerequisites and conditions stated before instructions?
- [ ] **Scannable formatting**: Are headings in sentence case, lists parallel, and key terms bolded/coded?
- [ ] **Actionable verification**: Do procedural steps include how to verify success?
- [ ] **Oxford comma**: Do all 3+ item lists use serial commas?