readability

name	readability
description	This skill should be used when writing or revising web content, product copy, AI-generated responses, docs, or long-form text where clarity, scannability, and comprehension matter.

Readability

Apply this skill to turn dense copy into web-friendly content that people can scan, understand, and use quickly.

Principles to apply

Ground decisions in NN/g guidance from:

• references/nng-guidelines.md
• https://www.nngroup.com/articles/genai-write-for-the-web/
• https://www.nngroup.com/articles/formatting-long-form-content/
• https://www.nngroup.com/articles/legibility-readability-comprehension/

Core rules:

1. Keep copy concise.
2. Structure for scanning, not essay-style reading.
3. Use the inverted pyramid (answer first, details second).
4. Use plain language and short sentences.
5. Design for comprehension, not just grammatical correctness.

Workflow

1. Define audience and task.
2. Cut nonessential content before reformatting.
3. Rewrite lead sections to front-load key information.
4. Add scan aids:
   • Descriptive headings
   • Bullets for parallel points
   • Brief summary or key takeaways for long content
   • Selective emphasis only where it materially aids scanning
5. Confirm language simplicity and sentence-level clarity.
6. Run the readability audit script and address failures.

Audit script

Use the bundled script for deterministic checks:

ruby scripts/readability_audit.rb <file>

Optional comparison to baseline branch:

ruby scripts/readability_audit.rb <file> --branch main

Optional grade target (default is 10):

ruby scripts/readability_audit.rb <file> --target-grade 9

The script reports:

• Flesch-Kincaid grade
• Sentence and paragraph length pressure
• Heading/list density for longer content
• Lead-paragraph length

Supplemental scripts are available when a narrower check is useful:

ruby scripts/flesch_kincaid.rb <file> [branch]
ruby scripts/vocabulary_profiler.rb <file> [branch]

Use flesch_kincaid.rb for a simple grade-only check. Use vocabulary_profiler.rb to estimate how much copy uses common top-1000 English words; it is backed by scripts/top1000.txt.

Treat these scripts as guardrails, not substitutes for human judgment.

Output expectations

When using this skill in a user-facing task:

1. Deliver the revised text.
2. Briefly summarize structural changes (for example: "added summary, split long paragraphs, converted dense section to bullets").
3. Call out unresolved tradeoffs (brand voice, legal constraints, required jargon).