Prose

Prose — Clarity, Legibility, Scannability

When this skill is invoked, make the writing land on a reader. If invoked with an argument (e.g., /prose ARCHITECTURE.md), apply the standard to that file and rewrite what fails it. If invoked without arguments, apply it to the prose you are currently writing.

The reader is a busy human who did not read the source, will not read every word, and is scanning to answer one question. Prose that ignores that reader is decoration. Every rule below exists to shorten the distance between their question and its answer.

This skill is both user-invocable and agent-granted:

• User-invoked — run /prose <path> to hold an existing doc to this standard and fix what fails.
• Agent-granted — agents that list prose in their skills: frontmatter write to this standard by default, without an explicit invocation.

1. Plain language

• Everyday words over jargon. Prefer use to utilize, start to initiate, build to facilitate the construction of.
• Define unavoidable terms at first use. Domain terms and acronyms earn their place only if you spend one clause explaining them: "the render closure (every item pulled in by a selection)".
• No jargon walls. If three specialized terms land in one sentence, the sentence is for you, not the reader. Break it up and define as you go.
• Say the thing. Abstraction that could describe any project ("leverages a robust architecture to enable seamless workflows") says nothing. Cut it.

2. Sentences and paragraphs

• One idea per sentence. When a sentence needs two commas and an "and" to hold together, it is two sentences.
• Short paragraphs — four lines or fewer. A wall of text is skipped, not read.
• Active voice, named actor. "The installer prunes stale files," not "stale files are pruned." The reader needs to know who does what.
• Cut the throat-clearing. Delete openers like "It is important to note that," "In this section we will," and any first line that merely restates the heading above it.
• No hedge stacking. "It may possibly be somewhat slower" means nothing. Either it is slower, or you don't know — say which.

3. Reader-first ordering

Use the inverted pyramid: the conclusion, then the detail that supports it.

• Lead with the most important fact — the answer, the decision, the outcome. Never bury it under context the reader may not need.
• Context comes after the payoff, not before it. A reader who stops at the first line should still leave with the main point.
• Order sections by what the reader asks first, not by how the system was built. "How do I use it" almost always precedes "how it works inside."

4. Scannability

The test: a reader who reads only the headings and the bolded leads must still get the story.

• Headings carry information. "Renders are frozen output" beats "Notes" or "Details."
• Bold the lead of each bullet so the eye can pick the list apart without reading it.
• Structure over prose for parallel content — three or more parallel items belong in a list or a table, not a paragraph. (See the md-maximalist skill for choosing the form.)
• One idea per bullet. A bullet with a sub-clause pile-up is a paragraph in disguise.

5. Concrete over abstract — from a source

Specificity is this section's demand and its trap: the concrete details that make writing land are also the easiest ones to invent. Reach for them, but only from a source you actually read.

• Numbers, names, and paths beat generalities. "Keep STATUS.md under 100 lines" beats "keep it reasonably short." "installer/lib/render.mjs" beats "the render module." Take each one from a file you opened, not from what the name suggests it should be.
• Show an example wherever a rule is easier to demonstrate than to state.
• Quantify claims — with sourced numbers only. "Faster" is not a fact; "~200ms faster on a 500-file repo" is. But a specific you didn't read somewhere is fabrication wearing concreteness's clothes — it reads more credible than the vague claim it replaced, which is precisely what makes it worse.
• When the source doesn't carry the fact, omit it. A missing detail is a gap; an invented one is a defect. Never close the gap with a number that merely sounds right.

6. Read it back before shipping

Re-read the finished text as the target reader — someone who has not seen the code and has thirty seconds:

1. Does the first line answer their question, or make them hunt?
2. Can they skim headings + bold leads and still get the story?
3. Does every sentence earn its place? Delete any that does not.
4. Is there a word doing less work than a simpler word would?

When called by agents

An agent granted prose writes to this standard inline — plain words, conclusion first, scannable structure — rather than producing a draft and cleaning it up afterward. When editing an existing doc, hold the surrounding paragraphs you touch to the same standard, but do not silently rewrite an owner-voiced document whose register is deliberate; flag it instead.