Clarity

Clarity

Most bad writing produced with an agent is not ungrammatical. It is correct, fluent, well organized, and empty. It could have been written about any company, by any author, in any year. That is the failure this skill exists to catch, and every rule below serves it.

The premise, in one line:

Writing reads as a person's when it carries information only that person had.
Everything else is surface.

Surface work still matters, and this skill does plenty of it. But run it in the right order. A draft with nothing in it cannot be rescued by deleting its adverbs.

README.md argues for the eighteen rules this skill implements. Read it once for the reasoning; the mechanics below are enough to work from. The mapping:

 1  write for one reader        Gate 0 q5; interview q3
 2  what they bring vs need     Gate 0 q6
 3  one arguable point          Gate 0 q1, in the form its register asks for
 4  only you could say it       Gate 0 q2 and q4; the only-you test; the interview
 5  every sentence pays         tells 1.8 (padding); the only-you test
 6  specific enough to be wrong verifiable + sensory axes; tells 1.3; craft 1
 7  someone in the sentence     edit pass 3; tells 3.5, 3.6
 8  plain word, short sentence  tells 3.12 (overloaded), section 4; prose_stats
 9  cut, then stop              edit pass 5; calibration 3.2 and 4.1
10  say the relation            edit pass 9; tells 3.2
11  position, and its weakness  tells 1.6, 1.7
12  say it the way you'd say it self-check (the lunch test); tells section 7
13  do not perform              the Never list; calibration section 2
14  the first sentence's job    edit pass 1
15  paragraphs earn the next    edit pass 10; tells 2.6
16  stop where the thought does edit pass 12; tells 2.5
17  rewrite, do not smooth      edit pass 14b; co-write mode; interview
18  read it aloud               edit pass 16
 -  register                    Gate 0 opens on it; only argument owes a thesis
 -  warmth                      references/craft.md; edit pass 15; the affect check

Load references on demand

references/interview.md    — the perspective extraction protocol. Read before drafting anything
                             substantial from scratch, or when a draft is fluent but hollow.
references/tells.md        — the full pattern catalog with earned/unearned adjudication.
                             Read for any real edit pass or review.
references/craft.md        — the positive half: images, stance, rhythm, and the affect check.
                             Read after the edit pass, and always for evocation or narrative.
references/calibration.md  — measured targets and the overcorrection traps. Read before you
                             start cutting hedges, adverbs, dashes, or passives at scale.
references/critique.md     — review output format and worked before/after examples.
                             Read when the user wants a critique rather than a rewrite.

Pick the mode

If the invocation carried an argument, the first word of it selects the mode. Obey it without asking. Everything after that word is the topic, the file, or the pasted text.

interview | write | draft | new     Co-write. Interview first. Do not draft a word before it.
rewrite | edit | fix | humanize     Rewrite. Substance gate, then the edit pass.
review | critique | check           Review. references/critique.md format. Produce no new file.
lint | stats                        Run the scripts and read the output. No prose changes.

So /clarity interview why our incident reviews stopped working goes straight to the interview about that topic, and /clarity review draft.md produces a critique of that file and nothing else. An unrecognised first word is part of the topic, not a mode.

With no argument, infer:

| Situation | Mode | Where to start | |---|---|---| | The piece does not exist yet | Co-write | Interview first. Do not draft. | | A draft exists and needs to be better | Rewrite | Substance gate, then the edit pass. | | The user wants feedback, not a new file | Review | references/critique.md format. |

When the mode is still ambiguous, ask once, in one sentence. Then commit.

---

Gate 0: the substance gate

Run this before any stylistic edit, in every mode.

First, name the register, because the rest of the gate depends on it. Only one of these owes the reader an arguable thesis, and applying the argument rules to the other four is the most common way to wreck a good piece.

Argument     persuades toward a claim someone could dispute.        needs a thesis
Explanation  makes a mechanism understandable.                      needs a mechanism
Evocation    makes the reader feel the size or texture of a thing.  needs images
Narrative    carries the reader through events.                     needs a scene
Guide        gets the reader to a working outcome.                  needs steps

A celebration, a tour, an obituary, a launch announcement, and a piece about wonder are all evocation. Demanding a disputable thesis from one produces a contrarian debunking, which is the failure mode to watch for: if your rewrite has become an argument against something, check that the brief actually asked for an argument.

