A Claude Code skill that analyzes writing for readability using the Automated Readability Index (ARI). Point it at any markdown file and get an objective, sentence-level audit: grade level, hard sentences, adverbs, qualifiers, passive voice, and complex words — with a pass/fail verdict and specific rewrite suggestions.
| Check | Target |
|---|---|
| Document grade level (ARI) | ≤ 9 |
| Very hard sentences (ARI ≥ 14) | 0 |
| Hard sentences (ARI ≥ 12) | ≤ 2 |
| Adverbs | ≤ 3 |
| Qualifiers ("I think", "maybe", "sort of") | 0 |
| Complex words with simpler synonyms | 0 preferred |
| Passive voice | ≤ 2 |
The skill uses the Automated Readability Index (ARI) — the same algorithm the Hemingway Editor uses under the hood. ARI counts characters and words rather than syllables, making it fast and deterministic:
ARI = 4.71 × (chars/words) + 0.5 × (words/sentences) - 21.43
The result maps to a US grade level (rounded up). The default target is grade 9 — the US adult average. For reference, Ernest Hemingway's novels score around grade 5.
The script scores the full document and every sentence individually. Sentences exceeding grade 12 are flagged yellow (hard); grade 14+ are flagged red (very hard).
- Download
clarity-editor.skillfrom the releases page - Install it into Claude Code:
claude skill install clarity-editor.skillOr clone this repo and install from source:
git clone https://github.com/austinderrick/clarity-editor.git
claude skill install clarity-editor/Once installed, trigger the skill in any Claude Code session:
"Run clarity-editor on
my-post.md" "Clarity check this draft" "Check the grade level of this file"
The skill runs scripts/analyze.py on the target file and writes a clarity-report.md alongside it with the full audit and verdict.
You can also run the analyzer directly from the command line:
# Human-readable report
python3 scripts/analyze.py path/to/file.md
# Machine-readable JSON
python3 scripts/analyze.py path/to/file.md --jsonNo external dependencies. The script uses Python stdlib only (re, math, json, collections, pathlib).
============================================================
CLARITY REPORT — blog-draft.md
============================================================
Grade Level : 8 [Good] (target: ≤ 9)
Word Count : 949 [Good] (target: 700–1100)
Reading Time : ~5 min
Sentences : 69
HARD SENTENCES — 2 red (ARI ≥ 14), 1 yellow (ARI ≥ 12)
[RED 16] "The script walked each worksheet in four-row steps, assembled each
block into a single customer record, parsed the semicolon..."
→ Split at "parsed" or replace "assembled" with "built"
ADVERBS — 4 unique (target: ≤ 3)
"entirely" ×3
"immediately" ×1
QUALIFIERS — 0 (target: 0)
None found.
COMPLEX WORDS — 0
None found.
PASSIVE VOICE — 1 instance
"The report was written by the team last quarter."
============================================================
clarity-editor/
├── SKILL.md — Skill metadata and Claude workflow instructions
├── README.md — This file
└── scripts/
└── analyze.py — ARI analysis engine (stdlib only, no dependencies)
PASS (writing is clear and ready) when all of:
- Grade level ≤ 11
- Zero red sentences
- ≤ 3 yellow sentences
- Zero qualifiers
- Adverbs ≤ 5
NEEDS WORK when any of:
- Grade level > 11
- Any red sentences
- More than 3 qualifiers
- Adverbs > 8
Borderline results (grade 10–11, 1–3 yellows, 4–8 adverbs) pass with the specific issues noted in the report.
clarity-editor works standalone on any writing, but it's designed to slot cleanly into multi-stage editorial pipelines — after a qualitative editorial review pass and before a final humanizer/polish pass. It fills the gap that subjective review misses: objective, per-sentence complexity scoring.
To integrate into a pipeline, instruct Claude to run this skill on the output of the previous stage, then proceed to the next stage only if the verdict is PASS.
This skill was built after researching the Hemingway Editor's scoring system in depth. The core algorithm (ARI), threshold values (yellow ≥ 12, red ≥ 14), and issue categories (adverbs, qualifiers, passive voice, complex words) all map directly to how the Hemingway Editor works internally.
MIT