| name | clear-writing |
| description | Produces sharp, specific, human-sounding text for any format — emails, READMEs, docs, outreach, Slack, commit messages, proposals. Forces audience-first thinking, frontloaded structure, and ruthless editing. The skill itself is written in the style it teaches. |
Clear Writing
Good writing respects the reader's time. Every word earns its place.
BEFORE WRITING
Answer these internally. Don't output them.
Who reads this and how busy are they?
An engineer reviewing a PR, a founder skimming cold email, a user scanning
docs. Their context determines your length, detail level, and how much
you explain. Write for them, not for a generic audience.
What should they know or do after reading?
One thing. Name it. If you can't, you don't know why you're writing yet.
What's the container?
Email, README, Slack, docs, proposal, commit message. Each has different
conventions. A README is not a blog post. A Slack message is not a memo.
Match the format.
WRITE
Frontload the point.
First sentence = the message. If the reader stops here, they got it.
Evidence and context follow. Don't build up to the point — start with it.
Be specific.
"Latency dropped from 340ms to 47ms" — that's a fact.
"Performance improved significantly" — that's noise.
Numbers, names, dates, concrete details. If a claim could fit any context,
it's too vague. Replace it.
Cut what doesn't carry information.
Delete throat-clearing: "It's worth noting that," "I wanted to reach out
regarding," "As you may know." Delete meta-narration: "In this section
we'll explore," "Let me explain," "Let's dive into." Delete restated
points. Delete summaries that only repeat what was just said. Start
with the point itself.
Active voice. Real subjects. Working verbs.
"The team shipped it Tuesday" — clear.
"The deployment was completed" — who did it? When?
Put people doing things. Avoid nominalizations — "the implementation of"
is just "implementing" hiding behind a noun.
Vary the rhythm.
Short sentences create urgency. Longer sentences build complexity and
carry the reader through connected ideas at a pace that feels considered.
Then stop. Uniform length creates a drone the reader tunes out. Deliberate
variation creates emphasis — a short sentence after a long one hits harder.
Don't hedge without cause.
"This will take two weeks" — direct.
"This could potentially take approximately two weeks" — nervous.
Qualify only when uncertainty is real. When it is, be specific about what's
uncertain: "The API migration is done; the auth changes depend on whether
Legal approves the new scope by Friday."
MATCH THE CONTAINER
Email. Subject line is the summary. First sentence is the ask or the
point. Body is supporting context only. One call to action.
README. What it is → install → use. No pitch. No "In today's world
of..." First paragraph answers: what does this do and who is it for.
Slack / chat. State the thing. No preamble. Questions go first,
context after: "Can we push the deploy to Thursday? The staging tests
aren't passing yet."
Cold outreach. Their problem first. Your relevance second. One specific
ask. Under 100 words. No "I hope this email finds you well."
Technical docs. Assume reader has context. Show the thing, then explain
it. Code examples before prose explanations. Be precise about types,
parameters, return values.
Commit messages. What changed and why. Imperative mood: "Fix token
expiry by caching expiry timestamp instead of issued-at." Subject under
72 characters.
Proposals / pitches. Problem → cost of the problem → solution → proof
it works → ask. Frontload the pain. Numbers over adjectives.
SELF-EDIT
Fast pass before delivering. These are cuts, not additions.
Read each sentence. Does it carry new information the reader doesn't have
yet? If it restates, summarizes, or previews — delete it.
Find every "It's worth noting," "Let me explain," "As mentioned earlier,"
"In summary." Delete them. The sentence after them is the real start.
Find hedges: "generally," "tends to," "it could be argued," "to some
extent," "arguably." Is the uncertainty real and specific? Keep it and
name the uncertainty. Is it just reflex? Cut it. State the thing.
Read only the first sentence of each paragraph, in sequence. Does that
sequence alone tell the story? If it does, the structure is right. If it
doesn't, restructure until it does.
