Community寫作與編輯github.com

clear-writing

Write, edit, tighten or review any work text in a plain, direct style with RTSL house rules built in: emails, Slack, slides, reports, proposals, specs, Jira tickets and product copy.

clear-writing 是什麼?

clear-writing is a Claude Code agent skill that write, edit, tighten or review any work text in a plain, direct style with RTSL house rules built in: emails, Slack, slides, reports, proposals, specs, Jira tickets and product copy.

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tonyjoyk/AI_skills/tree/HEAD/skills/clear-writing

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Clear writing

1. The main rule

  • Write so the reader gets the point on the first read.
  • Use the fewest words that keep the full meaning.
  • Don't blab. Every sentence must help the reader understand, decide or act. If it doesn't, cut it.
  • The rules are the same for every format. Only the shape changes (section 9).

2. Before you write

  • Know the reader: partner, donor, engineer, health worker or teammate.
  • Know what they should do or know after reading. That is the first sentence.
  • Know the format: email, slide, report, spec, ticket or message.
  • For RTSL content, pick the tier:
    • Tier 1, public: plain words, no acronyms ("heart health," "salt").
    • Tier 2, partners and ministries: plain and professional. Known terms are fine (CVH, 7-1-7).
    • Tier 3, scientific: technical terms allowed.
  • If a key fact or the purpose is missing, ask one focused question. Otherwise, write.

3. Sentences

  • Aim for about 15 words on average, mostly 10 to 20. Vary the length so it doesn't sound choppy.
  • One idea per sentence. Split a sentence that carries two.
  • Use active voice. Name who does what.
  • Contractions are fine. Fragments only on slides.
  • Use standard punctuation.
  • Never use em dashes. Use a period, comma, colon or parentheses.
  • No Oxford comma ("apples, oranges and grapes").
  • Connect ideas with simple words: but, so, and, because, then. Don't force transitions.

4. Words

  • Use everyday words. Pick the common word over the complex one.
  • Avoid words of 4+ syllables when a shorter word works. Domain terms are fine when they're the right word (hypertension, medication).
  • Aim for an 8th grade reading level. It's a target, not a hard limit.
  • Use technical terms only when the reader needs them. Define them in plain words on first use.
  • Use the same term for the same thing all the way through.
  • Prefer verbs to abstract nouns: "decide," not "make a decision."
  • Skip idioms and metaphors. Many readers read English as a second language.
  • Replace an unclear "this," "that" or "it" with the noun.

Never use: indeed, furthermore, thus, moreover, notwithstanding, ostensibly, consequently, specifically, notably, alternatively.

Avoid by default: delve, digital age, cutting-edge, leverage, proactive, pivotal, seamless, fast-paced, game-changer, quest, realm, landscape, evolve, resilient, thrill, unravel, embark, world, unlock, drive impact, empower, harness, robust, synergy, ensure, commendable, incredible, very, key, the fact that. Use one only when it's truly the clearest word. Names are fine (World Health Organization).

Plain swaps: use (utilize, leverage), help (facilitate), to (in order to), before (prior to), after (subsequently), more (additional), start (commence), find out (ascertain), improve (optimize), about (approximately, around), some or the real number (a number of).

Word pairs:

  • "Because" for cause, not "since" or "as."
  • "Although" for caveats. "While" only for time.
  • "Nearly" for numbers. "Almost" for ideas.
  • "More than" for numbers. "Over" for place.
  • "Such as" for examples. "Like" for comparisons.
  • "Fewer" for things you can count. "Less" for amounts.
  • "Past" for recent time. "Last" for a final item.

5. Be concrete: name the thing, not the category

  • Simple words can still leave no picture. "Workflow design" and "operational support" name a category, not a thing.
  • Replace the category with the real instance the reader can see.
    • workflow design → the screens a worker taps through to register a patient
    • operational support → a one-page job aid, a short training and someone to call
    • continuity of care → the patient keeps getting treatment without a gap
    • data completeness → every treated patient shows up in the registry
  • If you must keep a category label, follow it with "such as" and an example.
  • Test each noun phrase: can the reader picture it or point to it?
  • Use real names, numbers and examples instead of "significant" or "improved."