Then the questions. Question 1 takes the form its register asks for:

1. What is the one point? State it in a single sentence. A topic is not a point: "Code
   review in the age of agents" is a subject and will wander into completeness.
   For an argument, the sentence must be disputable: "review should start from what the
   change was trying to do, not from the lines it touched."
   For an explanation, it is the mechanism: "a model predicts the next token, and every
   surprising behaviour follows from that."
   For an evocation, it is the feeling the reader should leave holding: "our existence is
   improbable and worth being astonished by." That is not disputable and does not need
   to be.
2. What does this say that is not the consensus view of anyone who has read three
   articles on the topic?
3. What in here could be wrong? Name the specific claim a reader could check and dispute.
4. Which sentences could only have been written by this author?
5. Who is the one reader? Name a person you can picture, not a segment. The engineer three
   years in who keeps hitting this. The colleague who disagreed last week.
6. What does that reader already carry, and what do they still need? These are two
   separate questions and the gap between the answers is the piece. A draft that explains
   what the reader knows insults them; a draft that assumes what they lack loses them.
   Most drafts do both in different paragraphs, because nobody asked.

Questions 5 and 6 decide scope, register, and how much to explain. Ask them before drafting and most later decisions answer themselves. If the author cannot name the reader, ask; do not pick one for them and proceed quietly.

If question 1 produces two points, the piece is two pieces. Pick the one the author cares more about and offer to cut the other, or say plainly that the draft is carrying more than it can land. Everything after this, from tone through to the last sentence, is decided by that one point.

If question 1 yields only a topic, or if questions 2 through 4 come back as "nothing," "nothing," and "none," the problem is not the prose.

The failed-gate rule, which every mode in this skill defers to. Report the diagnosis first, in two or three sentences, naming what the piece is missing. Offer the extraction interview in references/interview.md. Then, if the author still wants the edit, do it in full and say what it bought and what it did not. Never silently polish a hollow draft, because the polish is what makes it look finished. And never withhold the work because the diagnosis was unwelcome. Report, deliver, label.

The only-you test

Apply per paragraph. Could this paragraph appear, near-verbatim, in someone else's piece on the same subject? If yes, it is filler even when every word of it is true. Cut it, or replace it with the thing the author knows that the other writer does not.

Two kinds of concrete

"Be specific" hides two different operations, and a rewrite that only knows one of them turns into a bibliography.

Verifiable specificity replaces a claim nobody can check with one they can.

Rung 0  abstraction     "Teams struggle with dependency risk."
Rung 1  category        "We once installed a package that made us vulnerable."
Rung 2  instance        "A transitive dependency of a lint plugin started
                         exfiltrating env vars in a patch release."
Rung 3  named instance  "event-stream, November 2018, eight million weekly
                         downloads, and the payload only fired inside Copay."

Rung 1 is the trap. It has the grammar of a specific and the content of an abstraction, so it reads exactly like Rung 0. A load-bearing claim needs Rung 2 or better.

Sensory concreteness replaces a word the reader processes with one they can picture, hear, or feel in the body. This is what Zinsser and Strunk actually mean by concrete, and it is the axis most rewrites miss.

abstract    "the profound emotional experience of music"
sensory     "the deep stirring of the soul when we listen to Mozart's Requiem"

abstract    "early tools conferred a hunting advantage"
sensory     "these were primitive, but could tear through skin and muscle"

abstract    "we want the piece to move you"
sensory     "we want to make the hairs on the back of your neck stand up"

The two axes are independent, and most pieces need the second more. A date and a citation make a claim checkable. They do nothing to make a reader see anything. If your rewrite has added four references and no images, you have climbed one ladder and ignored the other. An evocation may need almost no verifiable specificity and a great deal of the sensory kind.

The honesty limit, which overrides the ladder. Never invent a Rung 3. Do not manufacture a name, number, date, quote, benchmark, or remembered incident to satisfy a specificity target. When only the author holds the detail, leave a marked slot and say what is missing:

[TK: which package, and roughly when?]

A cut is better than a fabrication. A slot is better than a cut. A hypothetical clearly framed as hypothetical is fine; a fake memory in the author's voice is not.

---

Mode: co-write

The single highest-leverage finding behind this skill, measured across eighteen full-length checks against a leading AI-text classifier in August 2026:

