# Simplify Prose

> Rewrites an existing document into plain language — shorter sentences, active voice, common words in place of jargon — and edits the file in place only after the human approves the specific changes. Use when a user asks to simplify, humanize, clarify, de-jargon, or plain-language a document, README, design doc, ticket description, or pasted prose, or to make writing easier to read.

- Skill: `abchoudh-amd/simplify-prose` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add abchoudh-amd/simplify-prose`
- Raw SKILL.md: https://api.skillmd.com/api/skills/abchoudh-amd/simplify-prose/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: abchoudh-amd (https://skillmd.com/u/abchoudh-amd)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/abchoudh-amd/simplify-prose

---


# Simplify Prose

Rewrite prose that already exists so a reader gets the point on the first pass.
[writing style](../_shared/WRITING-STYLE.md) governs prose being written for
the first time. This skill is the pass for everything written before that standard
applied, or written under time pressure, or inherited from someone else.

The rewrite is proposed before it is applied. An in-place edit of someone's
document is not reversible by reading the response, so the human sees the exact
changes and approves them first.

## Quick start

1. Read the target. Measure it against the countable targets below.
2. Identify every rewrite, and every span the preservation rules put off limits.
3. Present the proposal: each change as `line → before → after`, plus what stays
   and why.
4. Stop. Nothing is edited before the human answers.
5. On approval, apply the edits and report the new measurements.

## The standard

Plain language as defined by [plainlanguage.gov](https://www.plainlanguage.gov/guidelines/)
and ISO 24495-1. Seven rules carry almost all of it:

- **One idea per sentence.** A sentence carrying two ideas becomes two sentences.
- **Active voice with a named actor.** `The parser reads the CSV`, not `the CSV is
  read`. Passive is correct only in the three cases in [REFERENCE.md](REFERENCE.md).
- **The common word wherever the technical one adds no precision.** `use` not
  `utilize`, `start` not `initiate`, `about` not `with respect to`, `enough` not
  `sufficient`. A real term of art stays; see the substitution table's keep column.
- **Unwind nominalizations.** `we decided` not `a decision was made`. A `-tion`,
  `-ment`, or `-ance` noun usually has a verb trapped inside it.
- **Define an unavoidable term on first use**, once, in a clause. `The dispatcher
  binds a lease — the exclusive write claim a writer holds on a path — before...`
- **Lead each paragraph with its point.** The reader who stops after the first
  sentence should still get the claim.
- **Address the reader as `you`** where the document tells them to do something.

## Countable targets

Measure these before and after. Report both numbers in the proposal.

| Target | Value |
|---|---|
| Average sentence length | 20 words or fewer |
| Longest sentence | 35 words, a hard cap |
| Passive-voice sentences | 10% or fewer, each one justified |
| Unavoidable terms defined on first use | all of them |

These are proxies and nothing more. A document can hit every number and still be
unreadable, and a good document occasionally misses one on purpose. They exist so
the proposal shows the human something concrete instead of asserting improvement.
Never report a target as a grade, a score, or a passing result.

## Length is a ceiling, not a target

[writing style](../_shared/WRITING-STYLE.md) requires varied sentence and
paragraph length, and calls uniform three-clause rhythm the clearest sign nobody
chose the shape of the text. A short-sentence rule applied naively produces
exactly that rhythm.

So the 35-word cap is a ceiling. Under it, vary length deliberately: a four-word
sentence after a twenty-eight-word one is the point, not a defect. Chopping every
sentence to a uniform fifteen words satisfies the arithmetic and fails the
standard. The two rules are not in conflict, and a future reader should not
"resolve" them by deleting one.

## Preservation rules

Rewrite prose. Nothing else. Never modify:

- fenced code blocks, inline code spans, command transcripts, argv, or diffs;
- YAML frontmatter keys, JSON and schema keys, or field names;
- required headings — their text, order, count, and casing. The seven `##` sections
  in [`write-design`](../write-design/SKILL.md) are the case to watch: that skill
  freezes their names and order to match an upstream template;
- numbers, units, metric names, file paths, identifiers, or option flags;
- link targets. Link text may be rewritten; the URL never changes.

This is the contract rule from [writing style](../_shared/WRITING-STYLE.md)
applied to editing rather than authoring. Structure wins over style. Where a
contract dictates wording, keep the contract wording, report the conflict, and
rewrite the prose around it.

## Approval gate

Present the complete proposal, then stop and wait. State:

- the measurements before, and what they become after;
- every proposed change as `line → before → after`, grouped by which rule drives it;
- every span deliberately left alone, and which preservation rule protects it;
- any place where the standard and a contract conflict, and which one you kept.

Present the proposal as a concise numbered batch in ordinary prose and wait for a
reply. Where the real decision is a choice among competing rewrites of the same
passage, number the alternatives so the human can answer by number.

Do not invoke runtime plan-mode transitions, and never treat an internal plan state
as approval. This repository reserves plan mode for approving saved artifacts, and
an in-place edit is not an artifact write. The same reasoning governs
[`commit`](../commit/SKILL.md).

Approving a rewrite approves that rewrite. If the file changes on disk after the
proposal, measure again and present a fresh proposal rather than applying a stale
one.

## Input modes

**A file path** is the primary mode. It ends in an in-place edit of that file,
after approval.

**Pasted text** has no file behind it. Return the rewrite and the change list in
the response and write nothing. Do not create a file to hold the result, and do
not search for a file the text might have come from.

If the user names a file that does not exist, say so and stop. Do not create it.

## When a rewrite would break a contract

Leave the span alone. Report it as a conflict, naming the rule that wanted the
change and the contract that blocks it, and rewrite the rest of the document.

Never silently skip a conflicted span, and never narrow the job to the easy parts
without saying so. A conflict is a finding the human may want to act on elsewhere.

## Out of scope

- Code. Readability of code belongs to `simplify`; this skill treats code as a
  preserved span even when the code is unclear.
- Authoring new prose. A new HLD is [`write-design`](../write-design/SKILL.md);
  a new handoff is [`write-agent-handoff`](../write-agent-handoff/SKILL.md).
- Facts. The rewrite preserves meaning. If a sentence appears wrong, report it as
  a question; do not correct it under cover of a style pass.
- Structure. Adding, removing, reordering, or renaming sections is a rewrite of
  the document, not a simplification of its prose. Propose it separately.

## Routing

- Unclear code → the built-in `simplify`.
- A new design document → [`write-design`](../write-design/SKILL.md).
- A commit subject → [`commit`](../commit/SKILL.md), whose subject-format rules
  win over this standard on any conflict.
- Prose inside a template-bound artifact → rewrite the prose here, and leave the
  template structure to the skill that owns it.

## Additional resources

- [REFERENCE.md](REFERENCE.md) — the substitution table, passive-voice and
  nominalization detection, the measurement procedure, document-type adjustments,
  and the pre-edit self-check.
- [EXAMPLES.md](EXAMPLES.md) — worked runs covering an in-place edit, a contract
  conflict, and pasted text.
- [writing style](../_shared/WRITING-STYLE.md) — the authoring standard this
  skill extends to existing documents, and the contract rule it inherits.