playbooks

home / skills / humanizerai / agent-skills / readability

readability skill

/skills/readability

This skill analyzes text readability using Flesch-Kincaid, Gunning Fog, and SMOG, providing scores, interpretations, and practical improvement recommendations.

npx playbooks add skill humanizerai/agent-skills --skill readability

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.2 KB
---
name: readability
description: Analyze text readability with Flesch-Kincaid, Gunning Fog, SMOG, and other metrics. Returns objective scores with interpretation and recommendations.
user-invocable: true
argument-hint: "[text to analyze]"
---

# Analyze Readability

Calculate and display readability metrics for the provided text.

## Input

The user provides text in $ARGUMENTS. If no text provided, ask for it.

## Metrics to Calculate

### Core Scores

| Metric | Formula | Interpretation |
|--------|---------|----------------|
| **Flesch Reading Ease** | 206.835 - 1.015(words/sentences) - 84.6(syllables/words) | 0-100, higher = easier |
| **Flesch-Kincaid Grade** | 0.39(words/sentences) + 11.8(syllables/words) - 15.59 | US grade level |
| **Gunning Fog Index** | 0.4[(words/sentences) + 100(complex words/words)] | Years of education |
| **SMOG Index** | 1.043 × √(complex words × 30/sentences) + 3.1291 | Grade level |

*Complex words = 3+ syllables*

### Text Statistics

- Word count
- Sentence count
- Average sentence length (words)
- Average word length (characters)
- Complex words count and %
- Passive voice sentences (estimate)

## Output Format

```
## Readability Analysis

### Scores
| Metric | Score | Meaning |
|--------|-------|---------|
| Flesch Reading Ease | [X] | [interpretation] |
| Flesch-Kincaid Grade | [X] | [grade level] |
| Gunning Fog | [X] | [years education] |
| SMOG | [X] | [grade level] |

### Statistics
- Words: [X]
- Sentences: [X]
- Avg sentence length: [X] words
- Complex words: [X] ([Y]%)

### Target Audience
[Who can easily read this based on scores]

### Recommendations
1. [Specific suggestion]
2. [Specific suggestion]
3. [Specific suggestion]
```

## Interpretation Guide

| Flesch Score | Grade | Audience |
|--------------|-------|----------|
| 90-100 | 5th | Very easy |
| 80-89 | 6th | Easy |
| 70-79 | 7th | Fairly easy |
| 60-69 | 8-9th | Standard |
| 50-59 | 10-12th | Fairly difficult |
| 30-49 | College | Difficult |
| 0-29 | Graduate | Very difficult |

## Recommendations

Based on scores, suggest:
- Sentences to shorten (if avg > 20 words)
- Complex words to simplify
- Passive voice to convert to active
- Specific examples of what to fix

Overview

This skill analyzes text readability using established formulas like Flesch Reading Ease, Flesch-Kincaid Grade, Gunning Fog, and SMOG. It returns objective scores, interprets them for likely readers, and gives concrete recommendations to simplify or adjust the text. The output includes summary statistics and actionable edits to improve clarity.

How this skill works

You provide the text to analyze. The skill counts words, sentences, syllables and complex words (3+ syllables), estimates passive sentences, and computes core readability metrics. It maps numeric results to audience levels and produces targeted suggestions such as shortening sentences, replacing complex words, and converting passive constructions.

When to use it

  • Assess accessibility of blog posts, guides, or web content
  • Optimize copy for a target grade level or audience
  • Evaluate SEO and UX impact of long or complex text
  • Review academic or technical drafts for readability
  • Compare readability before and after edits

Best practices

  • Provide representative sample text (at least a few paragraphs) for accurate metrics
  • Specify a target audience or grade level if you have one
  • Iterate: re-run analysis after applying recommendations
  • Prioritize shortening very long sentences (>20 words) and simplifying frequent complex words
  • Use active voice for clearer, more direct prose

Example use cases

  • Lower reading level of product descriptions to improve conversions
  • Prepare user manuals targeted at a general audience (grade 8–10)
  • Edit marketing emails to increase engagement by raising Flesch score
  • Audit internal documentation to reduce jargon and passive phrasing
  • Train writers with before/after readability comparisons

FAQ

What does each score mean for my readers?

Flesch Reading Ease ranges 0–100 (higher = easier). Flesch-Kincaid, Gunning Fog, and SMOG return approximate US grade levels or years of education required to understand the text.

How much text is needed for reliable results?

Short paragraphs work, but analysis is more reliable with several sentences (ideally 200+ words). Very short inputs can skew sentence- or syllable-based metrics.