An unofficial 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.
Invoke $nbj-write-clearly, or let a compatible agent select it automatically, for:
- developer documentation;
- procedures and help-center content;
- release notes;
- technical explanations; and
- UI copy.
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.
- 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.
Clone the repository:
git clone https://github.com/daniel-p-green/nbj-write-clearly.git
cd nbj-write-clearlyCopy the skill into your agent's skill directory. For Codex:
mkdir -p ~/.codex/skills
cp -R .agents/skills/nbj-write-clearly ~/.codex/skills/For agents that use ~/.agents/skills:
mkdir -p ~/.agents/skills
cp -R .agents/skills/nbj-write-clearly ~/.agents/skills/Start a new task so the agent refreshes its skill inventory.
Invoke the skill by name:
Use $nbj-write-clearly to revise this draft for clarity without changing its facts or voice.
It can also audit without rewriting:
Use $nbj-write-clearly 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, and UI copy.
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 source review inspected all 70 distinct content pages in the guide's live navigation on August 17, 2026. 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.
See EVALUATION.md for the candidate comparison and forward-test result.
This project began with 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.
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.
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.