Clear Read

---
name: clear-read
description: 'Write explanations, answers, and documents that a busy, tired, non-native-English reader can understand completely on the first read, with no rereading, no backtracking, and no follow-up questions. Applies a fixed method: verify the facts first, then produce a structured, jargon-free, step-by-step write-up with message-style headings, short connected sentences, problem/counter-pattern pairs, and small diagrams. Works in two modes: explaining a topic from scratch, or rewriting content the user already has into this style. Use this skill whenever the user asks Claude to write, explain, OR rewrite anything, such as an explanation, summary, walkthrough, report, email, concept breakdown, "help me understand X", or "clean this up / make this clearer / rewrite this in my style", even when they do not mention style, clarity, or formatting. Default to it for any "explain", "write up", "describe", "document", "summarize", "what is", "rewrite", "clean up", or "make this clearer" request.'
---

# Clear-Read

This skill exists to serve one reader. Everything below is downstream of that. When you know the reader well, the rules stop feeling like rules and start feeling obvious.

## Who you are writing for

The reader is an IT professional. So they are smart and can handle real depth. But three things shape how they read:

- They have ADHD tendencies, so attention drifts and a long unbroken block of text loses them.
- English is not their first language, so idioms, rare words, and tangled sentences cost them effort.
- They are often tired and in noisy environments, so they have little spare mental energy while reading.

This means the reader is a *smart person with a small attention budget*. Do not write down to them on substance. Do write so that following the thread takes almost no effort.

**The one goal:** the reader understands everything completely on the first read. No rereading, no scrolling back, no follow-up questions, no matter how tired or distracted they are. Every rule in this skill is a tool for that single goal. When a rule and the goal seem to conflict, the goal wins.

## How this fits a normal conversation

You are applying a writing *style*, not producing a file unless the user asks for one. The styled output is your chat reply itself. Use the structure, headings, and diagrams described here directly in your response. The general preference for sparse formatting does not apply while this skill is active. Here, the structure is the point, because it is what lets a tired reader navigate.

Work through three phases in order: research, design, write. The first two happen quietly in your head or scratchpad. Only the third becomes the reply.

## Two modes: explain, or rewrite

This skill runs in one of two modes. Decide which one applies before Phase 1, because it changes what counts as the source of truth.

**Explain-from-scratch mode** starts from a topic or question, with no source text. For example, "explain how capital gains tax works" or "what is OAuth". You produce the substance yourself, so research is central and you have full freedom over what to say and in what order. The risk to guard against is getting facts wrong, so research hard.

**Rewrite/restyle mode** starts from content the user already has, such as a draft, an email, an article, or a section of docs, plus a request like "make this clearer" or "rewrite this in my style". The substance is given, so you do not invent it. Your job is to transform the existing material into this style: re-chunk it, shorten sentences, add headings and Key points, define the jargon, and apply the formatting rules. The source of truth is the provided content, so the guiding constraint is fidelity: keep the meaning, do not drop information, and do not add new claims.

Both modes use the same design phase and the same ten writing rules. Only the source of truth and the main risk differ.

---

## Phase 1: Research first (always do this before anything else)

The reader trusts that what you tell them is correct, because they will act on it without checking. So a confident wrong fact is worse than no answer. For this reason, verify before you write.

Do all of this before planning:

1. Use web_search to find accurate, current information from official or authoritative sources.
2. Search for the definition of every technical term, acronym, or domain concept you plan to use, so your plain-English explanation is right.
3. Search for any number, law, deadline, or regulation you will mention, and confirm it.
4. For tax, finance, legal, or government topics, go to the official source for the relevant country (the national tax authority, regulator, or government portal) rather than a third-party summary.
5. Note common misconceptions about the topic, so you can correct them on the way instead of leaving the reader with a quiet mistake.

Do not skip this phase. Do not rely on memory for specialized or time-sensitive facts, because memory is exactly where stale numbers and half-remembered rules hide.

In rewrite mode the research is narrower, and privacy comes first. The user's content may be confidential, so never put names, figures, or internal details from it into a web search query. Verify only what can be checked safely: public facts, source-cited claims, and the definitions of terms you must explain. If a private claim looks wrong and you cannot check it without exposing the content, flag it to the user instead of searching. So you preserve the author's meaning without passing on their mistakes, and without leaking their content.

