/writing-guidelines

name: writing-guidelines
description: This skill should be used when the user asks to "review writing", "check documentation style", "audit interface copy", or "apply writing guidelines".
metadata:
  argument-hint: <file-or-pattern>
license: MIT

Writing Guidelines

Review the files or patterns provided by the user for compliance.

Read files, check against rules below. Output concise but comprehensive: sacrifice grammar for brevity. High signal-to-noise.

Rules

Planning & content type

• Every page has a plan (overview, goal, audience, content plan, open questions) referenced or linked
• Content type declared in `meta.contentType`: `Tutorial`, `How-to`, `Reference`, `Conceptual`, `Troubleshooting`, or `Landing`
• Title is user-shaped (the user's question), not feature-shaped (the engineer's name)
• Page does one job: tutorial OR how-to OR reference, not three at once
• Goal is verb-driven (Bloom's taxonomy): "configure", "explain", "debug" (testable)
• Multi-audience pages: short shared opener, then technical subsections

Voice & tone

• Active voice. Mental test: append "by monkeys". If the sentence parses, rewrite
• Direct address: `you`, never `the user` or `one can`
• Imperative for steps: "Click **Add Project**", not "You will need to click **Add Project**"
• Sentences under 20 words target
• Contractions encouraged (`you'll`, `it's`) for warmth
• Present tense unless describing future behavior
• Limit `we`: only for deliberate organization actions ("we recommend", "we deprecated"), never as a stand-in for "you"
• No rhetorical questions (sounds like marketing)
• Second-read test: read each sentence once at speech pace; if you re-read to parse it, name the subject, the action, and the consequence (kill metaphor verbs and pronouns reaching back several sentences)

Banned words

• `easy`, `simple`, `quick`: puts pressure on the reader and reads as marketing; replace with concrete description ("one command", "default settings", "most projects don't need this")
• `very`, `just`, `really`: filler; cut or rewrite

Concision

• Earn every detail: cut a number, name, or implementation detail if a more general phrasing wouldn't change the reader's understanding or action
• Weasel words: replace vague qualifiers (`significantly`, `many`, `often`, `typically`, `generally`) with a specific number or claim
• Vague quantifiers: no `near-zero`, `sub-second`, `most requests`; give the figure and cite it (`99.37% of requests see zero cold starts`)
• Filler/metaphor verbs: name the action instead of reaching for cadence (`moves through`, `lands`, `carries`, `hits` → the literal step)

AI-generated tells (flag these)

• Summary-style transitions: never open a paragraph by recapping the last one (`With this setup complete…`, `Now that we've explored…`); pivot straight to the next point (`In practice…`, `The catch is…`)
• Stop-start sentences: don't split one dependent idea into choppy fragments (`Previously this was manual. Now it's automatic. This saves time.` → one sentence); short sentences for emphasis are fine
• Spec-sheet voice: rewrite sentences that read like a system reading a datasheet (`provides`, `is configurable`, `is explicitly labeled`)
• Cold-open paragraphs: a body paragraph whose first sentence works as a standalone heading has no antecedent; carry the prior subject forward (`Because…`, `Once…`)
• Personified artifacts: machines don't perform human-physical actions (`hand the browser a URL` → `the browser fetches the URL`; `the token holds…` → `the token is stored…`)
• Reused framing: the angle must come from this page, not a template (`The question most teams face is whether…`)

Tone, by content type

• **Tutorial**: warm, encouraging, predictable structure, no traps
• **How-to**: terse, direct (reader is mid-task)
• **Reference**: neutral, exhaustive, quotable
• **Conceptual**: explain like the reader will teach it back; examples and analogies welcome
• **Troubleshooting**: empathetic but not apologetic; acknowledge then fix

Headings

• Sentence case for page headings (`H1` `H2` `H3`): "Configure environment variables", not "Configure Environment Variables"
• Title case for nav labels: "Configuring Environment Variables"
• `meta.title` becomes the `H1`; `meta.navLabel` becomes the sidebar entry
• Subheadings descriptive, not cute: "Caveats when self-hosting on Cloudflare", not "Caveats"
• Reader should be able to guess section content from the heading alone

Structure

• Every page opens with a one-paragraph TL;DR of what the page covers
• Every major section opens with a summary sentence
• Acronyms spelled out on first use: "Content Security Policy (CSP) blocks inline scripts"
• Define every term the first time you use it (link to its conceptual page)
• Reference docs organized by surface; education docs organized by reader task
• Keep paragraphs to 2 to 4 sentences; split anything longer or covering two ideas

Lists

• Three or more list-shaped items in a paragraph: convert to a list
• Bulleted for unordered; numbered for ordered (lifecycles, sequential steps)
• Always introduce a list with a colon
• No periods at the end of list items unless they are full sentences
• Bold/description format: `- **Term**: description here` (colon after bold term)

Code

• Code blocks need a language tag for syntax highlighting
• TypeScript is the default for new code unless the surface is genuinely language-agnostic
• Multi-step flows wrapped in `<Steps/>` so structure is visible
• Highlight load-bearing lines: `` ```typescript {8-12,23-37} ``
• ≤80 columns per line in snippets
• ≤25 lines per snippet; split longer blocks with prose
• Omit defaults; don't repeat variable definitions, use shared var
• Minimal comments in code blocks; prefer prose explanation
• Explain what every code block does in prose (don't drop and run)
• Don't reference full example files at the end of guides ("See `train.py`"); the guide is the deliverable

Placehold