# Human Prose

> Write and revise clear prose in explanations, documents, comments, docstrings, commit messages, and PR descriptions. Use when drafting human-facing prose or when text feels dense, wordy, or machine-written. Preserve technical meaning and the user's requested voice and format.

- Skill: `homeowmorphism/human-prose-2` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add homeowmorphism/human-prose-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/homeowmorphism/human-prose-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: homeowmorphism (https://skillmd.com/u/homeowmorphism)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/homeowmorphism/human-prose-2

---


# Human prose

Codex adaptation (2026-09-16) of [homeowmorphism/human-prose](https://github.com/homeowmorphism/human-prose)
by Hang Lu Su. Modified scope and editing guidance for Codex; original
evidence and attribution are retained.

Write for a reader who processes one clause at a time. Each rule below
targets a reading difficulty. Use these as editing defaults, preserving
the user's requested voice, necessary terminology, and the document's
conventions. The [evidence base](references/evidence.md) distinguishes
research findings from the original author's preferences. Load it when
discussing the rationale or citations; it is not needed for routine edits.

## The rules

1. **One main idea per sentence.** Split overloaded sentences while
   keeping connections between ideas explicit (Flesch 1948). Avoid a
   string of fragments that makes the argument harder to follow.
2. **Avoid mid-sentence interruptions.** An em-dash aside or a nested
   parenthetical suspends a clause the reader must hold open (Gibson
   1998). Write a second sentence instead. A short parenthetical label
   (like this one) is fine; a clause-length intrusion is not.
3. **Prefer active voice and concrete verbs.** Name who does what when
   the actor matters. Replace abstract noun phrases with verbs where
   that makes the action clearer (Gough 1965; Coleman 1964).
4. **Given before new.** Open each sentence from material the reader
   already has, then add the new (Haviland & Clark 1974).
5. **No decorative emphasis.** Emphasis works by selectivity (Schneider
   et al. 2018). Flourishes are seductive details, and those measurably
   hurt learning (Rey 2012). Choose emphasis deliberately and sparingly.
6. **Plain register.** Explain unfamiliar terms in plain language before
   relying on them. Keep precise technical terms when they help the
   audience, and use them consistently. This adapts an upstream style
   preference; it is not a restriction on how often a term may appear.
7. **Name the referent.** An abstract noun standing for something else in
   the document ("this cost", "that discipline", "the price") makes the
   reader search for what it names, and they resolve it against the
   nearest candidate rather than the intended one (Haviland & Clark
   1974). Name the thing itself when the reference is ambiguous.
8. **Say it once, then stop.** Length is a cost the reader pays whether
   or not the words earn it. Cut restatements, preambles, hedges, and
   sentences that announce what the next sentence will do. Delete a
   sentence when it adds no meaning. Keep qualifications that carry real
   uncertainty, evidence, or scope.

## The pass

Apply the rules as a dedicated pass after the content is complete, not
while drafting. Rule 8 goes first: cut whole paragraphs before polishing
sentences, or the pass polishes text that should not exist. Keep verbatim
material untouched: quotes, compiler error text, signatures, citations.
Preserve facts, identifiers, links, and code behavior. A prose request
does not authorize unrelated code changes. In source files, respect the
project's comment and documentation conventions; check affected syntax
when a changed delimiter, docstring, or documentation test could matter.
Return the revised prose directly unless the user requested an explanation
of the edits.