6. Facts and honesty

  • Use only facts and numbers from the source or from the user.
  • Never invent a number to sound concrete. Write [need data: X] instead.
  • Keep names, dates, numbers, commitments and technical meaning exact.
  • Cut filler hedges: I think, it seems, maybe, perhaps, hopefully.
  • Keep real limits. State them plainly with their size ("two weeks of data from three clinics").
  • If unsure, say what's unknown and what would settle it.
  • Write "evidence shows," not "proves" or "we know."
  • Don't simplify away a detail or caveat the reader needs.

7. Patterns to cut

Use these on the editing pass, after a draft exists. Drafting with them on makes flat, over-pruned prose.

  • Restating: a second sentence repeats the first in fancier words. Keep it only if it adds a new fact.
  • Fake contrast: "dedicated, not part-time" when nobody proposed the weaker option. Keep it only if the reader might really assume the other thing.
  • Wrap-up lines: "Together," "Ultimately," "The bottom line is." Keep only in a long section that needs a pointer back.
  • Vague verbs: "leverage X to unlock Y." Name the real action and outcome.
  • Buzzword stacks: "data-driven, scalable, evidence-based." Say what it does.
  • Throat-clearing: "It is important to note," "This brings us to." Almost always cut.
  • AI tells: "In today's fast-paced world," "Here's a comprehensive overview," "Not only X, but also Y," "At the end of the day."
  • Three adjectives added for rhythm.
  • An opening that restates the question.
  • A closing summary that repeats what the reader just read.
  • Hype that tries to inspire instead of inform.
  • If a pattern looks like the author's deliberate voice, ask before cutting.

8. Structure

  • Lead with the takeaway, then the detail. Never open with background.
  • Write recommendations as direct instructions. For ministry partners, "We recommend..." is fine.
  • Use lists for separate items. Use paragraphs when ideas connect. Don't turn everything into bullets.
  • Keep list items parallel and one or two lines each. A bold label can start a scannable item.
  • Bold the key phrase in a paragraph so skimmers get the gist.
  • Headers in sentence case.
  • A busy reader should get the gist from headers and bold text alone.

9. By format

Email

  • Purpose or request in the first line.
  • Warm and human, but short.
  • End with the next step or the ask.

Slack or chat

  • Natural and brief, like a person talking.
  • Skip headers and heavy formatting.

Slides

  • One idea per slide.
  • The headline states the finding as a sentence.
  • A few short supporting lines. Fragments are fine.

Charts

  • Title states the finding ("Salt intake is rising"), not the data source.
  • No chart junk: 3D, heavy grids, decorative icons.

Reports and trip reports

  • Takeaway and recommendations at the top. Then findings, then detail.
  • Clear headers. Bold key phrases.

Proposals and donor pieces

  • Problem, recommendation, reason, next step.
  • Urgency comes from facts and scale, not hype.
  • Credit partners and shared effort before RTSL's own success.
  • Show what a local win means at wider scale.

Specs and PRDs

  • Problem: who has it, how often and what it costs. Two or three sentences, grounded in evidence.
  • Goals are outcomes, not outputs ("cut registration time in half," not "build a new form").
  • Non-goals with reasons, to stop scope creep.
  • User stories: "As a [specific user], I want [capability] so that [benefit]." Describe the need, not the widget.
  • Requirements ranked P0, P1, P2. If everything is P0, nothing is.
  • Acceptance criteria are testable. Replace "fast" or "easy" with a number or behavior.
  • Metrics have a target, a method and a date to check.
  • Open questions name who answers and whether they block work.

Jira tickets

  • One-line summary of the outcome.
  • Two or three sentences of context.
  • Acceptance criteria as a checklist.

Product copy (UI)

  • Tell users what they can do or what happened.
  • Use the words users use. Short labels.
  • Error messages say what went wrong and how to fix it.

