| name | write-for-humans |
| description | Make human-facing text clear, natural, and appropriate for its readers without losing technical depth or important meaning. Use automatically whenever Codex creates, rewrites, edits, or reviews documentation, READMEs, guides, tutorials, explanations, plans, reports, specifications, summaries, release notes, handoffs, UI copy, or other prose people must understand. Use alongside file-format or documentation skills. Do not use for code-only output, machine-readable data, verbatim quotations, or text whose exact wording must remain unchanged. |
Write for humans
Write for the reader, not for the model producing the text.
Understand the reader
Before drafting, infer from the request and available context:
- what the reader wants to understand, decide, or do;
- what the reader probably already knows;
- which facts, terms, and constraints are new to them;
- how much detail they need now.
Do not mistake unfamiliar wording for lack of subject expertise. Clear language must not turn
expert content into beginner content. If a missing fact would materially change the text, ask
one short question. Otherwise, choose a reasonable reader model and proceed.
Write clearly
- Put the answer, outcome, or required action first.
- Use common, concrete words and direct sentence structures.
- Keep necessary technical terms. Define an unfamiliar term on first use, then use it
consistently.
- Expand an unfamiliar acronym on first use.
- Make relationships explicit: who does what, what causes what, and which condition controls
an action.
- Use useful repetition when it prevents ambiguity.
- Avoid idioms, inflated business language, decorative metaphors, vague abstractions, and
unnecessary synonyms.
- Prefer connected prose for an explanation. Use bullets for choices and numbered lists for
steps; do not fragment every thought into a list.
- Use headings only when they help the reader find information.
- Keep the tone direct, calm, and respectful. Never call a task “easy” or “simple.”
Explain in a useful order
For a concept, give the direct answer or mental model, then one concrete example, then explain
how it works. Put limits, trade-offs, edge cases, and formal detail after the core idea.
For instructions, state the goal and expected result, list prerequisites, then give numbered
steps in execution order. Show exact commands or values and place each warning beside the step
where it matters.
Preserve meaning
Do not simplify by deleting needed conditions, exceptions, numbers, units, warnings,
uncertainty, scope, or causal links. Do not turn a rewrite into a summary unless asked. If
plain wording would make a precise claim vague, keep the precise wording and explain it
underneath.
When adapting source material, run a separate fidelity pass. Compare the result with the
source for numbers, scope, conditions, sequence, causal direction, exceptions, warnings, and
uncertainty.
For documentation, describe only the supported current workflow and intended state. Put
prerequisites before actions, use interface and code terms exactly, and place a warning next
to the step where it matters.
Review from the reader's position
Before finishing, silently check:
- Can the intended reader understand the first paragraph without hidden context?
- Is the main point easy to find?
- Are unfamiliar terms, pronouns, conditions, and expected results clear?
- Is every detail useful for the reader's goal?
- Did the text preserve the source's scope and meaning?
Revise once if the check finds a problem. Do not print the checklist.
Independent review gate
Use a fresh reader for any draft that is at least 800 words, is fidelity-sensitive source
adaptation, or informs a consequential legal, medical, financial, security, architecture, or
operational decision. Give reader-fidelity-reviewer only the intended reader and goal, draft,
requirements, and source material or stable source anchors. Do not give it the authoring
conversation or reasoning.
Resolve every blocking comprehension or fidelity finding before delivery. If the correction
materially changes the affected passage, rerun the reviewer on that passage. The review is
complete when it reports no blocking issue and the author has performed the self-check above.
If the runtime cannot start a fresh reviewer, say that independent review is unavailable; do
not present the author's self-check as independent evidence.
