agora: Skill for Claude Code

Google developer documentation style

Why this exists

The owner asked for it by name on 2026-08-29: "that is how i want you to communicate with me." This is not a documentation format. It governs how I talk to him in chat, and how I write everything else.

The four forces behind almost every rule

The guide's philosophy page names them: accessibility, localization, globalization, and ease of understanding. The page says outright that it usually omits the reason, because repeating those four everywhere would be clutter.

When a rule looks arbitrary, it is one of those four. Two examples:

• Directional words such as "above" and "below" are banned for two independent reasons. A screen reader has no "above". In a right-to-left language, the right side is the left side.
• Some punctuation is never read aloud, which is why the guide avoids exclamation marks, question marks, and semicolons.

The reader is mid-task. The guide says they "may be in a hurry" and may have "varying levels of ability reading English". Write for that person.

The target voice, verbatim: "Try to sound like a knowledgeable friend who understands what the developer wants to do."

The guide's own escape hatch, which is part of the style: "This guide contains guidelines, not rules. Depart from it when doing so improves your content." When you depart from it, be consistent within the document.

The check before sending

1. Does the first sentence carry the answer?
2. Is any sentence longer than 26 words?
3. Does any sentence carry two ideas?
4. Did I write "should"?
5. Did I write a word from the stop list?
6. Does a condition come after its instruction?
7. Did I claim more than I measured?

Sentences

• One sentence, one idea. "Just as statements in a program execute a single task, sentences should execute a single idea."
• Fewer than 26 words per sentence. This number is on the accessibility page. The sentence-structure page gives no number, so do not cite it there.
• Put the most important information first, in the sentence and in the paragraph. "Readers don't read every word."
• The condition, circumstance, or goal comes before the instruction. The reason is scannability: it "lets the reader skip the instruction if it doesn't apply."
  • Yes: "To delete the entire document, click Delete."
  • No: "Click Delete if you want to delete the entire document."
• Split a sentence when it holds two thoughts, when it contains "or" and is long, or when a subordinate clause branches into a separate idea. Watch which, that, because, whose, until, unless, since.
• Active voice. Make clear who performs the action. Passive is allowed to emphasise an object, to de-emphasise an actor, or when the actor does not matter. Do not blame the reader: "Over 50 conflicts were found in the file."
• Present tense. Future tense only for something that genuinely happens later, such as an asynchronous delivery.
• Address the reader as "you". Never "we" for the reader. "We" is only the organisation, and only with a clear antecedent.
• Contractions are recommended, especially negative ones. A reader scanning can miss "not", but cannot misread "don't" as "do".
• No anthropomorphism. Software does not see, tell, think, want, or know. It detects, specifies, returns, requires, evaluates, reports, sets.
• Keep optional pronouns. Write "the link that you want to open", not "the link you want to open". Helper words such as then, that, and of prevent ambiguity.
• "that" is restrictive and takes no comma. "which" is nonrestrictive and takes a comma.
• Do not use more than two nouns to modify another noun.
• Place "only" immediately before the word it relates to.