writing-review
Skill0 starsChanged 2 months agoMITView on GitHub
Use before sending prose that has to persuade, explain, or be acted on — a report, proposal, email, summary, design doc, or manuscript section. Checks whether the argument holds and whether the sentences carry it: an unstated point, sections in an order nobody can follow, generalizations with no evidence under them, abstraction where a concrete noun belongs, and clutter that survived the first draft. Triggered by: finishing a draft, "does this read well", "can you review this writing", sending something to a reader who can stop reading.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- gwpicard/ai-loop-kittheir own version, first seen Nov 1, 2026
- slogsdon/skills-writingtheir own version, first seen Oct 19, 2026
- ragnos-labs/skill-indextheir own version, first seen Aug 23, 2026
- markrstevenson/skillstheir own version, first seen Aug 10, 2026
- darrenCWJ/agent-skills-scaffoldtheir own version, first seen Aug 9, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- gwpicard/ai-loop-kit★ 1same name
- darrenCWJ/agent-skills-scaffold★ 0same name
- markrstevenson/skills★ 0same name
- ragnos-labs/skill-index★ 0same name
- slogsdon/skills-writing★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository2 other files it gives its agents.
- check-claimsSkill
- occams-razorSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 7 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
The argument can fail: No point, or a point nobody can find.
- Distinctive: line 46
Test: read only the headings and first sentences.
- Distinctive: line 66
Every generalization carries its evidence, and the evidence is *interpreted* — quotations and figures do not explain themselves.
- Distinctive: line 85
Short sentences: Use periods freely. A long sentence is usually two.
- Distinctive: line 100
Test: read it aloud. The sentences you stumble over are the ones to rewrite — not because reading aloud is a rule, but because stumbling …
- Distinctive: line 108
Write as you would explain it to a competent colleague.
- Distinctive: line 164
Purpose: If the point is unclear, nothing below matters.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing Review
Core Principle
Two things can be wrong with a piece of writing, and they fail independently.
The argument can fail. No point, or a point nobody can find. Sections in an order that hides the logic. Assertions with nothing under them.
The sentences can fail. Abstraction where a concrete noun belongs. Twelve words doing four words' work. A voice nobody would use out loud.
A draft can be immaculate at sentence level and say nothing. It can have a real argument buried in prose no one will finish. Check both, separately, in that order — fixing sentences in a section you are about to cut is wasted work.
Level 1 — The Argument
Purpose
"A thesis and direction are clear. The writing is addressed to a well-defined audience."
One point, not three. Name it in a single sentence. If you cannot, the draft is still thinking rather than telling.
Then name the reader. Not "people" — the actual person who will act on this, and what they already know. Purpose without an audience produces writing that is technically correct and lands nowhere.
Test: what is the one sentence a reader should be able to repeat afterwards? Is it in the document, or only in your head?
Organization
"Ideas and support are developed one at a time systematically and logically."
One idea at a time, in an order the reader can predict. Ascending, descending, chronological, or parallel — any of those work; no discernible pattern does not.
Test: read only the headings and first sentences. Does the argument still follow? If the order could be shuffled without loss, there was no order.
Coherence
"Conceptual links are provided between individual elements."
The joins between ideas, stated rather than implied. Key terms repeated instead of elegantly varied — a reader tracking an argument needs the same word for the same thing. Summary where a section turns.
Test: at each section break, can the reader say why this follows that? If the link lives only in your head, the document has a gap the reader will fall into.
Not this: connective words sprinkled as decoration. "Furthermore" between two unrelated points is a lie about a relationship.
Support
"All generalizations and conclusions are justified by logically presented evidence."
Every generalization carries its evidence, and the evidence is interpreted — quotations and figures do not explain themselves. A number dropped into a paragraph without a sentence saying what it means is decoration.
Test: underline every claim. For each, point at the thing that justifies it. Unjustified claims either get evidence or get softened to the honest version.
Level 2 — The Sentences
Clarity
"Diction and syntax are precise; the writer has considered the reader's understanding."
- Concrete over abstract. Name the thing. Concept nouns hide who did what — replace them with people and verbs.
- Active over passive. "The committee rejected it" beats "it was rejected." Passive voice hides the actor, which is sometimes the point and usually a bug.
- Short sentences. Use periods freely. A long sentence is usually two.
- Subject-verb-object. Deviate deliberately, not by accident.
Clutter
"Vigorous writing is concise." — Strunk, via Zinsser
Most first drafts are a third too long. Cut:
| Cut | Why |
| Qualifiers — rather, quite, sort of, a bit | They weaken the sentence and buy nothing |
| Adverbs propping up weak verbs | Find the verb that does not need help |
| Decorative adjectives | Keep the ones carrying information |
| Phrases that restate the previous sentence | The reader got it |
Test: read it aloud. The sentences you stumble over are the ones to rewrite — not because reading aloud is a rule, but because stumbling locates the problem faster than staring does.
Voice
"Never say anything in writing that you wouldn't say in conversation." — Zinsser
Write as you would explain it to a competent colleague. Jargon and clichés are both substitutes for having decided what you mean.
This does not license sloppiness. It rules out the register people adopt when they are performing authority rather than exercising it.
Paragraphs, Lead, Ending
- Paragraphs short enough to look inviting. Each one advances the argument.
- The lead earns the second sentence. Not throat-clearing, not a summary of what you are about to say.
- The ending stops. It does not recap what the reader just read. The best endings surprise slightly and feel inevitable anyway.
Insight
"The writer has found creative ways to integrate, synthesize, and interpret challenging ideas."
The one principle that cannot be reduced to a checklist. Synthesis — the sources combined into something none of them said — is what separates a competent draft from one worth reading.
Test: does the document contain a sentence that is yours? If every claim could be traced to a source and nothing connects them, it is a literature review wearing an argument's clothes.
What This Does Not Do
Two adjacent checks, deliberately kept separate:
| Question | Skill |
| Does every element earn its place? | occams-razor |
| Is any of this false? | check-claims |
The overlaps are real and the boundaries matter:
- Clutter vs the razor. This skill cuts words that do not earn their place. The razor cuts sections, comparisons and components that do not. Different altitude, same instinct.
- Support vs check-claims. Support asks whether a claim has evidence under
it.
check-claimsasks whether that evidence is true. Well-supported and wrong is a real state.
Running all three on one document is reasonable. Folding them into one skill is not — it would be one check answering three questions.
Order
- Purpose. If the point is unclear, nothing below matters.
- Organization and Support. Structural fixes move whole paragraphs.
- Sentences. Last, because you are polishing text that will survive.
Polishing before the argument settles is the most common way to waste an afternoon on a draft you then restructure.
Self-Check
| Finding | Status |
| The one-sentence point is in the document | Purpose holds |
| Headings alone carry the argument | Organization holds |
| Every claim has evidence you can point at | Support holds |
| Nothing survives being read aloud unchanged | Rewrite those sentences |
| Nothing in it is yours | Stop. This is assembled, not written. |
Sources
- "The Six Principles of Good Writing," Campus Writing Program — purpose, organization, coherence, support, clarity, insight. https://stvincent.libguides.com/english/el205/6principles
- Jeff Zych, "Writing" — purposeful, clear, genuine, and the mechanics, drawing on William Zinsser's On Writing Well. https://jlzych.com/writing/
The first is a rubric for argument; the second is a craft doctrine for holding a reader. They agree on purpose and clarity, which is why those two carry the most weight here.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

