Rewrite Prose

---
name: rewrite-prose
description: |
  Use this skill when writing, proofreading, or polishing the
  wording of plain text documents — Markdown (.md), TeX (.tex),
  or .txt files — and the English text embedded in source
  code: comments, docstrings, log messages, error messages,
  and user-facing strings. Apply the rules conservatively:
  preserve the author's voice and meaning, replace awkward
  phrasing with cleaner alternatives, fix grammar, and cut
  filler words, clichés, and tautologies. Do NOT apply to
  the surrounding code, YAML, JSON, or quoted material.
---

Never change the tone of voice; a formal text stays formal,
  a casual one stays casual.

Never change the meaning; if a sentence is ambiguous, ask
  the author rather than guess.

Replace awkward constructions with cleaner ones that mean
  the same thing (`We made a decision to proceed` →
  `We decided to proceed`).

Use the present tense instead of `will`, except when the
  future itself is the point of the sentence.

Cut clichés like `at the end of the day`, `needless to say`,
  `low-hanging fruit`, and `circle back`.

Cut tautologies (`end result` → `result`, `each and every`
  → `each`, `free gift` → `gift`).

Use the Oxford comma in lists of three or more items.

Do not use `etc.`, `and so on`, `and so forth`, or trailing
  ellipses; either complete the list or name the category.

Prefer active voice unless the actor is unknown or
  irrelevant.

Cut filler words like `very`, `really`, `just`, `actually`,
  `basically`, `essentially`; replace `very X` with a
  stronger single word.

Replace `in order to` with `to`.

Prefer short Anglo-Saxon words over Latinate ones (`use`
  not `utilize`, `start` not `commence`, `help` not
  `facilitate`).

Drop `that` when removing it does not hurt readability.

Avoid double negatives (`not uncommon` → `common`).

Keep parallel grammatical structure across items in a list.

Split sentences that carry two ideas joined by `and` or
  `but`.

Avoid `there is` and `there are`, which delay the real
  subject.

Avoid hedging words like `perhaps`, `maybe`, `arguably`,
  `sort of` unless the uncertainty is real.

When writing for AI agents, place one thought per paragraph,
  so the agent can locate, quote, and reason about each idea
  without untangling it from neighbors.

Headings carry no trailing period.

In Markdown, place link URLs at the bottom of the file as
  reference definitions and use shortcut-style links in the
  text (`[Microsoft]` with `[Microsoft]: https://microsoft.com`
  at the end), not inline (`[Microsoft](https://microsoft.com)`).

Spell numbers one through nine as words and write 10 and up
  as digits, except in tables, code, versions, and
  measurements.

Do not touch the author's chosen vocabulary when correct,
  deliberate stylistic choices, quoted text, code, proper
  names, or domain jargon used correctly.

Make the smallest change that fixes the problem, and show
  the original next to a non-trivial rewrite so the author
  can confirm the meaning was preserved.