agentleFS
rogertinchrogertinch/claude-skills/writing-well/SKILL.md

writing-well

Skill2 starsChanged 6 months agoMITView on GitHub

Use when the user wants to edit, revise, tighten, or draft nonfiction prose — essays, articles, blog posts, memos, op-eds, film or book reviews, memoir chapters, or any piece of writing meant for a real reader. Applies craft principles from On Writing Well: cut clutter, strengthen verbs, fix weak leads and soft endings, unify voice and tense. Skip for: fiction, poetry, marketing or SEO copy, UI text, code or commit messages, grammar questions, or removing AI writing patterns (em-dashes, "delve," etc.).

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. ferminrp/agent-skills★ 39same name
    2. spalladino/claude-skills★ 1same 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 repository3 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 11 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    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:

    If the user asks for one of the above, say so and either defer or offer the closest Zinsser-adjacent angle (e.g., "I can't apply Zinsser to …

    line 20
  2. Distinctive:

    When in doubt, ask once: "Do you want me to revise this draft, or draft something new from a brief?"

    line 29
  3. Distinctive:

    Read the piece twice before you touch it.

    line 33
  4. Distinctive:

    Before you fix sentences, check the larger frame.

    line 39
  5. Distinctive:

    After all the cuts, the prose should still sound like a person.

    line 105
  6. Distinctive:

    Before you write a word, force the writer through Zinsser's pre-writing decisions.

    line 111
  7. Distinctive:

    What one point: do you want the reader to leave with?

    line 113
  8. Distinctive:

    If the user resists pre-writing decisions ("just draft it"), do a fast first pass, then in your notes flag the unities you guessed at so …

    line 122
  9. Distinctive:

    Keep the notes short — 5–10 bullets at most.

    line 147
  10. Distinctive:

    When drafting from a brief, lead with the draft, then list the pre-writing decisions you made so the user can redirect any that were wrong.

    line 149
  11. Distinctive:

    When you're stuck on a sentence or a piece feels off, these are the questions Zinsser actually asks.

    line 153

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “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 Well — Zinsser's Nonfiction Craft

You're applying William Zinsser's method from On Writing Well (the classic guide to writing nonfiction). The job is craft, not opinion: every decision in this skill traces back to a specific principle Zinsser repeated across the book.

When this skill fits — and when it doesn't

Use it for: essays, articles, blog posts, criticism, memoir, business writing, science/tech explainers for general readers, op-eds, longform reporting, personal essays. Anything where a real human reader will judge the prose on its own.

Don't use it for:

  • Fiction, poetry, lyrics, screenwriting. Zinsser explicitly excludes these; his rules can actively hurt creative writing that depends on rhythm, voice play, or invented language.
  • Removing AI-isms (em-dash overuse, rule-of-three, "it's not X, it's Y," "delve," "elevate"). That's a pattern-detection job — defer to a humanizer/stop-slop pass. Zinsser's lens is craft, not provenance.
  • Marketing copy, SEO, UI text, push notifications, CTAs. Short commercial copy follows different rules (keyword density, scannability, conversion). Applying Zinsser here can flatten copy that needs to sell.
  • Code, code comments, commit messages, technical reference docs. These are reference material, not prose for readers.

If the user asks for one of the above, say so and either defer or offer the closest Zinsser-adjacent angle (e.g., "I can't apply Zinsser to UI text, but I can tighten the verbs in your product description if that's useful").

The two flows

Detect which one the user wants from the request itself:

  • Paste of existing prose → revise. They want you to apply Zinsser to text they already have.
  • Brief or description ("help me write…") → draft. They want a new piece. Walk through pre-writing decisions first, then draft.

When in doubt, ask once: "Do you want me to revise this draft, or draft something new from a brief?"

Flow A: Revise existing prose

Read the piece twice before you touch it. First pass: what is the writer trying to say? Second pass: what's getting in the way?

Then revise against this checklist, in roughly this order. Don't apply every rule mechanically — Zinsser's whole point is that the writer has a personality and a purpose, and your job is to clear away what's burying them, not to flatten them into a house style.

1. Unity (Zinsser ch. 8) — does the piece know what it is?

Before you fix sentences, check the larger frame. Inconsistencies here make sentence-level work pointless.

  • One point. A successful piece "leaves the reader with one provocative thought." Not two, not five. If the draft is trying to say multiple things, name them and ask the user which is the real piece. Don't silently pick one.
  • Unity of pronoun. First, second, or third person — and stay there.
  • Unity of tense. Pick one and stay; switch only deliberately, with a mood-changer word to signal it.
  • Unity of mood. Casual or formal or ironic — not three of them in one piece. Travel-brochure prose mixed with personal narrative is Zinsser's classic example of the failure.

2. The lead (ch. 9) — does the first sentence earn the second?

The first sentence has one job: make the reader want to read the second. Then the second has to earn the third. If the draft opens with throat-clearing — context, definitions, "In today's world…" — cut to the first sentence that actually does work.

Stock leads to kill on sight:

  • "When some future archaeologist…"
  • "If a visitor from Mars…"
  • "One day not long ago, [Name] was [doing thing] when…"
  • "What do [Person A], [Person B], and [Person C] have in common?"
  • Definition leads: "Webster's defines X as…"
  • "In today's fast-paced world…"

Replace with: a concrete fact, a paradox, a specific image, a quoted line, a question that nudges curiosity.

3. Clutter (ch. 3) — the bracket pass

Zinsser's classroom method: put brackets around every word doing no useful work. Then ask, "Do I need this at all?" Usually you don't. Most first drafts cut by 50% without losing information.

Targets:

  • Long Latinate words where a short Anglo-Saxon one will do: assistance → help, numerous → many, facilitate → ease, individual → person, remainder → rest, initial → first, implement → do, sufficient → enough, attempt → try, referred to as → called, currently → now, at the present time → now, prior to → before, in order to → to.
  • Inflated phrases: due to the fact that → because, with the possible exception of → except, until such time as → until, for the purpose of → for, in the event that → if.
  • Euphemism and corporate fog: experiencing pain → hurting, involuntary methodologies → layoffs, negative cash-flow position → broke.
  • Throat-clearing clusters: I might add, it should be pointed out, it is interesting to note, the fact of the matter is, in a very real sense. If you might add, add it. If it's interesting, make it interesting.
  • Redundant prepositions glued onto verbs: head up, free up, face up to, order up, meet up with, start up.

4. Verbs (ch. 10) — active and precise

  • Active over passive. "Joe saw him," not "He was seen by Joe." Passive sentences leak energy. The exception is when the doer is genuinely unknown or unimportant.
  • Precise over generic. "He resigned" or "He was fired" — not "He stepped down." "She walked" is fine; "She trudged" or "She strode" tells the reader something.
  • Verbs of motion and image carry their meaning: glitter, dazzle, twirl, beguile, scatter, swagger, poke, pamper, vex. Reach for these before reaching for adjectives.

5. Adverbs and adjectives — most are redundant

  • Adverb glued to verb whose meaning it duplicates: blared loudly, clenched tightly, grinned widely, smiled happily. Cut the adverb. The verb already says it.
  • Adjective stating known fact: tall skyscraper, lacy spiderweb, yellow daffodil. Cut. Keep adjectives that add new information (garish daffodil, red dirt).
  • "Decidedly," "arguably," "virtually," "essentially," "basically" — hedge words masquerading as precision. Almost always cut.

6. Little qualifiers — kill the hedges

A bit, a little, sort of, kind of, rather, quite, very, too, pretty, in a sense. "Don't say you weren't too happy because the hotel was pretty expensive. Say you weren't happy because the hotel was expensive." Every qualifier whittles the reader's trust. Be confused. Be tired. Be annoyed. Be bold.

7. Concept nouns and creeping nounism — put people back in

Sentences without people performing actions go dead. Watch for:

  • Reaction, response, hostility, cynicism, situation used as the subject with a weak "is/was" verb.
  • Noun chains: communication facilitation skills development intervention.

Rewrite so a person does a thing with a verb: "Most people just laugh."

8. Sentence transitions — does B follow from A?

Read paragraphs aloud. After each sentence, ask: does the next sentence land where the reader expects? If not, either rewrite the next sentence or insert a mood-changer at its start: but, yet, however, instead, still, therefore, meanwhile, today, later. Put them at the front of the sentence — "however" in the middle hangs like a wet dishrag.

9. The ending — stop when you're ready to stop

If the draft ends with "In sum, it can be noted that…" or "What insights, then, have we been able to glean…" — cut everything from there to the end. The piece probably already ended a paragraph earlier. Find the sentence that has finality (often a quotation, a vivid detail, or a callback to the opening) and end there.

10. Voice — does it sound like the writer?

After all the cuts, the prose should still sound like a person. If it sounds like anyone could have written it, you cut too much. Check for:

  • Breeziness ("yours truly," "bummed me out," "guy") — cheap chumminess. Cut.
  • Stiltedness (no contractions, "indeed," "moreover," third-person reportorial throughout) — let the writer breathe. Use "I'll" instead of "I will" where it fits.

Flow B: Draft from a brief

Before you write a word, force the writer through Zinsser's pre-writing decisions. Ask explicitly (you can compress this into one message, but don't skip it):

  1. What one point do you want the reader to leave with? Not two, not five — one.
  2. In what capacity are you addressing the reader? (Reporter? Participant? Provider of information? Critic?)
  3. What pronoun and tense?
  4. What attitude? (Involved, detached, ironic, amused, judgmental, earnest.)
  5. How small can you make this? Tolstoy didn't write a book about war and peace — he wrote about specific people in a specific war. Zinsser's rule: "think small." Pick one corner of the subject.
  6. Who are you writing for? Zinsser's answer is always: yourself, first. Write what you'd want to read. The audience of one is enough.

