clear-writing

Files (1)

• SKILL.md

SKILL.md (first lines)

# Clear Writing

Rewrite prose for a capable reader who needs the relevant context without unnecessary effort.

## Preserve the meaning

Before rewriting, identify the main point, intended reader, and useful result. Preserve facts, requirements, safeguards, conditions, uncertainty, and any technical term whose exact wording carries meaning. Preserve precise meaning, not terminology for its own sake. Follow any format or content rules for the artifact.

Decide whether the reader needs clearer sentences or a fuller explanation. A draft can be accurate and grammatical while assuming the reader already knows the workflow, why it matters, or what a limitation prevents. When supporting sources are supplied, read the relevant parts before deciding the draft contains enough context. Use them to establish the missing facts, not to restart the investigation.

When context is missing, rebuild the passage around the reader's question using the available evidence. Explain the situation and practical consequence before the mechanism. Preserve the source's meaning, not the draft's omissions or order. Add only context supported by the sources; if a material ambiguity remains, name it and ask one focused question rather than silently resolving it.

Treat pasted text as output-only unless the user asks you to edit a file.

## Rewrite for the reader

Lead with the main point, then develop one idea at a time. Start a new paragraph when the focus changes. Prefer short, direct sentences with enough variation and connection to read naturally.

Use concrete subjects and direct verbs. Prefer plain, specific words over abstractions, internal jargon, stacked nouns, or inflated claims.

Prefer facts to shorthand. Write requirements as actions or conditions, not names for bodies of work. Do not assume readers share a label because the source uses it. Keep a label only when the context shows readers know its meaning, when the text defines and reuses it, or when the reader needs the exact name. Otherwise write the facts. Before returning, remove each label while keeping its explanation. If the reader can still understand and act, and the label does not save a repeated explanation, leave it out.

If the source gives a deadline of 3 pm today, replace “this request is urgent” with “send the answer before 3 pm today.” If it defines the opening checks as unlocking both exits and testing the smoke alarm, replace “finish the opening checks” with those actions. Without those facts, preserve the original meaning rather than inventing specifics.

Once the explanation supplies the context the reader needs, leave clear sentences alone. Change a sentence only when you can name what the reader could misunderstand or struggle to find. Style preference is not enough. Do not swap synonyms, join or split sentences, or add transitions merely to produce a rewrite.

Treat reader competence and reader context separately. Do not infer familiarity with a system, domain, incident, or local vocabulary from general technical expertise. Prefer the reader's terms. Introduce a local term only when the reader needs its exact name to act or continue the discussion, and explain its practical meaning first.

Use one term for each concept instead of rotating synonyms. Reserve hedges for real uncertainty, and state exactly what is unknown and why.

Keep connected ideas in prose. Use bullets for genuinely separate facts and numbered steps when order matters. Put conditions before actions, and keep each step focused on one action.

Remove repeated context, process narration, and detail that does not help the reader act or understand. Keep the result proportional to the subject. Use links for supporting detail when the reader can open them, and keep the context needed to understand the result in the text.

## Explain and update clearly

When explaining an unfamiliar process, system, or trade-off, begin with one concrete example. Reuse that example when comparing options or introducing lower-level details.

For technical explanations, read [`explain-code`](../explain-code/SKILL.md) before rewriting when the draft is dense, did not land, assumes unexplained system knowledge, or the reader asks for more context. Return the high-level layer or the specific drill-down the user requested, then give explicit breadcrumbs for useful areas they can explore next. Do not reproduce every layer of the source explanation at once.

Before asking a question, explain the situation that makes the answer necessary. Then ask one short, focused question.

When describing a change, state what changed, what happened before, and why the new behavior is better.

Treat investigation notes as source material, not as the structure of the response. For a decision or update, state the conclusion, its practical effect, and what happens next. Include only the evidence the reader needs to understand or act; link the rest.

Describe product requirements through user outcomes before implementation details when possible.

## Respect the artifact

Artifact-specific instructions decide required content and format. This skill improves the prose without replacing those rules.

For user interfaces, begin with the action the person is trying to complete and the visible effect. Use terms they encounter in their work. Keep service names, data-model terms, persistence details, and internal scope boundaries out of the interface unless knowing them changes what the person should do. Name buttons after the action or result, not the implementation mechanism.

For pull requests, commit messages, and review comments, write about the project change and the context the reader needs. Keep investigation notes, prompting, and agent workflow out of the artifact.

For agent instructions, use `writing-for-agents` to make the behavior contract reliable, then apply this skill to make it clear.

## Check the rewrite

Confirm that:

- the meaning and important constraints remain intact;
- the main point appears before supporting detail;
- concrete subjects perform clear actions;
- each paragraph or list has one purpose;
- requirements state actions or conditions instead of only naming work;
- each remaining label is known to the reader, defined and reused, or an exact name they need;
- describing words either change the meaning or have been removed;
- each changed sentence fixes something the reader could misunderstand or struggle to find;
- unnecessary or unexplained jargon, repetition, and process narration are gone;
- the reader can understand and act without decoding unfamiliar terms or reconstructing the conclusion from supporting evidence;
- the result is concise without hiding necessary context.

Return the rewritten text first. Add commentary only for a material ambiguity, trade-off, or intentional change the reader needs to know about.

From ryanmazzolini/pi-skills, MIT.

More from ryanmazzolini/pi-skills