Clear writing and clear thinking are inseparable. A document is an instrument by which thought becomes visible, testable, and useful.

This project assembles principles, guidelines, and tools to improve the quality of practical writing by humans and by agents.

The benefits are more than polished language. The goal is to improve thinking as expressed in language and to encourage prose where the form, content, and expression fit both human needs and the work to be done.

In many professional and technical domains, documents are increasingly written in two main ways:

• humans writing with agent review or assistance
• agents writing with human oversight

Sadly, agents often don’t write well. And humans don’t pay enough attention to notice.

But this is not hopeless. The disciplines that have long improved human writing—good judgment, plus care to avoid common errors—improve agent writing too.

The focus here is practical prose: writing that helps a reader—human or agent—understand, decide, do, or verify something. Practical prose includes technical documents, research reports, specifications, memos, plans, and other artifacts where value depends on usefulness.

Three key points:

• Many elements here do not apply to creative writing, personal essays, fiction, or other writing where the primary goals are expressive or creative.

• We focus only on English. In the future, this could be extended to other languages. With the help of sensitive native speakers and increasingly powerful AI translations, it’s likely we could adapt these guidelines to other languages effectively while preserving the nuances specific to each language.

• The focus on utility does not mean rejecting the needs of human readers. Good prose serves human needs and reflects human qualities. Usefulness is not in opposition to style, beauty, or human expression. The best practical writing often joins the classic virtues of structure, precision, and evidence with the romantic virtues of voice, rhythm, and feeling.

Run the Practical Prose CLI in any repo with uv—no install step required:

uvx pprose --help        # explore the commands
uvx pprose install       # add the Agent Skills to the current repo

The PyPI package and the command are both pprose. pprose install writes one SKILL.md per workflow into both .agents/skills/ (Codex, Gemini CLI, and pi read these natively) and .claude/skills/ (Claude Code mirror), and maintains a marker-bounded pprose block in AGENTS.md (preserving any other content). Re-running it is idempotent. See Agent Skills for the skill catalog and Tooling for the CLI reference and install flags.

These tools help you use agents more effectively when writing, give agents context that improves fully agent-written text, provide a framework to find weaknesses in human or agent writing, and visualize quality to sharpen your own awareness. Concretely:

1. Guiding principles and guidelines for quality in practical writing for use by agents and humans
2. Measures of writing quality that include six areas (purpose, expression, form, reasoning, grounding, and judgment) divided into 20 dimensions
3. An evaluation rubric on how to evaluate text according to these dimensions
4. An automated visualization tool that uses an LLM to evaluate the quality of any text across these dimensions and visualize it
5. Agent skills and a CLI to package all of these documents and evaluation tools
6. A bibliography of notable works on practical writing

The visualization tool evaluates any document across all 20 dimensions and renders the result as a card:

Left: Vannevar Bush, “As We May Think” (The Atlantic, 1945)—lucid prose but lightly sourced and single-lens. Right: the Apple Media Services Terms—broad in scope and cleanly organized, yet with several Reasoning and Judgment dimensions N/A: a contract states terms rather than arguing or weighing them. Both were graded by Claude Opus 4.8; scores depend on the model and vary slightly between runs. Source texts are in example-texts/; see the dev note for how these are generated.

No. It is a new project; v0.1.0 shipped in June 2026. I’ve only been using it on my own projects since spring 2026. It likely has a lot of ways it could improve. But it does draw on years of reading and editing both human-written and now agent-written text.

Technical writers and editors have known for centuries that the best way to validate written ideas is through disciplined editorial review. Evidence can be checked, reasoning can be inspected, uncertainty can be calibrated. By enforcing standards for quality writing, we think more clearly.

What is different now is that language is drafted, transformed, summarized, and evaluated by LLMs in greater volume than by humans. Much of it is slop: not just distasteful but often inaccurate or harmfully misleading.

Fluency is cheap. Judgment remains precious.

There is not enough human attention to filter and edit AI slop. By codifying standards for quality, we can not only help humans write better but help machines assist us in thinking and writing clearly.

Many of the challenges in working with AI involve improving the quality of thinking of both the agents and the people who oversee the work. You can outsource writing and thinking to agents. But you can’t outsource your understanding or your judgment.

At its best, AI does not replace but rather augments human intellect. Clear thinking is essential to solving the hardest problems. And clear language is the way we will work with this new generation of knowledge tools.

Entire books have been written on what “quality” really is. For our purposes, quality is fit: the parts of a document work when purpose, truth, form, evidence, language, and reader needs support the same task.

