write-for-humans

Write For Humans

Why this skill exists

docs-hygiene:write-for-agents is the write-side doctrine for markdown an agent loads, and it excludes human-facing prose deliberately, in its description and again in its own "What this skill does NOT do": end-user READMEs, changelogs, and marketing prose "have a different reader and different rules." This skill is those rules. The two are siblings on the same axis: one moment (while the doc is being written), split by who reads the result.

The reader here is a tired engineer on their first read. Four questions get you to prose they understand: what kind of document is this, how do sentences address them, how much does each sentence carry, and can any sentence be read two ways.

Resolve the standard before you apply one

The project's own style guide wins. Always. Before writing, look for one, a STYLE.md, a documentation contributing guide, a house standard named in the contributor docs, or a linter config encoding prose rules. When the project declares a standard, it is authoritative and everything below is a fallback you do not reach for. Say which one you resolved, in one line, before you write.

The layers below are a named default set, not this plugin's house rules:

Layer	Question it answers	Standard
Mode	What kind of document is this?	Diátaxis
Address	How do sentences talk to the reader?	Google developer documentation style
Load	How much does each sentence carry?	ASD-STE100 Simplified Technical English
Ambiguity	Can this be read two ways?	Global English

A project that adopted a different guide, Microsoft's, Chicago, an in-house one, gets that guide, not these. A project with none gets these, and you say so, so the choice stays visible and the project can overrule it later. Never silently impose one.

When a rule makes a sentence worse, fix the sentence another way or leave it alone. The rules serve the reader; a sentence that obeys every rule and sounds machine-written has failed.