# Readability

> 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.

- Skill: `mickzijdel/readability` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add mickzijdel/readability`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mickzijdel/readability/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mickzijdel (https://skillmd.com/u/mickzijdel)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mickzijdel/readability

---


# 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:

```bash
uv run scripts/readability_audit.py <file>
```

Optional comparison to baseline branch:

```bash
uv run scripts/readability_audit.py <file> --branch main
```

Optional grade target (default is 10):

```bash
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:

```bash
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:

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).

---

**Credit:** Adapted verbatim from [Nate Berkopec's dotfiles](https://github.com/nateberkopec/dotfiles/blob/main/files/home/.claude/skills/readability/SKILL.md).