Assess text readability using multiple metrics. Execute Python script for detailed readability analysis. Use when evaluating text complexity, comprehension level, or audience fit.
⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads
This Claude skill automates text readability analysis using multiple industry-standard formulas such as Flesch-Kincaid, Gunning Fog, and SMOG. It provides actionable insights into writing complexity, including grade level estimates, reading ease scores, and detailed linguistic statistics. By identifying overly complex sentences and high-syllable counts, it helps writers and editors refine their content to perfectly match the comprehension level of their target audience.
Use Cases
Content Optimization: Evaluate blog posts or marketing copy to ensure they meet a 'Standard' readability level (8th-9th grade) for maximum general audience engagement.
Technical Documentation: Audit complex manuals or API guides to reduce cognitive load and ensure instructions are accessible to non-expert users.
Educational Material Development: Align textbooks, lesson plans, or training modules with specific US grade levels to ensure age-appropriate comprehension.
SEO & UX Writing: Improve website dwell time and user experience by simplifying complex landing page copy based on objective readability metrics.
Document Version Comparison: Quantify the improvement in clarity between original drafts and simplified revisions to track editing progress.
name
readability-scorer
description
Calculate readability scores (Flesch-Kincaid, Gunning Fog, SMOG) and grade levels for text. Analyze writing complexity and get improvement suggestions.
Readability Scorer
Analyze text readability using industry-standard formulas. Get grade level estimates, complexity metrics, and suggestions for improving clarity.
Quick Start
from scripts.readability_scorer import ReadabilityScorer
# Score text
scorer = ReadabilityScorer()
scores = scorer.analyze("Your text to analyze goes here.")
print(f"Grade Level: {scores['grade_level']}")
print(f"Flesch Reading Ease: {scores['flesch_reading_ease']}")
Features
Multiple Formulas: Flesch-Kincaid, Gunning Fog, SMOG, Coleman-Liau, ARI
Grade Level: US grade level estimate
Reading Ease: 0-100 ease score
Text Statistics: Words, sentences, syllables, complex words
# Analyze text
python readability_scorer.py --text "Your text here"
# Analyze file
python readability_scorer.py --input document.txt
# Compare files
python readability_scorer.py --compare doc1.txt doc2.txt
# Batch analyze directory
python readability_scorer.py --input-dir ./docs --output report.csv
# Specific formula only
python readability_scorer.py --input doc.txt --formula flesch
CLI Arguments
Argument
Description
Default
--text
Text to analyze
-
--input
Input file
-
--input-dir
Directory of files
-
--output
Output file (json/csv)
-
--compare
Compare two files
-
--formula
Specific formula
all
Score Interpretation
Flesch Reading Ease
Score
Difficulty
Grade Level
90-100
Very Easy
5th grade
80-89
Easy
6th grade
70-79
Fairly Easy
7th grade
60-69
Standard
8th-9th grade
50-59
Fairly Hard
10th-12th grade
30-49
Difficult
College
0-29
Very Difficult
College graduate
Grade Level Scale
Grade
Audience
1-5
Elementary school
6-8
Middle school
9-12
High school
13-16
College
17+
Graduate level
Examples
Analyze Blog Post
scorer = ReadabilityScorer()
blog_post = """
Writing clear content is essential for engaging readers.
Short sentences help. Simple words work best.
Your audience will thank you for making things easy to understand.
"""
scores = scorer.analyze(blog_post)
print(f"Flesch Reading Ease: {scores['flesch_reading_ease']:.1f}")
print(f"Grade Level: {scores['grade_level']:.1f}")
print(f"Reading Time: {scores['reading_time_minutes']:.1f} minutes")
if scores['grade_level'] > 8:
print("Consider simplifying for a wider audience.")
scorer = ReadabilityScorer()
import os
results = []
for filename in os.listdir("./docs"):
if filename.endswith(".md"):
text = open(f"./docs/{filename}").read()
scores = scorer.analyze(text)
results.append({
'file': filename,
'grade': scores['grade_level'],
'ease': scores['flesch_reading_ease']
})
# Sort by difficulty
results.sort(key=lambda x: x['grade'], reverse=True)
print("Documents by Difficulty:")
for r in results:
print(f" {r['file']}: Grade {r['grade']:.1f}")
Dependencies
nltk>=3.8.0
Limitations
English language only
Formulas designed for prose (may not work well for lists, code, etc.)
Syllable counting is estimated (may have minor inaccuracies)
Doesn't assess comprehension, only surface-level complexity