agentleFS
michaelwjohnsonmichaelwjohnson/claude-skills/skills/writing-review/SKILL.md

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

  • Other versions5 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 5

    1. gwpicard/ai-loop-kit★ 1same name
    2. darrenCWJ/agent-skills-scaffold★ 0same name
    3. markrstevenson/skills★ 0same name
    4. ragnos-labs/skill-index★ 0same name
    5. 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.

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
  1. Distinctive:

    The argument can fail: No point, or a point nobody can find.

    line 12
  2. Distinctive:

    Test: read only the headings and first sentences.

    line 46
  3. Distinctive:

    Every generalization carries its evidence, and the evidence is *interpreted* — quotations and figures do not explain themselves.

    line 66
  4. Distinctive:

    Short sentences: Use periods freely. A long sentence is usually two.

    line 85
  5. Distinctive:

    Test: read it aloud. The sentences you stumble over are the ones to rewrite — not because reading aloud is a rule, but because stumbling …

    line 100
  6. Distinctive:

    Write as you would explain it to a competent colleague.

    line 108
  7. Distinctive:

    Purpose: If the point is unclear, nothing below matters.

    line 164

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

CutWhy
Qualifiers — rather, quite, sort of, a bitThey weaken the sentence and buy nothing
Adverbs propping up weak verbsFind the verb that does not need help
Decorative adjectivesKeep the ones carrying information
Phrases that restate the previous sentenceThe 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:

QuestionSkill
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-claims asks 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

  1. Purpose. If the point is unclear, nothing below matters.
  2. Organization and Support. Structural fixes move whole paragraphs.
  3. 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

FindingStatus
The one-sentence point is in the documentPurpose holds
Headings alone carry the argumentOrganization holds
Every claim has evidence you can point atSupport holds
Nothing survives being read aloud unchangedRewrite those sentences
Nothing in it is yoursStop. This is assembled, not written.

Sources

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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.