Style Guide Creation skill for Codex

A useful style guide is short, decides things, and is enforced. It answers the questions writers actually argue about in this project, shows a before-and-after for every rule, and turns every mechanical rule into a linter check so reviewers stop leaving the same comment. A 60-page guide nobody opens is a failure regardless of quality.

Scope it first

Ask the user (or infer from the request) and write the answers at the top of the guide:

Question	Typical answers
What content does it govern?	Developer docs, product UI text, API reference, support articles, marketing site
Who writes it?	Engineers, tech writers, PMs, support, contractors, community
Who are the readers?	Developers integrating an API, admins, end users, buyers
What base guide do we inherit?	Google developer documentation style guide, Microsoft Writing Style Guide, Chicago, AP
How is it enforced?	Vale in CI, PR review checklist, TMS QA checks

Pick one base guide and defer to it for everything you do not decide. Google or Microsoft suit technical docs; Chicago suits long-form and books; AP suits news-like marketing and blogs. Your guide then contains only overrides and project-specific decisions.

Marketing positioning and brand personality work belongs to $brand-voice. Editing a specific document belongs to $copy-editing. This skill builds the rulebook.

Workflow

- [ ] 1. Collect the corpus (docs folder, UI strings, top support articles)
- [ ] 2. Mine it for inconsistencies and frequent review comments
- [ ] 3. Decide: base guide, voice and tone, the contested rules
- [ ] 4. Build the word list (preferred term, avoid, notes)
- [ ] 5. Write the guide: rule, reason, before/after, one page per area
- [ ] 6. Encode mechanical rules as Vale rules; run on the corpus
- [ ] 7. Triage hits: fix, tune the rule, or accept as exception
- [ ] 8. Publish next to the content and link from AGENTS.md and CONTRIBUTING.md

Mine the corpus for decisions

Decisions should come from real disagreements in the content, not from a generic list.

# term variants: count each spelling
for t in "log in" "login" "log-in" "sign in" "signin"; do
  printf '%-10s %s\n' "$t" "$(rg -i -o --no-filename "\b$t\b" docs/ | wc -l)"; done

rg -o --no-filename '^#{1,3} .*' docs/ | head -40         # heading case in use
rg -c '\be\.g\.|\bi\.e\.' docs/ | sort -t: -k2 -nr | head  # latinisms
rg -o --no-filename '\b[A-Z]{2,6}\b' docs/ | sort | uniq -c | sort -nr | head -30  # acronyms

Also read recent review comments on docs PRs (gh pr list --label docs --state merged then gh pr view <n> --comments; needs network). Comments repeated three or more times become rules.

What to decide

Keep each area to the rules that matter for this project.

Area	Decisions to make
Voice	3-4 traits, each with “this, not that” (direct, not curt; friendly, not jokey)
Tone by context	Error messages, onboarding, release notes, outage comms, legal
Person and tense	Second person (“you”), present tense, active voice by default
Headings	Sentence case or title case; task headings as imperatives (“Create a token”)
Terminology	Product names, feature names, capitalization, what to never call things
UI references	Bold for UI labels, exact label text, “select” vs “click”
Code in prose	Backticks for identifiers, commands, file names, values
Numbers, dates, units	Numerals vs words, ISO dates in technical content, space before units
Lists and punctuation	Serial comma, list item punctuation, when to use tables
Inclusive language	allowlist/denylist, primary/replica, main; no idioms that exclude
Links	Descriptive link text, never “click here”; relative links inside docs
Accessibility	Alt text, no meaning by color only, no directional words (“see below”)

Rule format

Every rule gets: the rule, one line of why, and a before/after. Without the example, people interpret the rule differently.

### Use sentence case for headings
Easier to scan and avoids debates over which words to capitalize.

| Avoid | Use |
|---|---|
| Configure Your Webhook Endpoint | Configure your webhook endpoint |

Word list

The word list is the most-used page. Keep it alphabetical and in a table:

| Use | Avoid | Notes |
|---|---|---|
| sign in (verb), sign-in (noun) | log in, login | Matches the UI button |
| workspace | org, organisation | "Organization" is a billing entity, different thing |
| Acme CLI | acme-cli, the CLI tool | `acme` when showing the command itself |
| select | click, hit | Works for touch and keyboard |
| allowlist, denylist | whitelist, blacklist | |

Enforce with Vale

Vale is the default prose linter (works offline once installed; vale sync downloads packages and needs network). Install with the system package manager (brew install vale) or the project’s tooling; ask before installing.

# .vale.ini
StylesPath = .github/styles
MinAlertLevel = suggestion
Vocab = Acme
Packages = Google

[*.{md,mdx}]
BasedOnStyles = Vale, Google, Acme
Google.Headings = NO          # we override heading rules in Acme

Vocabulary lives at .github/styles/config/vocabularies/Acme/accept.txt (one term or regex per line; accepted terms are also exempt from spelling errors) and reject.txt.

Word-list rules become substitution rules:

# .github/styles/Acme/Terms.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
ignorecase: true
swap:
  log in: sign in
  login: sign-in
  whitelist: allowlist
  blacklist: denylist
  org: workspace

Heading case as a capitalization rule:

# .github/styles/Acme/Headings.yml
extends: capitalization
message: "'%s' should use sentence case."
level: warning
scope: heading
match: $sentence
exceptions:
  - Acme
  - API
  - GitHub

vale sync                      # fetch packages listed in Packages (network)
vale docs/                     # lint the corpus
vale --output=line docs/ | wc -l

Run it against the whole corpus before turning it on in CI. If a rule produces hundreds of hits, either fix them in one dedicated PR or start the rule at suggestion level. Turn on error level only for rules with near-zero false positives; style judgment calls stay as warning or suggestion and stay in human review.

Swap keys are regular expressions and Vale adds word boundaries itself, so org will not match inside organize. In CI, report only on changed lines so legacy content does not block every PR; the errata-ai/vale-action GitHub Action runs through reviewdog and filters to added lines by default.

Structure of the guide

# <Project> writing style guide
Applies to: <content types>. Base guide: <name + link>; this page lists only our decisions.
Last reviewed: <YYYY-MM>. Owner: <role>. Linter: Vale (.vale.ini).

## Voice and tone          (traits with this-not-that, tone table by context)
## Grammar and mechanics   (person, tense, headings, lists, numbers, dates)
## Formatting              (code, UI labels, links, admonitions, tables)
## Word list
## Inclusive and accessible writing
## Content types           (templates or links: tutorial, how-to, reference, release notes)
## Changing this guide     (open a PR; rules need a reason and an example)

Store it next to the content (docs/style-guide.md or the docs site), and add one line to AGENTS.md so Codex and other agents follow it: “Docs follow docs/style-guide.md; run vale <changed files> before committing docs.”

Gotchas

• Copying a base guide’s rules into your guide creates two sources of truth. Link, do not copy.
• Rules without reasons get ignored or argued about forever. One line of why is enough.
• Too many error-level Vale rules train people to disable Vale. Keep errors for the word list and objective mechanics.
• UI text and docs drift apart: pull the exact UI labels from the source strings file rather than from memory when writing the word list.
• A guide with no owner and no review date goes stale within a year.

Verification

• Every rule has a before/after example; every word-list row has a preferred term.
• vale docs/ runs clean of errors after the cleanup PR, and the rule count by level is reported to the user.
• Spot-check: pick three recent docs PR comments; the guide now answers each one.
• AGENTS.md and CONTRIBUTING.md link to the guide.