readability-scorer

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

When & Why to Use This Skill

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.
namereadability-scorer
descriptionCalculate 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
  • Batch Analysis: Process multiple documents
  • Comparison: Compare readability across texts

API Reference

Initialization

scorer = ReadabilityScorer()

Analysis

scores = scorer.analyze(text)
# Returns:
# {
#     'flesch_reading_ease': 65.2,
#     'flesch_kincaid_grade': 8.1,
#     'gunning_fog': 10.2,
#     'smog_index': 9.5,
#     'coleman_liau': 9.8,
#     'ari': 8.4,
#     'grade_level': 8.5,  # Average
#     'reading_time_minutes': 2.3,
#     'stats': {
#         'words': 250,
#         'sentences': 15,
#         'syllables': 380,
#         'complex_words': 25,
#         'avg_words_per_sentence': 16.7,
#         'avg_syllables_per_word': 1.52
#     }
# }

Individual Scores

# Get specific scores
fre = scorer.flesch_reading_ease(text)
fkg = scorer.flesch_kincaid_grade(text)
fog = scorer.gunning_fog(text)
smog = scorer.smog_index(text)

Batch Analysis

texts = [text1, text2, text3]
results = scorer.analyze_batch(texts)

# From files
results = scorer.analyze_files(["doc1.txt", "doc2.txt"])

Comparison

# Compare two texts
comparison = scorer.compare(text1, text2)
print(f"Text 1 grade: {comparison['text1']['grade_level']}")
print(f"Text 2 grade: {comparison['text2']['grade_level']}")

CLI Usage

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

Compare Document Versions

scorer = ReadabilityScorer()

original = open("original.txt").read()
simplified = open("simplified.txt").read()

comparison = scorer.compare(original, simplified)

print("Original:")
print(f"  Grade Level: {comparison['text1']['grade_level']:.1f}")
print(f"  Flesch Ease: {comparison['text1']['flesch_reading_ease']:.1f}")

print("\nSimplified:")
print(f"  Grade Level: {comparison['text2']['grade_level']:.1f}")
print(f"  Flesch Ease: {comparison['text2']['flesch_reading_ease']:.1f}")

improvement = comparison['text1']['grade_level'] - comparison['text2']['grade_level']
print(f"\nImprovement: {improvement:.1f} grade levels easier")

Batch Analyze Documentation

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