The seven principles below decompose that fit into specific attributes.

Principles set direction, but when an editor evaluates a piece of writing, they look at specific qualities or dimensions.

Each dimension maps back to one or more principles in practical-prose-principles.md; prescriptive rules live in practical-prose-guidelines.md and 1-5 scoring anchors in practical-prose-rubric.md.

The system has seven reference layers and two operational layers. Each layer answers a different question.

The Common layer is the base substrate. common-doc-guidelines.md captures general organization, structure, style, and formatting rules that apply to any document—technical docs, READMEs, internal memos, specifications—not just practical prose. The practical-prose layers (Principles, Guidelines, Rubric) build on top of it with the seven principles and 20 dimensions specific to evaluating practical writing. Principles, Guidelines, and Rubric form a tight triple: same seven principles, same 20 dimensions, same six groups (Purpose, Expression, Form, Reasoning, Grounding, Judgment). Genre supplements extend those core layers only where a genre demands more; the first one covers comprehensive practical guides, not all practical documents. The bibliography supplies the intellectual basis; the shortcuts and runbooks are how the system gets used in practice.

• Writing a document and want the rules: practical-prose-guidelines.md.
• Writing a comprehensive practical guide: writing-practical-guides.md, including its groundwork process for scoping the guide before outlining.
• Scoring a document and want the anchors: practical-prose-rubric.md.
• Running a pre-publish self-audit: practical-prose-quick-checklist.md.
• Running a formal eval: the runbooks/ directory.
• Understanding why a rule exists: the corresponding principle in practical-prose-principles.md, and the source tradition in practical-prose-bibliography.md.
• Looking at the tooling: tools/pprose/ is the installable Python package with the metrics, scoring, and report generators.

This repo can be used directly by modern coding agents through AGENTS.md and portable Agent Skills under skills/. The eval skills use the pprose tooling described below.

Install paths:

1. Recommended: let pprose install set up every supported surface in any repo (see Quick Start for what it writes and the scope flags).
2. Point the agent at this repo and let AGENTS.md route to the right skill: the committed skills/<name>/SKILL.md files are version-pinned discovery copies that work as a npx skills add / skills.sh landing page.
3. If a Claude Code plugin marketplace entry exists, install that as a Claude-only convenience.

The skills are intentionally small routers: each names the workflow once and points at pprose <command> / pprose guidelines <name> / pprose shortcut <name> rather than duplicating that content. The pprose CLI bundles the guidelines, shortcuts, runbooks, and rubric inside its wheel, so an installed skill works in any repo with no other files present.

tools/pprose/ is a standalone modern-Python package (bootstrapped from simple-modern-uv). The distribution and console-script entry point are both pprose:

• pprose metrics: deterministic metrics over a document (banned-register hits, vague-word counts, link validity, frontmatter presence, etc.).
• pprose score: score a document against the rubric via Pydantic AI (Anthropic, OpenAI, or Google; --model required); Anthropic runs reuse a cached rubric+guidelines block, and --batch runs N artifacts in parallel.
• pprose report: combine metrics and scores into an eval report; validate, compute-derived, and from-metrics subcommands.
• pprose compare: compare N eval reports across versions or variants.

It also bundles the guidelines, shortcuts, runbooks, and rubric and serves them as reference subcommands (pprose guidelines|shortcut|runbook|skill <name>, --list to enumerate), so the skills work in any repo. Every artifact pprose install generates carries a format=fNN surface=… stamp, so re-running install is idempotent and a newer-format artifact is never clobbered by an older pprose. Each generated skill references pprose with a pinned, local-first invocation (pprose if on PATH, else uvx pprose@<version>—the trusted version that ran install—else a message telling the user to install uv or pprose). Scope installs with --project (the default inside a git repo) or --global, and select destinations with --surfaces=portable,claude,agents-md. New releases can add guidelines and skills; because installed skills pin the version that installed them, a repo picks up additions only when you upgrade and re-run install (uvx pprose@latest install, or uv tool install --upgrade pprose && pprose install). Re-running refreshes the artifacts and the version pin they bake.

Example eval pass (no install via uv; score needs --model plus a provider API key):

uvx pprose report from-metrics path/to/doc.md --label my-doc --scope-class brief --out my-doc.eval.md
uvx pprose score my-doc.eval.md --model opus
uvx pprose report validate my-doc.eval.md

Code is MIT licensed. Content (principles, guidelines, rubric, and other prose) is CC BY 4.0. See LICENSE for details.