clarity-editor

name

clarity-editor

description

Analyze writing for readability and clarity using the Automated Readability Index (ARI). Runs an objective, sentence-level analysis that scores grade level, flags hard-to-read sentences, and detects adverbs, qualifiers, passive voice, and complex words with simpler synonyms. Use when asked to: check readability, run a clarity pass, analyze a draft, score sentence complexity, check grade level, or improve writing clarity. Triggers on: "clarity check", "readability check", "run clarity-editor", "check this draft", "grade level", "hard sentences", "adverb check", or "is this easy to read".

Clarity Editor

Runs scripts/analyze.py on a file, interprets the output, and produces a structured report with a pass/fail verdict and specific rewrite recommendations.

Algorithm

Uses the Automated Readability Index (ARI) — chosen over Flesch-Kincaid because it counts characters (not syllables), making it faster and more consistent:

ARI = 4.71 × (chars/words) + 0.5 × (words/sentences) - 21.43

Result = US grade level (rounded up). Default target: Grade 9 (US adult average). Ernest Hemingway's novels score grade 5. Grade level is not a measure of quality — it measures who can read it without effort. Grade 9 reaches the broadest audience.

Step 1: Run the Script

python3 ~/.claude/skills/clarity-editor/scripts/analyze.py "<path-to-file>"

The script strips markdown formatting, scores the full document and each sentence individually, and detects adverbs, qualifiers, complex words, and passive voice.

Step 2: Interpret the Output

Metric	Target	What it means if over
Grade Level (full doc)	≤ 12	Overall sentence density is too high
Red sentences (ARI ≥ 16)	0	Must rewrite — split at conjunctions
Yellow sentences (ARI ≥ 14)	≤ 3	Simplify or split if possible
Adverbs (unique -ly words)	≤ 6	Replace verb+adverb with a stronger verb
Qualifiers	0	Weakens authority — remove or restate with conviction
Complex words	0 preferred	Accept the simpler synonym
Passive voice instances	≤ 2	Rewrite as active where it matters most

Sentence thresholds explained:

• Yellow = sentence ARI 2+ grade levels above target (≥ 14 for grade-12 default)
• Red = sentence ARI 4+ grade levels above target (≥ 16 for grade-12 default)

Step 3: Produce the Report

Write a clarity-report.md in the same directory as the input file.

Report format:

## Clarity Report — [filename]

**Grade Level:** X [Good/OK/Needs Work]  (target: ≤ 9)
**Word Count:** X
**Reading Time:** ~X min
**Sentences:** X total

---

### Hard Sentences

[RED ARI X] "sentence..."
  Suggestion: Split at [natural break] or replace [long word] with [simpler word].

[YEL ARI X] "sentence..."
  Suggestion: [specific simplification]

---

### Adverbs (X found — target: ≤ 3)

"quickly" in "She ran quickly to the..." → upgrade verb: "She rushed to the..."

---

### Qualifiers (X found — target: 0)

"I think" in "...I think this approach..." → remove: "This approach..."
"maybe" in "...maybe we should..." → restate with conviction: "We should..."

---

### Complex Words (X found)

"utilize" → "use"
"leverage" → "use"

---

### Passive Voice (X found)

"The report was written by Susan." → "Susan wrote the report."

---

### Verdict

PASS — writing is clear and readable.
  OR
NEEDS WORK — [list the specific issues that exceed thresholds].

Pass/Fail Gates

PASS when ALL of these are true:

• Grade level ≤ 11 (≤ 9 ideal, ≤ 11 acceptable)
• Zero red sentences
• ≤ 3 yellow sentences
• Zero qualifiers
• Adverbs ≤ 5

NEEDS WORK when ANY of these are true:

• Grade level > 11
• Any red sentences exist
• More than 3 qualifiers
• Adverbs > 8

For borderline results (grade 10-11, 1-3 yellows, 4-8 adverbs): PASS with specific recommendations noted in the report.

How to Fix Common Issues

Red/Yellow sentences: Find the main clause and break the sentence there. Look for conjunctions (and, but, because, which, that, who) as natural split points. Replace any word over 3 syllables with a simpler synonym if one exists.

Adverbs: Find the verb the adverb modifies. Ask: is there a single stronger verb? "ran quickly" → "sprinted". "spoke quietly" → "murmured". If no upgrade exists, the adverb is acceptable.

Qualifiers: Delete them. "I think this works" → "This works." "Maybe consider" → "Consider." If the uncertainty is genuine and important, express it differently: "The data suggests..." rather than "I think maybe the data..."

Passive voice: Identify the actor (often follows "by"). Move them to subject. "The dashboard was built by the team" → "The team built the dashboard." Exception: passive is fine when the actor is unknown or irrelevant.