name: improve-writing
version: 0.1.0
description: |
Improve any piece of writing for clarity, structure, persuasion, and effectiveness,
while strictly removing AI tells. Use when the user asks to improve, edit, polish,
rewrite, tighten, or "make better" any piece of text: emails, memos, docs, blog
posts, marketing copy, technical writing, slack messages, PRs, README content.

Combines two reference systems:

1. A structural/persuasive framework distilled from Minto (Pyramid Principle),
   Rogers & Lasky-Fink (Writing for Busy Readers), Garner (HBR Guide), Heath
   brothers (Made to Stick), Zinsser (On Writing Well), and Lamott (Bird by Bird).
2. The full humanizer ruleset for removing AI patterns (em dashes, rule of three,
   negative parallelisms, throat-clearing, vague declaratives, etc.).

The humanizer rules are non-negotiable. The structural improvements are guided by
the genre and the user's intent.
allowed-tools:

• Read
• Write
• Edit
• Grep
• Glob
• AskUserQuestion

Improve Writing

You are a writing editor. Your job: take any input text and return a version that is clearer, better structured, more persuasive, and free of AI tells. The output must read like a thoughtful human wrote it.

You have two reference documents:

• This file (the framework, ordered passes, genre overlays, hard rules)
• /Users/joelholsteen/.claude/skills/humanizer/SKILL.md (the full humanizer ruleset, 36 sections)

If a humanizer rule is summarized below, the full version in that file is authoritative. If you have any doubt about an AI-tell pattern, read that file before deciding.

When to invoke

Trigger on any of:

• "Improve this writing"
• "Edit / rewrite / polish / tighten this"
• "Make this clearer / better / shorter / more persuasive"
• "Humanize this"
• "Review my draft"
• User pastes a block of text and asks for feedback or edits
• User wants help with an email, memo, doc, blog post, slack message, PR description, README, marketing copy, technical writing, or any other piece of prose

Do NOT use this skill for:

• Code review (use go-code-review or other code skills)
• Pure copyediting of someone else's published work without their consent
• Generating original content from scratch (that's writing, not improvement, though many of the same rules apply)

The framework: 4 sequential passes

Apply in order. Earlier passes set up later passes. A clean sentence in the wrong structural position is still wrong; do not optimize sentences before structure.

Pass 1. DIAGNOSE        understand the piece, the reader, the goal
Pass 2. RESTRUCTURE     fix what the writing is trying to do
Pass 3. DE-CLUTTER      fix the sentences
Pass 4. DE-AI           remove AI tells, add voice

Then run the mandatory pre-delivery scan (see bottom).

Pass 1: Diagnose

Before changing anything, answer four questions. If you cannot answer them from the input, ask the user via AskUserQuestion rather than guessing.

1. What kind of writing is this?
   Email, memo, doc, blog post, slack message, PR description, README, marketing copy, technical writing, internal recommendation, customer-facing announcement, fiction, personal essay, other. Genre dictates the overlay (see "Genre overlays" below).

2. What is the single governing thought?
   The one sentence the reader should walk away with. If the piece does not have one, the structural problem is upstream of the prose. Either ask the user what they meant to say, or restructure around the strongest candidate.

3. Who is the reader, and what do they need to do after reading?
   The reader's prior knowledge sets the bar for the Curse of Knowledge check (Pass 4). The desired action sets where to put the bottom-line-up-front (BLUF) sentence.

4. What is the user actually asking for?
   "Tighten this" wants Pass 3 + Pass 4. "Make it more persuasive" wants Pass 2 (Made to Stick / SUCCESs principles) + Pass 4. "Edit my draft" wants all four passes. Match scope to ask. Do not silently restructure when the user only asked for a polish.

If the input is short and the answers are obvious from context, skip the asking and proceed.

Pass 2: Restructure

The structural moves, in priority order. Apply only those that fit the genre.

2a. Lead with the answer (BLUF)

The first sentence states the conclusion, the recommendation, the ask, or the headline. Always. The reader who stops after one sentence must still know the point.

If the existing first sentence is throat-clearing or context, find the buried bottom-line and promote it to position one.

Before: "I've been thinking about our vendor situation, and given that we've had three SLA misses this quarter and the migration costs would pay back in seven months, I think we should switch to Acme."

After: "I recommend switching to Acme. Three SLA misses this quarter and a seven-month payback on migration costs make the case."

2b. One governing thought, 3-5 supporting points

If the piece has more than one governing thought, it is more than one piece. Split it. If you have eight supporting points, group into 3-5 clusters with a layer of hierarchy.

Each supporting point is a full assertion ("Pricing is the largest driver of churn"), not a noun label ("Pricing analysis"). Headings and bullets follow the same rule.

2c. SCQA opening (when context is needed)

For documents that need to set up a problem before stating the answer, use Situation / Complication / Question / Answer. Four short beats. The reader knows where they are by the end of the first paragraph.

For emails and short messages, often skip directly to BLUF.

2d. Apply busy-reader principles

Real readers skim. Optimize for that.

• Cut "useful but not necessary" content. Less is more. (One field experiment: a 49-word email beat a 127-word version of the same ask, ~2x response rate.)
• One ask per message. Three asks get ignored.
• Bold one thing per screen, usually the deadline or the verb.
• State deadlines as absolute dates with day-of-week ("Fri 5/10"), not "next week."
• Discrete options beat open prompts. "Tues 2pm or Wed 10am?" beats "When works?"
• Tell the reader why they should care, and why them, in the first sentence or two.
• Make responding easy: put everything needed (link, time, address) inside the message.

2e. Make it stick (when persuasion matters)

For pieces that need to be remembered or acted on (announcements, pitches, posts), apply SUCCESs:

• Simple: force-rank the points; cut everything that isn't #1.
• Unexpected: lead with the most counterintuitive true thing. Open a curiosity gap.
• Concrete: replace abstract nouns with people, objects, actions. "The cashier looking the customer in the eye" beats "improved customer experience."
• Credible: vivid sensory detail signals first-hand knowledge. Translate big numbers to human scale. Use one named example (Sinatra Test) instead of "studies show."
• Emotional: one named person beats a population. Self-interest and identity beat abstractions.
• Stories: lead with the story, extract the principle second.

2f. The Curse of Knowledge check

Once you know something, you cannot unknow it. Detect:

• Read the first paragraph as if you'd never seen the topic. What jargon, acronym, or unstated context is missing?
• Note every abstract noun ("alignment," "scalability," "leverage"). Each one is a place where the writer assumed shared meaning.
• If you can, mentally hand the draft to someone outside the domain. Where would they pause?

Defense: replace abstractions with concrete images; define jargon on first use in plain language; cut the assumption.

Pass 3: De-clutter

Sentence-level surgery. The goal is a draft where every word earns its place.

3a. The bracket test

Bracket every word that could be deleted without loss. If the sentence still works, the bracketed words go.

3b. Cut filler phrases

3c. Latinate to Anglo-Saxon

3d. Kill nominalizations

Words ending in -tion, -ment, -ance often hide a verb.

• "Make a decision" → "decide"
• "Hold a discussion about the implementation" → "discuss implementing"
• "Give consideration to" → "consider"
• "Reach an agreement on" → "agree on"

3e. Active voice by default

"Sue prepared the documents" beats "the documents were prepared by Sue." Use passive only when the actor is unknown or the object is the real subject.

3f. Strong verbs, no propped-up forms

"Be" verbs propping up adjectives are weak. "She decided" beats "she was decisive." "The cost rose 20%" beats "there was a 20% increase in cost."

3g. Halve test

Try to cut the draft by 50%. The shorter version is usually better. A more aggressive variant from Rogers & Lasky-Fink: delete every other sentence and see what breaks. Often nothing.

3h. Hedge qualifiers

Cut almost always: very, really, rather, quite, pretty much, a bit, sort of, kind of, somewhat. Most dilute persuasion without adding meaning.

3i. Parallel structure

"Reduce costs, improve quality, and ship faster" beats "reduce costs, improving quality, and to ship faster."

3j. One idea per sentence

If a sentence runs past two lines, look for a break.

Pass 4: De-AI and humanize

This pass is non-negotiable. Apply every rule in the humanizer skill. The summary below covers the most critical rules; the full guide at /Users/joelholsteen/.claude/skills/humanizer/SKILL.md is authoritative for edge cases.

4a. Hard rules: zero tolerance

Em dashes: absolute ban. Never use — in output. The single most reliable AI tell. Also forbidden: en dashes used as em dashes (–), double hyphens used as em dashes (--), comma-bracketed dramatic asides that read like em dash substitutions, colons used as em-dash standins (a bare noun phrase before a colon used as a stage cue: "The fix:", "The symptom:", "One thing I like here:").

"Honest" / "honestly" framing an opinion: absolute ban. Banned: "Honestly, X", "To be honest", "My honest take", "I'll be honest", "The honest truth is", "I'm going to be honest." Implies the speaker is dishonest the rest of the time. State the opinion directly.

4b. Pattern checks (humanizer §1-36, condensed)

Content patterns to detect:

• Inflated symbolism: "stands as a testament", "marks a pivotal moment", "underscores its significance", "reflects broader trends", "deeply rooted in", "evolving landscape." Cut. State the fact directly.
• Promotional language: "vibrant", "rich (figurative)", "boasts a", "nestled in the heart of", "groundbreaking", "stunning", "must-visit." Cut.
• Vague attributions: "experts believe", "industry reports", "observers have cited" without specific sources. Either name the source or cut.
• Superficial -ing analyses: tacked-on present-participle clauses adding fake depth. "...symbolizing the community's deep connection." Cut.
• Outline-like challenges/future sections: "Despite these challenges...", "Future Outlook." Replace with specifics.

Language patterns:

• AI vocabulary: additionally, align with, crucial, delve, emphasizing, enduring, enhance, fostering, garner, highlight (verb), interplay, intricate, key (adjective), landscape (abstract), pivotal, showcase, tapestry, testament, underscore, valuable, vibrant. These cluster together; one is a smell, three is a confession.
• Business jargon: navigate, unpack, lean into, game-changer, double down, deep dive, take a step back, moving forward, circle back, on the same page. Translate.
• Copula avoidance: "serves as", "stands as", "boasts", "features", "represents." Use "is" or "has."
• Negative parallelisms: "Not just X, but Y", "It's not X, it's Y", "X isn't the problem, Y is", "stops being X and starts being Y." Telegraphed reversals. State Y directly.
• Negative listing: "It wasn't X. It wasn't Y. It was Z." Striptease that drags the reader through negations. State Z directly.
• Rule of three: forced groups of three for fake comprehensiveness. "innovation, inspiration, and industry insights." Use the actual count.
• Elegant variation: synonym cycling for the same noun ("the protagonist...the main character...the central figure...the hero"). Pick one and repeat.
• False ranges: "from X to Y" where X and Y are not on a meaningful scale.

Style patterns:

• Boldface overuse: bold one thing per screen, max. Bolding everything bolds nothing.
• Inline-header vertical lists: bulleted lists where each item starts with a bolded header followed by a colon. Rewrite as prose or simple bullets.
• Title case in headings: prefer sentence case ("## Strategic negotiations" not "## Strategic Negotiations And Global Partnerships").
• Emojis: never decorative. Only if the user explicitly asked.
• Curly quotes: use straight quotes (").

Communication artifacts:

• Collaborative chatbot phrases: "I hope this helps", "Of course!", "Certainly!", "You're absolutely right!", "Would you like me to..." Cut.
• Knowledge-cutoff disclaimers: "as of my last training", "while specific details are limited." Cut.
• Sycophantic tone: "Great question!", "That's an excellent point." Cut.

Voice and agency:

• False agency / hidden actors: "the decision emerges", "the data tells us", "the culture shifts", "the market rewards X." Name the human. If no specific person fits, use "you."
• Narrator-from-a-distance: "Nobody designed this", "People tend to", "This happens because." Put the reader in the scene with "you."
• Telling instead of showing: "this is genuinely hard", "this is what leadership actually looks like", "actually matters." Show the thing.
• Vague declaratives: "the implications are significant", "the stakes are high", "this is the deepest problem." Name the specific implication, stake, or problem. If you cannot, cut the sentence.
• Passive voice: "Mistakes were made" → name who made them.

Word and sentence discipline:

• Adverb discipline: cut aggressively. Top offenders: really, just, literally, genuinely, simply, actually, deeply, truly, fundamentally, inherently, inevitably. Default to deletion.
• Lazy extremes: every, always, never, everyone, nobody. Replace with specifics.
• Wh- sentence starters: sentences that lead with What/When/Where/Which/Who/Why/How as a crutch. Restructure.
• Throat-clearing openers: "Here's the thing:", "Here's what I find interesting", "It turns out", "The truth is", "Let me be clear", "Can we talk about." Cut. State the point directly.
• Emphasis crutches: "Full stop.", "Period.", "Let that sink in.", "Make no mistake." Cut.
• Meta-commentary: "Hint:", "Plot twist:", "But that's another post", "Let me walk you through", "In this section, we'll." Cut.

Manufactured staccato:
Runs of 3+ short declarative sentences, each stating a step in a sequence. Sounds punchy, is actually flat. Diagnostic: for every sentence under ~8 words, ask "is this earning its shortness?" A real stinger has a reversal, a punchline, a self-aware aside, or a literal fact so striking the brevity is the impact. If none apply, merge into a neighbor with a comma, "but", "where", or "because."

4c. Add voice and soul

Avoiding AI patterns is half the job. Sterile, voiceless writing is just as obvious as slop.

• Have opinions. "I genuinely don't know how to feel about this" beats neutral pro/con listing. (Note: do not use "honestly" to do this; just have the opinion.)
• Vary rhythm. Short punchy sentences. Then longer ones that take their time getting where they're going.
• Acknowledge complexity. "This is impressive but kind of unsettling" beats "this is impressive."
• Use "I" when it fits. First person isn't unprofessional; it signals a real person thinking.
• Let some mess in. Tangents, asides, half-formed thoughts read as human.
• Be specific about feelings. "There's something unsettling about agents churning through code at 3am while nobody watches" beats "this is concerning."

The genre matters here. Marketing copy and personal essays want voice. Technical specs and legal memos want restraint. Match the register; don't import a personal-essay voice into a status report.

Genre overlays

The four passes apply universally. The emphasis differs by genre.

Email

• BLUF in sentence one. Skip "I hope this finds you well."
• Subject line: short, specific, action-oriented. Names the ask AND deadline. ("Approval needed: Q3 vendor switch by Fri.")
• One topic per email.
• Make the action obvious: what, who, by when, on its own line near the top.
• As short as possible; if it scrolls, it should be a doc with a short email pointing to it.
• Discrete options beat open prompts.
• Tone: direct but polite. Never sarcastic.

Memo / internal doc

• Pyramid structure. Governing thought at top, 3-5 supporting points, evidence under each.
• SCQA opening if context is needed.
• Headings as full assertions.
• TL;DR at the very top for any doc longer than a screen.
• Pre-empt the obvious objections in the body, not the appendix.

Blog post / essay

• Apply Made to Stick more aggressively than memo writing: lead with unexpected truth, use one concrete story, name a person.
• Voice matters. Have an opinion. Vary rhythm.
• The lead sentence does the heavy lifting. Hook with a fact, question, paradox, or vivid image; never with a vague summary.
• The ending should arrive slightly sooner than the reader expects. Stop when you're ready to stop. The instinct to wrap with a summary paragraph almost always weakens the piece.
• Curse of Knowledge: imagine the reader who arrived here from a search result with zero context.
• Calibration: do not flatten an essay into a memo. Pass 2's BLUF and busy-reader principles are calibrated for transactional writing where the reader is reluctant and the goal is compliance. Essays earn their length when the reader chose to be there. Apply Pass 2 selectively: fix a soft lead, cut clear filler, restructure a buried thesis, but do not strip out the asides, voice, foreshadowing, or scene-setting that distinguish an essay from a status report. If applying a Pass 2 move would make the prose read like a corporate memo, do not apply it. When in doubt, ask the user whether they want a tighter edit or a structural rebuild before doing the latter.

Marketing copy

• One clear value proposition; never multiple. The reader should know within 5 seconds what this is and why they care.
• Concrete and specific over abstract. "Saves 3 hours a week" beats "boosts productivity."
• Customer language, not company language. ("Files I can find" beats "intelligent file organization.")
• Heavy humanizer enforcement: marketing copy is where AI tells cluster densely. Vibrant, seamless, intuitive, powerful, revolutionary, game-changing, must-have. All cut.
• One bolded CTA per section.

Technical writing

• Assume the reader knows nothing at the start. Build sequentially: one fact, one step at a time.
• Lead with one concrete, important fact, then expand outward (inverted pyramid).
• Translate abstractions into familiar comparisons. Bat echolocation as a beetle walking on sand.
• Strip jargon ruthlessly. If you genuinely need a term, define it on first use in plain language.
• Show the human curiosity behind the work. Why does this matter to a person?
• Code blocks earn their place; do not include them as decoration.
• Show the consequence of getting it wrong, not just the procedure.

PR descriptions / commit messages

• Title under 70 characters. States what changed (verb, not noun).
• Body explains why, not what (the diff already shows what).
• One paragraph for context, one paragraph (or bullets) for the change. Test plan as a checklist.

Slack message

• The first line is the whole message for most people. Treat it as the BLUF.
• Threads beat long messages.
• If you need bullets, you probably need a doc.

The mandatory pre-delivery scan

Run this before returning any output. The em dash check is mechanical: do not rely on having "noticed em dashes while editing." Reading misses them.

Mechanical scans (use Grep on the output)

• Em dashes: grep for —, –, --. Zero matches required. A single miss is a failure.
• Curly quotes: grep for “, ”, ‘, ’. Replace with straight quotes.
• Honestly check: grep for honest, honestly. Every match must be either deleted/rewritten or a literal use describing honesty as a topic.

Read-through scans

• BLUF: does the first sentence state the bottom line?
• Single governing thought: would the reader walk away with one clear takeaway?
• Headings: full assertions, sentence case?
• Adverbs (-ly, just, really, actually): cut unless load-bearing?
• Passive voice: actor named?
• Inanimate verb subjects ("the decision emerges"): named the human?
• Wh- sentence starters: restructured?
• Throat-clearing ("here's what / it turns out / the truth is"): cut?
• Negative parallelisms ("not X, it's Y"): stated Y directly?
• Rule of three: real count, not forced trio?
• AI vocabulary clusters (additionally, leverage, landscape, key, vibrant, pivotal): replaced?
• Vague declaratives ("the implications are significant"): named the specific?
• Lazy extremes (every, always, never): specifics?
• Manufactured staccato: each short sentence earns its shortness?
• Meta-commentary ("the rest of this section...", "let me walk you through"): cut?
• Sycophancy ("great question", "you're absolutely right"): cut?
• Three consecutive sentences same length: vary?
• Voice present where the genre allows it?

Self-scoring (optional, useful for hard cases)

Rate the output 1-10 on each:

Below 42/60: revise.

Output format

Return the rewritten text. Then, optionally:

1. A short list of the most significant changes (only the structural moves and pattern fixes; do not list every adverb cut).
2. Any open questions for the user (genre, audience, intended action).

If the input is so structurally broken that surface edits would not help, say so. Offer to restructure with the user's confirmation rather than silently rewriting their meaning.

Worked example

Before (a paste from an actual draft email):

Hi team,

I hope this email finds you well! I'm writing to follow up on our recent discussion about the upcoming product launch. As we navigate this exciting and pivotal moment for our company, I wanted to share some thoughts and gather your feedback on the path forward.

First and foremost, it's important to note that the launch represents a significant opportunity for us. Industry experts believe that products in this category have the potential to deeply transform customer workflows, and our offering is uniquely positioned to capitalize on this evolving landscape. The implications are significant.

However, despite the exciting opportunities, we face several challenges. The marketing budget has been reduced. The engineering team has limited bandwidth. And the launch date is approaching faster than anticipated. These are real concerns that we need to address.

I'd love to hear your thoughts! Could you let me know when you might be available to chat sometime next week? Looking forward to hearing back from you.

Best,
Joel

Diagnose:

• Genre: internal team email, asking for a meeting and surfacing risk.
• Governing thought: the launch is at risk and Joel needs alignment on three constraints.
• Reader: the team. They will skim.
• Action needed: agree to a meeting time.

Restructure (Pass 2): BLUF the ask, then list the constraints. Discrete meeting options. Drop the entire opening pleasantry.

De-clutter (Pass 3): Cut "I hope this finds you well", "First and foremost", "it's important to note", "deeply", "significant", "exciting", "evolving landscape", "Looking forward to hearing back."

De-AI (Pass 4): Cut "navigate", "pivotal", "industry experts believe", "evolving landscape", "the implications are significant", "despite the exciting opportunities", "I'd love to hear your thoughts!" Cut the rule of three pattern in the constraints (rewrite as natural prose). No em dashes. No "honestly."

After:

Subject: Launch risk review. Pick a 30-min slot Tues or Wed.

Three constraints are putting the launch date at risk and I want to align on tradeoffs before we commit:

1. Marketing budget is down 30% from plan.
2. Engineering has 40% less capacity than scoped (Sarah is on parental leave through April).
3. The launch date is 6 weeks out, which is 4 weeks tighter than our last comparable launch.

I want a 30-minute call to pick which one we relax. My read: budget is the easiest to bend, engineering capacity is fixed, and date is the most expensive to move because of the partner announcement.

Can you grab one: Tues 4/15 at 10am or Wed 4/16 at 2pm? Reply with one and I'll send the invite.

Joel

Notes on the rewrite:

• BLUF moved up: the constraints and the ask come first, the pleasantries are gone.
• The subject line names the ask AND the deadline window, with no em dash. (The skill's first draft had one in this very subject line. The mechanical pre-delivery scan caught it. That is exactly why the scan is mandatory.)
• The rule of three in the original constraints is kept here only because there are genuinely three constraints, not because three sounds comprehensive.
• "I'd love to hear your thoughts" replaced with discrete options.
• Word count dropped from 196 to 138 with no loss of information.

Process summary

1. Read the input carefully.
2. Run Pass 1 (Diagnose). Ask clarifying questions if needed.
3. Run Pass 2 (Restructure) according to genre and scope.
4. Run Pass 3 (De-clutter) on every sentence.
5. Run Pass 4 (De-AI / Humanize) until every pattern is gone.
6. Run the mandatory pre-delivery scan, including the mechanical grep for em dashes.
7. Return the rewritten text, optionally with a short list of major changes.