10. RTSL house rules

  • "Resolve to Save Lives" first, then "RTSL." Never "Resolve."
  • RTSL "supports" or "accompanies" countries. It doesn't "help" them. An intervention can "help."
  • Mention health when describing what RTSL does.
  • Write priorities in full: Epidemic Prevention, Blood Pressure Control, Healthier Foods and Environment, Primary Health Care.
  • "Health threats," not "issues," "problems" or "conditions."
  • "Nutrition" or "food," not "diet." "Salt," not "sodium." "Trans fat," no hyphen. "Cardiovascular disease," singular.
  • Person-first: "people living with hypertension," "people affected by the outbreak." "People" or "residents," not "citizens."
  • "7-1-7" with hyphens. It's a "target" and an "approach."
  • American spelling, unless the audience uses British English.
  • Dates: Jan. 17, 2026. No ordinals.
  • US dollars, no "US" or "USD."
  • Few acronyms. Spell out on first use. Common ones: CVH, PHC, NCDs, LMICs, HCWs, CHW, MoH, LSSS, SPCs, FOPL, TWG, UHC. "WHO," never "the WHO."
  • Descriptive link text, never "click here."
  • Skip clichés: "build back better," "leave no one behind," "viruses know no borders."

11. Editing and feedback

  • Read for substance first. Don't polish a section that shouldn't exist.
  • Fix the order, then cut, then simplify words.
  • Check facts against the original after editing.
  • "Tighten" or "review": list proposed cuts so the user can choose. Don't silently rewrite.
  • "Rewrite," "fix" or "simplify": return the new text with a short change list. No long explanation.
  • "Simplify" means clearer, not just shorter.
  • "Warmer" means natural phrasing, not more words or emotion.
  • "More professional" means more precise, not more jargon.
  • "Shorter" means cut repeats and filler first, detail last.
  • The latest instruction wins.
  • Change only what was asked. A small edit never rewrites the whole piece.
  • Keep the parts the user said are working.
  • If feedback is clear, revise without asking.

12. Final check

  1. Is the takeaway in the first sentence or two?
  2. Could a busy reader act on this without reading twice?
  3. Can the reader picture every noun phrase?
  4. Is every number from the source, with gaps marked?
  5. Could you cut a sentence without losing anything?
  6. Zero em dashes, zero never-use words?
  7. For RTSL content: right tier, partners credited, no Oxford comma?

13. Examples (placeholders, replace with your own real edits)

Report

Before: In order to facilitate improved patient outcomes, it is recommended that stakeholders leverage a multi-pronged engagement strategy, given that 40% of patients do not answer follow-up calls. After: Reach patients in more than one way. Today we only call them, and 40% don't pick up. Add SMS reminders.

Report: plain words, no picture

Before: The next phase should strengthen the digital care pathway by improving workflow design and supporting the paths patients actually use. After: The next phase should fix two things. First, the screens a worker taps through to register a patient. Second, let patients enter care the way they really arrive: already on medication, referred from a private clinic or newly sick after a normal screening.

Email

Before: I hope this email finds you well. I wanted to reach out to follow up regarding the dashboard access request that was discussed during our meeting last week, and to check whether there has been any progress on this front. After: Hi Sam, a quick follow-up on dashboard access from last week's call. Has the request gone through? If it's stuck, I'm happy to chase it with the ministry team.

Slide

Before: Registration workflow analysis. Our analysis found that health workers need to navigate through nine separate screens to register a patient, although only four collect required fields. After: Registration takes nine screens. Only four collect required fields. Cut the other five or make them optional.

Notes for future edits

  • This skill replaces rtsl-writing-style-guide and differs from it on purpose: no em dashes, "about" instead of "approximately," and urgency from facts instead of an "inspiring" tone.
  • Sentence length and reading level are targets. They never override clarity or meaning.
  • Add a rule when the same kind of edit shows up three times across two or three documents. One-off edits are judgment calls, not rules.

相關技能