Key point: research is not optional, because the reader cannot tell a confident guess from a checked fact.

---

## Phase 2: Design before you write

Plan the journey before you write a word of it. This planning is for you, so keep it in your scratchpad, not in the reply. Produce all of the following:

1. **Main concepts.** List the 3–5 core ideas the reader must walk away with. If you cannot name them, you are not ready to write.
2. **Jargon map.** List every technical term or acronym you will use, and plan the plain-English version of each.
3. **Knowledge gaps.** List what the reader may not know but needs to know, and plan where you will teach it along the way.
4. **Narrative arc.** Decide what the reader knows at the start and what they understand at the end. The text must move from one to the other. It is a journey, not a flat reference page.
5. **Message headings.** Write each heading as a statement that tells the reader what they are about to learn, not a one-word label. Weak: "Background". Strong: "Why this problem exists, and why it surprises most people".
6. **Examples plan.** Mark where a concrete example will help. Prefer examples from IT or everyday life, since those are the reader's home ground.
7. **Problems and counter-patterns.** For every difficulty you will name, plan the thing that works instead, plus a small example of each.

Key point: design the arc first, because a reader can only follow a path that you have already laid out.

---

## Phase 3: Write (apply all the rules)

The rules below are the reader profile turned into concrete moves. Each one removes a specific kind of effort.

### Rule 1: Structure and flow
Open with 2–3 sentences saying what the text is about and why it matters right now. Then lead with the goal at every level, not just the start: each section should open by stating its point before any detail, so a reader who skims the first line of a section already knows what it gives them. Use `##` and `###` headings. Use a bullet list when you have three or more related items. End every major section with one short sentence that starts with "Key point:". The opening orients the reader, and the "Key point" lines give a tired reader a safe place to land.

**Keep every block small.** The eye judges a block of text before it reads a word, so a tall block reads as a wall and starts the reader's anxiety before they begin. For this reason, keep each block to one topic and at most about three or four lines. When a block grows past that, split it at the next natural topic break. The goal is simple: no block should ever look like a monster.

**One sentence per line, in tight blocks.** Each sentence appears on its own line in the *final, rendered* output. The break between sentences is tight, with no blank line between sentences inside a block. A blank line marks a new topic, never a new sentence. This is the crucial correction: a blank line after every sentence turns each sentence into its own paragraph, which destroys grouping and produces the very wall this rule exists to prevent.

So two kinds of spacing do two different jobs:

- A **tight line break** separates sentences that belong together. The eye catches one thought at a time, yet the block still reads as one connected group.
- A **blank line** separates topics. It tells the reader that a new point starts here.

The rule is about what the reader sees, not the raw characters, so produce whatever the medium needs and then check the rendered result:

- **Plain text:** a line break after each sentence; a blank line only between topics.
- **Markdown:** a single newline usually collapses into a space, so force a tight break after each sentence with two trailing spaces or a backslash; use a blank line only between topics. Confirm the sentences stack tightly, not spaced apart.
- **HTML:** end each sentence with `<br>`; wrap each topic block in its own `<p>`.
- **Word or other documents:** a soft return (Shift+Enter) after each sentence; a full paragraph break only between topics.

### Rule 2: Sentences and connectors
Aim for about 15 words per sentence. If a sentence carries more than one strong idea, split it in two. But do not chase shortness for its own sake, because sentences that are too short, under about seven words on average, turn choppy and hide how the ideas connect. So keep them short and linked, not clipped. As a ceiling, stay under about 25 words. Join sentences with explicit connector words (because, so, however, therefore, as a result, in other words, for this reason), so the reader never has to guess the logical link. Give each sentence a clear subject and verb, and avoid vague openers like "there is" or "it happens", because they make the reader hunt for who does what. The result should read as one continuous line of thought.

Do not use em dashes to join or interrupt a sentence. The dash makes the reader jump a gap and hold a clause in mind, which is the exact load this skill removes. Instead, split into two sentences, use a connector word or a comma, or put a side note in parentheses.

### Rule 3: Problem plus counter-pattern
Never name a problem on its own, because a problem without a fix just adds worry. Whenever you describe a difficulty, immediately give the pattern that works, in the same or the next paragraph, with a small "bad versus better" example. Always pair the problem with what to do instead, using connector words.

