mickzijdel 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:
- Keep copy concise.
- Structure for scanning, not essay-style reading.
- Use the inverted pyramid (answer first, details second).
- Use plain language and short sentences.
- Design for comprehension, not just grammatical correctness.
Workflow
- Define audience and task.
- Cut nonessential content before reformatting.
- Rewrite lead sections to front-load key information.
- 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
- Confirm language simplicity and sentence-level clarity.
- Run the readability audit script and address failures.
Audit script
Use the bundled script for deterministic checks:
uv run scripts/readability_audit.py <file>
Optional comparison to baseline branch:
uv run scripts/readability_audit.py <file> --branch main
Optional grade target (default is 10):
uv run scripts/readability_audit.py <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:
uv run scripts/flesch_kincaid.py <file> [branch]
uv run scripts/vocabulary_profiler.py <file> [branch]
Use flesch_kincaid.py for a simple grade-only check. Use vocabulary_profiler.py 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:
- Deliver the revised text.
- Briefly summarize structural changes (for example: "added summary, split long paragraphs, converted dense section to bullets").
- Call out unresolved tradeoffs (brand voice, legal constraints, required jargon).
Credit: Adapted verbatim from Nate Berkopec's dotfiles.