The share of words the author actually wrote predicted the outcome almost linearly.
Register, structure, lint compliance, and literary quality moved it by about ten points.
Authorship share moved it by eighty.

And the sharper version of the same result, from a controlled pair on the same true story:

Provenance works as tokens, never as information.

Telling the model the author's real situation, motivation, audience, and framework, then letting the model word it, scored the same as fully invented content. The same material in the author's own unsmoothed sentences read as the author's. So the workflow is not "gather context, then generate." It is "gather sentences, then arrange."

Steps:

1. Interview. Run references/interview.md. Ask the author to talk, not to type notes.

One take. No tidying.

1. Collect prior writing. Old posts, internal notes, coined definitions, lists they have

already published. These slot in verbatim and count fully as theirs. Link out to them.

1. Build the spine from the author's words, edited only by cutting and reordering. Never

paraphrase, never smooth conversational grammar, never fix a half-finished thought into a clean one. Rewording the author's content in your tokens destroys the whole value of having collected it.

1. Keep your own contribution a bounded, visible minority. Research, citations, definitions,

comparisons, data compression. Target 25% of total words or less, kept in delimited sections rather than sprinkled sentence by sentence, so a reader can see which part is which. Verify every fact and every URL.

1. Cut your own prose first. Length trades against authorship share. Every extra paragraph

you write dilutes the piece.

1. Apply the edit pass to your block only. The author's spine is not yours to improve.

If the author gives you less than roughly 300 words, ask one follow-up (a specific example usually pulls the most), then work with what you have and tell them plainly what the smaller share buys.

Zero author input. Offer the interview first, and say plainly what the piece loses without it. If the author declines, write the draft anyway and label it: this is a model draft in the author's register, not the author's writing, and the provenance note should say so. The thing this mode will not do is hand that draft over as though it were theirs. Refusing to write it at all is not the rule, and never was.

---

Mode: rewrite

1. Run Gate 0. If the draft is hollow, apply the failed-gate rule: report, offer the

interview, and edit anyway if that is what the author wants, labelled for what it is.

1. Calibrate the voice. If the user supplies a sample of their own writing, read it first

and extract sentence-length distribution, punctuation habits, paragraph shape, opinion density, recurring phrases, register, and the words they avoid. A sample outranks every default in this skill. If they say "stuff," do not promote it to "elements." If their sample uses em dashes at a steady rate, keep them at that rate.

1. Preserve every claim. You may cut dull passages, expand useful ones, merge or split

paragraphs, and restructure. You may not lose a fact or add one. A fact is something a reader could check. An assertion of significance with no evidence, an appeal to unnamed experts, a status-signalling list of publications, and a rejected option the piece never returns to are none of them facts, so the tells that say cut those are not asking you to drop information. When you are unsure which kind of sentence you have, keep it and flag it.

1. Run the edit pass below.
2. Run the self-check on your own output before returning it.

---

The edit pass

Ordered. Earlier items change what later items are looking at.

 1. Fix the lead. Delete the generic opening and start at the first sentence that carries
    information, then check that the sentence you landed on does the two jobs a first sentence
    has: make the reader want the second one, and signal what the piece is for. A fact, a
    number, a scene, or a claim will all do it. A definition of the topic will not.
 2. Replace claims of importance with the mechanism that earns them.
    "This underscores the importance of durable execution."
    → "When step 4 fails, the workflow retries step 4 alone and keeps what steps 1 to 3
       already produced."
    The mechanism has to come from the source. If the draft never says what durable execution
    does here, you cannot supply it: ask the author, or cut the sentence. Every "after" example
    in this skill assumes the facts were already on the page.
 3. Name the actor. An abstract noun may not perform a human act. Decisions do not emerge,
    cultures do not shift, data does not tell us. Someone decided, someone changed how they
    work, someone read the chart. If no one specific fits, use "you" and put the reader in
    the seat. The exception, and it is a real one: keep a passive when the actor is genuinely
    unknown or beside the point, and the object is the topic. Do not drive passives to zero.
 4. Climb the specificity ladder on every load-bearing claim. Rung 2 minimum, or a TK slot.
 5. Cut the superficial -ing tails: "highlighting the.

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [addyosmani](https://github.com/addyosmani)
- **Source:** [addyosmani/clarity](https://github.com/addyosmani/clarity)
- **License:** MIT
- **Homepage:** https://clarity.addy.ie

Install and usage instructions live in the source repository linked above.