Write Clear

An agent skill for drafting, revising, and auditing clear technical and product documentation. It applies principles from the Google Developer Documentation Style Guide while protecting facts, technical tokens, uncertainty, and the author's voice.

This is not a generic "simplify everything" prompt. It helps an agent decide what to preserve, what to change, which guidance applies to the destination, and when to stop editing.

write-clear is a fork of nbj-write-clearly by Daniel Green (MIT). It flattens the layout for symlink-based install and extends the guidance after a fresh reading of the source guide. See NOTICE.md for attribution and docs/source-ledger.md for the dated source synthesis.

When to use it

Invoke $write-clear, or let a compatible agent select it automatically, for:

• developer documentation;
• procedures and help-center content;
• release notes;
• technical explanations;
• UI copy; and
• landing-page copy for technical tools, when the goal is clarity rather than hype.

Use it to draft new material, revise an existing draft, or audit prose without rewriting it. Do not treat it as a default voice layer for marketing, legal, academic, fictional, or personal writing unless you explicitly request this style.

What it improves

• Leads with the reader's answer or goal.
• Names actors and puts conditions before instructions.
• Uses direct, globally understandable language without making every sentence sound the same.
• Structures procedures, code, UI references, links, lists, and headings for scanning.
• Removes unsupported claims, pre-announcements, jargon, filler, and vague AI-sounding language.
• Preserves facts, caveats, modal verbs, quotations, commands, filenames, API names, product names, and UI labels.

Layout

The skill folder is self-contained, with SKILL.md at its root so both Claude and Codex discover it directly:

write-clear/
├── SKILL.md                     # lean core: workflow, authority order, preservation, validation
├── references/
│   ├── guide.md                 # high-frequency technical guidance, loaded on demand
│   └── official-index.md        # category map to the live Google pages
├── agents/openai.yaml           # Codex display metadata
├── docs/source-ledger.md        # dated rule-by-rule synthesis of the source guide
└── scripts/check.sh             # package validation

Install

Clone the repository, then link (or copy) the folder into each agent's skill directory. SKILL.md sits at the repository root, so the checkout is the skill.

Symlink it, so one git pull updates every agent at once:

git clone https://github.com/Ozhiaki/write-clear.git
ln -s "$PWD/write-clear" ~/.claude/skills/write-clear
ln -s "$PWD/write-clear" ~/.codex/skills/write-clear

To install a plain copy instead, copy the folder into the target skill directory:

cp -R write-clear ~/.claude/skills/write-clear

Start a new task so the agent refreshes its skill inventory.

Use

Invoke the skill by name:

Use $write-clear to revise this draft for clarity without changing its facts or voice.

It can also audit without rewriting:

Use $write-clear to audit this procedure. Report the highest-risk clarity problems, but don't rewrite it.

The trigger description also lets compatible agents select the skill for developer documentation, technical explanations, procedures, release notes, help-center content, UI copy, and technical landing pages.

Design

The compact SKILL.md holds the core workflow, authority order, preservation rules, and completion check. A conditional reference adds high-frequency technical guidance for procedures, code, commands, UI, tables, images, accessibility, and detailed audits. A separate official category index routes specialized compliance questions to the relevant live Google page without loading the whole guide for ordinary writing.

The skill deliberately operationalizes the core principles and high-frequency rules; it does not reproduce every word-list entry, punctuation exception, naming rule, or specialized format. For those cases, it routes the agent to the live guide. Project rules and reader clarity can still override house guidance when the result stays consistent.

The Google guide governs the default voice. A project can override it — for example with the Microsoft Writing Style Guide or ASD-STE100 (Simplified Technical English) — through the skill's authority order, which ranks project style above this skill's guidance.

See EVALUATION.md for the candidate comparison and forward-test results.

Inspiration and attribution

This project descends from an August 17, 2026 post by Nate B. Jones (@natebjones) suggesting that agents read the Google Developer Documentation Style Guide and turn it into a skill, by way of Daniel Green's nbj-write-clearly.

The skill paraphrases and reorganizes guidance from the Google Developer Documentation Style Guide. Google licenses its page content under CC BY 4.0 unless otherwise noted and its code samples under Apache 2.0. This repository is unofficial and is not endorsed by Google.

License

The original material in this repository is available under the MIT License. Google's source material remains under its stated licenses. See NOTICE.md for details.