Write Well: Claude Code skill for AI writing quality

Write Well is a Claude Code skill, built at AR Labs, for checking and improving prose that AI agents write. It finds the habits that make machine-written text tiring or hard to follow, rewrites them, and scores the result. Its most important check is not about style: it asks whether the reader has been given the context the text assumes. We use it on writing that leaves the agent session: published pages, messages to other people, design documents and the summaries an agent writes after a long run.

How it works

The skill has two modes. In the passive mode, our short set of writing rules loads into every agent session and the skill adds nothing. In the active mode, someone asks for a diagnosis, a rewrite, a score or a draft, and the skill runs one of four workflows.

The diagnosis works through five layers of "AI tells", the patterns that mark prose as generated:

The score rates five dimensions from 1 to 10: directness (does each sentence state something, or only announce it?), rhythm (does sentence length vary?), trust (does it respect the reader's intelligence?), authenticity (does it sound like a person?) and density (could anything be cut without losing meaning?). Below 25 calls for a significant rewrite; 38 and above is acceptable with minor fixes. The score is a diagnosis, not a gate.

A rewrite runs the diagnosis silently, fixes what it found, re-scores, and returns the new text with the before and after scores. It changes form, never the argument, and leaves tables, checklists and code untouched. Generate drafts new prose with the rules active; for anything over 300 words it writes one paragraph at a time and corrects course after each, rather than reviewing a finished draft. For content published under the name of Richard M. Thompson, who founded AR Labs, a voice profile drawn from his writing applies; it is never used for anything else.

The judgement it encodes

Grounding first. Models trained with human feedback measurably skip the "grounding acts" people use to establish shared reference (Shaikh et al., Grounding Gaps in Language Model Generations (NAACL 2024)). In practice an agent refers to files, decisions and earlier turns as if the reader had been in its context window. The skill's readability rubric checks four things: a "the X" whose X was never introduced, terms not defined at first use for the declared audience, a buried lead, and an ordering whose direction of dependency is not stated. The fix is layered: add a plain-English on-ramp, then the mechanism with terms defined, then the precise detail. Precision is never deleted to buy readability.

No banned-word list. The skill once kept one and retired it. A fixed list flagged words that were right in context and pushed prose toward stilted substitutes, which cost more than the tells it caught. A word is flagged only when it does no work in its own sentence.

Decide the audience before running the checks. Structural and formatting checks apply only to public-facing writing. Running them on a design document produces cosmetic noise and buries the grounding findings, which for internal text are usually the only ones worth acting on.

Rules in context are not rules obeyed. A prose rule competes with a habit the model learned in training, and under pressure the habit wins. So the skill asks for a deliberate pass over anything a person will forward, instead of trusting that the always-loaded rules held.

What exists today

The skill is in use across our work, and its rules load into every agent session. Its readability rubric is the one Doc Review hands to its readability reviewer, so both skills judge grounding the same way.

Example

Illustrative example. Diagnosing an agent's end-of-run status note:

## Diagnosis Report
 
Audience: internal (a status note to the project owner).
Layers 2 and 4 skipped: structural tells apply to public writing only.
 
Layer 1 (Word choice): 1
- "a genuinely robust fix": "genuinely" adds nothing; say what the
  fix guards against.
 
Layer 3 (Throat-clearing): 1
- "Here's the headline:": delete; start with the finding.
 
Layer 5 (Grounding/Readability): 3
- R1 "the reconciler" is used before anything introduces it.
  Fix: "the reconciler, the nightly job that matches payments to
  invoices,".
- R2 "HITL" is undefined for this reader. Fix: "human-in-the-loop
  (a person approves each step)".
- R3 The note opens on the mechanism. Fix: open with what changed
  for the owner, then how.
 
Quality Score: 34/50
Verdict: Needs light editing