# Nbj Write Clearly

> Drafts, revises, and audits reader-first technical and product documentation. Use when working on developer docs, procedures, release notes, technical explanations, help-center content, or UI copy where clarity, source fidelity, accessibility, or global readability matters. Do not auto-apply it to marketing, legal, academic, fictional, or personal writing unless the user explicitly requests this style.

- Skill: `yfe404/nbj-write-clearly` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add yfe404/nbj-write-clearly`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yfe404/nbj-write-clearly/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: yfe404 (https://skillmd.com/u/yfe404)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yfe404/nbj-write-clearly

---


# NBJ Write Clearly

## Outcome

Produce prose that lets the reader understand the point, identify the actor and action, and complete the task without rereading. Preserve the author's facts, intent, uncertainty, and useful voice.

## Apply the right authority

Use this order of precedence:

1. Follow the user's explicit request and the destination's requirements.
2. Preserve source facts, quotations, code, UI labels, product names, and intentional terminology.
3. Follow project-specific style.
4. Apply this skill's Google-derived guidance.
5. Consult other references only when the preceding sources are silent.

Depart from a guideline when doing so makes the content clearer for its actual readers. Stay consistent after making that choice.

## Write or revise

1. Identify the reader, their goal, the artifact type, and whether the task is to draft, revise, or audit.
2. Mark content that must not drift: facts, claims, qualifications, quoted language, technical tokens, links, and required structure.
3. Put the result or purpose first. Give each paragraph one idea and put critical information early.
4. Name the actor. Prefer active voice, present tense, and second person when addressing the reader. Use imperatives for steps.
5. Put a condition or circumstance before the instruction it controls.
6. Prefer familiar, precise words. Define necessary jargon or abbreviations on first use. Keep one term for one concept.
7. Use short sentences and paragraphs, but don't flatten every sentence into the same rhythm. Use common contractions when they sound natural.
8. Remove throat-clearing, repeated conclusions, fake quotations, excessive claims, pre-announcements, clichés, idioms, and decorative metaphors.
9. Structure for scanning: sentence-case headings, numbered lists for sequences, bullets for parallel items, and descriptive links.
10. Read [references/guide.md](references/guide.md) when the artifact includes procedures, code, commands, UI labels, tables, images, accessibility requirements, or a line-level style audit.
11. Read [references/official-index.md](references/official-index.md) only when the user requests Google Style Guide compliance or the task turns on a specialized rule such as word choice, product naming, punctuation, grammar, dates, units, mathematical notation, HTML, Markdown, filenames, or trademarks. Consult only the relevant official page when browsing is available.

## Protect meaning and voice

- Do not add facts, certainty, praise, urgency, or product claims.
- Preserve source modality such as *can*, *might*, *should*, and *will*. Do not change it only to satisfy a tense preference.
- Do not replace exact code, commands, filenames, API names, UI labels, or quotations with stylistic alternatives.
- Do not rewrite when the user asked only for an audit. Report findings in priority order and give bounded examples.
- Do not force documentation conventions onto dialogue, fiction, legal language, quotations, or a deliberately personal voice.
- Do not make prose childish or robotic in the name of simplicity. Prefer the clearest accurate term, even when it is technical.

## Validate

Before returning the result, check that:

- the opening answers the reader's main question;
- every instruction names or clearly implies the actor;
- conditions appear before the actions they govern;
- each pronoun has an unambiguous referent;
- terminology, capitalization, and formatting are consistent;
- claims remain factual, scoped, and supported by the source;
- a global reader can understand the prose without decoding slang or culture-specific references;
- the revision preserves all required facts, caveats, and technical tokens;
- the output still sounds like the author when voice matters.

Stop when the content is clear, accurate, consistent, and fit for its destination. Do not keep polishing lines that already do their job.