Then draft. Apply every rule in Flow A as you go. Open with a lead that earns the next sentence. End when you're done.

If the user resists pre-writing decisions ("just draft it"), do a fast first pass, then in your notes flag the unities you guessed at so they can correct course.

Output format

When revising:

**Revised draft**

[Clean revised prose, ready to use.]

**Cuts made (and why)**

- "due to the fact that" → "because" (clutter / inflated phrase)
- "was seen by the crowd" → "the crowd saw" (passive → active)
- Killed last paragraph beginning "In conclusion…" (summary ending; piece already landed)
- Cut "rather" 4×, "very" 2×, "in a sense" 1× (little qualifiers)
- Reordered paragraph 3 so the specific image comes first (lead earns the next sentence)

**Open questions for you**

- Is this for a general audience or specialists? I assumed general — pulled out two jargon terms.
- The piece argues both X and Y; I leaned into X as the single point. If Y is the real point, the lead needs to change.

Keep the notes short — 5–10 bullets at most. The reader cares about the prose; the notes are there so they can push back on your judgment, not so you can justify yourself.

When drafting from a brief, lead with the draft, then list the pre-writing decisions you made so the user can redirect any that were wrong.

A few of Zinsser's questions, ready to ask out loud

When you're stuck on a sentence or a piece feels off, these are the questions Zinsser actually asks. They work as your own diagnostic:

  • "What am I trying to say?"
  • "Have I said it?"
  • "Is it clear to someone encountering the subject for the first time?"
  • "Does this word do useful work?"
  • "Do I need this at all?"
  • "What does the reader want to know next?"
  • "What single point do I want to leave in the reader's mind?"

Why this matters

Zinsser's whole argument is that nonfiction is a craft with tools, and the tools are well-understood: clear thinking, short words, active verbs, unity, and ruthless rewriting. "If you find that writing is hard, it's because it is hard." Your job is to do the hard part the user shouldn't have to: bracket the clutter, name the rule that was broken, hand back prose that sounds more like the writer than the first draft did.

The reader has a 30-second attention span and a hundred other things to do. Earn every sentence.

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.