Communicating in writing
Skill isvlasov/rageatc-oss/plugins/rageatc-core-oss/skills/communicating-in-writing
Practical Claude Code / Cowork plugins for sharper thinking and structured problem-solving the slow way
npx -y skills add isvlasov/rageatc-oss --skill communicating-in-writingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Guides written communication — emails, reports, presentations, documents, website copy, newsletters, books. Use when writing or improving writing, adapting to an audience, or shaping document structure. Not for oral delivery or tool-specific formatting (slides, PDFs).
SKILL.md
6.2 KB, as published. Nobody here has run it
Communicating in Writing
Advisory and high-freedom: the layers below are thinking tools, not a sequence to execute. Work through intent, audience, and structure before drafting prose; craft comes last. Structure determines comprehension more than prose quality does — fix structure before fixing sentences.
Layer 1 — Intent
Establish before writing a word:
- Purpose — what the document must achieve, in one sentence. If there are multiple outcomes, rank them; a document with two equal purposes usually fails both.
- What changes — what the reader should know, believe, feel, or do after reading that they did not before. If you cannot state this, the writing is not ready to begin.
- Call to action — what you are asking the reader to do. Even informational documents have an implicit next step; surface it.
- Audience, document type, constraints — who reads it, what form it takes, what is non-negotiable.
Resolve all of these before drafting. A document begun without a clear purpose cannot be edited into shape — it needs rewriting once purpose is found.
Layer 2 — Audience
- Identify the primary reader (the decision-maker) and any secondary readers. For each: what do they know, what do they care about, what will they resist?
- Working memory holds roughly four new chunks at once. One idea per paragraph, lists of seven or fewer items, complex arguments broken into discrete steps.
- Prior knowledge determines structure, not just vocabulary. Experts tolerate dense sections and domain compression; non-experts need the same content in more sections, with scaffolding, analogy, and explicit transitions. Calibrate density to the reader, not to what feels natural to you as the expert.
- Mismatch signals: jargon the reader does not know, assumed context they do not have, detail level misaligned (too granular for an executive; too high-level for an implementer).
Layer 3 — Structure
- Lead with the answer. Conclusion or recommendation first, then reasoning and evidence. Exception — deliberate, not default: when the reader needs emotional or contextual preparation (bad news, controversial recommendations), build the case first.
- Each section answers exactly one question; split any section answering two. Headings signal what the section delivers, not its topic — "Three decisions required by Friday", not "Next steps".
- Test the through-line: can you state the document's argument in two or three sentences, in order? If not, the structure has a gap. For persuasive documents: situation → complication → question → answer.
- Persuasive documents work on three levels: sound argument (logos), credibility established early rather than assumed (ethos), connection to what the reader actually values (pathos). Most writing defaults to logic alone — check the other two explicitly.
- Readers remember openings and closings most. Open with the core message; close by reinforcing it or driving the call to action, never with a generic summary.
- For longer documents: summary up front, parallel structure in lists and headings, key terms repeated consistently — variation for style creates confusion, consistency aids navigation.
Layer 4 — Craft
- Active voice by default; passive only when the actor is genuinely unknown or irrelevant.
- Concrete, specific nouns and verbs; replace nominalisations with their verb forms (utilisation → use).
- Sentences of 15–25 words, most important information first; split any sentence the reader would re-read.
- One idea per paragraph, opening with the topic sentence. Paragraphs over six lines are doing too much.
- When content has relational, quantitative, or structural dimensions, represent it visually (table, diagram, flowchart) as well as in prose — a second encoding that reinforces the first, not decoration.
- Bullet lists for discrete, parallel items only; causal content needs prose or a numbered sequence.
- Headings, lists, and whitespace make the document scannable — readers scan before they read.
- Trust variable-width containers (email, web, chat) to wrap text — no hard line breaks; only when you control the rendering, aim for 60–80 characters per line.
- Conversational tone is more effective in most professional contexts; formal when the reader expects it (legal, regulatory, academic). Cut hedging unless the uncertainty is substantive.
Self-check
Evaluate, fix, then re-check:
- Buried lead — is the most important point in the first third? Can the reader state the main point after the first paragraph?
- Audience mismatch — any unfamiliar vocabulary, assumed context, or misaligned detail level?
- Overload — any section introducing more than four new concepts without a break? Paragraphs over six lines? Lists over seven items?
- Structure — a single logical thread from open to close? One question per section? Headings that signal, not label?
- Purpose — stated or implied in the first paragraph? A clear next step at the end? If the reader asks "what do you want me to do?", does the document answer immediately?
- Coherence — do the opening and closing frame the same document? Can a time-pressed reader get the essentials from headings and topic sentences alone?
Edge cases
- Mixed audience (experts and non-experts): layer the document — executive summary up front, technical detail in appendices or clearly labelled sub-sections. One body trying to serve both audiences equally serves neither.
- Brevity vs completeness: ask which failure costs more here. In most professional writing, burdening the reader is more common and more damaging than omission — cut to the reader's need, not to your thoroughness.
- Conclusions-first vs narrative logic in tension (the conclusion needs context to be understood): lead with a one-sentence orientation ("This is a recommendation to change our pricing model"), provide the context, then state and develop the conclusion.