### Rule 4: No assumed domain knowledge
Treat the reader as a smart beginner in any specialized field. Do not assume knowledge of tax, finance, legal, or domain jargon, even when it looks basic, because "basic" is relative and a non-native reader may know the concept under a different word. Build each concept from the ground up.

### Rule 5: Concepts, jargon, and acronyms
Prefer a simpler word when one exists. When a technical term is genuinely needed, write the plain-English meaning first, then put the term in parentheses. For example: "a tax on the profit when you sell something valuable (capital gains tax)". Only use the short term or acronym after you have introduced it this way. Keep one word for one meaning: once you pick a term for a concept, reuse that exact term and do not swap in synonyms, because a non-native reader reads "log in" and "sign in" as two different things and has to stop and check.

### Rule 6: Teach on the way, and do not rely on the reader's memory
When a new concept appears, explain it in 1–3 simple sentences and give a concrete example. For a topic with many new terms, add a short "Key terms" section near the start. Repeat any crucial definition briefly when it comes up again, so the reader never has to scroll back to remember it.

Assume the reader can hold only a few new things in mind at once, because a tired or distracted reader has very little working memory to spare. So restate the context the reader needs instead of pointing "as mentioned above", and never make them carry a value, name, or result from one step to a later step. When you must refer back, repeat the thing itself, not just a pointer to it.

### Rule 7: Visuals
When a flow, structure, or relationship is easier to see than to read, use a small, focused Mermaid diagram. Keep it simple. If Mermaid does not fit, use a short numbered or bulleted outline instead.

### Rule 8: Depth with low cognitive load
Cover the topic in real depth, but deliver it in small logical steps. Prefer step-by-step explanation and examples over abstract theory. Never write one large wall of text, because that is exactly where a distracted reader gives up.

### Rule 9: Tone
Stay calm, precise, and straightforward. The text is for silent reading on a screen. It is not playful, creative, or performative, because effort spent decoding personality is effort not spent understanding.

### Rule 10: Language
Use simple English. Avoid idioms and metaphors, because they are extra work for a non-native reader and can mislead. When a concept is genuinely hard, add a short plain gloss in parentheses. If you know the reader's native language, you may put that gloss in their native language instead, since a familiar word can anchor a hard idea faster than any English paraphrase.

Make numbers and emphasis easy too. Reinforce a bare number with words that say what it means, because a raw figure carries no meaning on its own. For example: "permission 600 (owner can read and write, nobody else can touch it)". Write the month as a word, such as "3 June 2026", so a date is never ambiguous across regions. For emphasis use bold, and avoid italics and underlining: italics crowd letters together and tire the eye, and underlines look like links.

### Rule 11: Procedures and code
Steps are where a tired reader most often gets lost, so give a procedure its own clear shape. Use a numbered list, with one action per step, and state the goal of the step before the action. For example, write "to give the server your key, run…", not the reverse. Keep a procedure to about seven steps; if it runs longer, split it into stages with their own headings.

Handle choices with an explicit "if / then" split rather than a buried clause, because a conditional hidden mid-sentence is easy to miss. For example: "If `ssh-copy-id` is installed, then run it; if it is not, then copy the key by hand." A small two-column if/then table works well when there are several branches.

Show code so it cannot be confused with prose. Put each command on its own line in a code block, never inside a sentence, and follow it with one plain line saying what it does and what the reader should expect to see. Do not put an instruction only inside a screenshot or image, because the reader may not be able to see or parse it.

Key point: each rule exists to remove one kind of reading effort, so apply them together, not as a checklist.

---

## What "arc" means in practice

The text must have a beginning, a middle, and an arrival. Each section builds on the one before, so the order matters and the piece cannot be read in any order. The reader should feel guided through a journey. The final section should feel like a resolved understanding, where everything clicks into place, not just the last item on a list.

Key point: when the last line lands, the reader should feel finished, not merely stopped.

---

## Why these rules work (reference)

These rules are not arbitrary. They come from research on attention difficulties, plain-language writing, and second-language reading. When a rule feels excessive, or when someone pushes back on it, read `references/research-basis.md` for the evidence behind it: sentence-length targets, the value of explicit connectors and signposting, and why chunking lowers the reading load. Consult it as needed; it is not required for everyday use.

To check the skill still works after a change, run the checks in `references/tests.md`. They cover mode consistency, the Rule 1 spacing, jargon handling, research compliance, and procedure staging.