readability
npx machina-cli add skill humanizerai/agent-skills/readability --openclawAnalyze 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
Source
git clone https://github.com/humanizerai/agent-skills/blob/main/skills/readability/SKILL.mdView on GitHub Overview
Readability analyzes text using standard metrics like Flesch Reading Ease, Flesch-Kincaid Grade, Gunning Fog, and SMOG to produce objective scores, interpretations, and actionable recommendations. It also reports statistics such as word and sentence counts, average sentence length, and complex word usage to guide revisions.
How This Skill Works
The skill takes user-provided text, computes core readability scores using established formulas (Flesch Reading Ease, Flesch-Kincaid Grade, Gunning Fog, SMOG), and identifies complex words (3+ syllables). It then outputs a structured Readability Analysis including Scores, Statistics, Target Audience, and Recommendations to improve clarity and accessibility.
When to Use It
- Tailoring marketing emails or blog posts to a specific audience by targeting an appropriate reading level
- Simplifying customer-facing policies, terms, or help articles for general readers
- Preparing instructional or educational materials aligned with a desired grade level
- Auditing technical or legal documents for accessibility and comprehension
- Evaluating drafts to reduce passive voice and shorten long sentences before publication
Quick Start
- Step 1: Provide the text to analyze as the argument input
- Step 2: Run Readability Analysis to obtain Scores, Statistics, and Recommendations
- Step 3: Revise the text per recommendations (shorten sentences, replace complex words, adjust voice), then re-run until targets are met
Best Practices
- Provide enough representative text to get stable scores across sections
- Use score ranges to set concrete targets for your target audience
- Identify long sentences and complex words to simplify (aim for shorter sentences and common vocabulary)
- Convert passive constructions to active voice where appropriate
- Validate revisions by re-running the analysis and comparing scores to targets
Example Use Cases
- Marketing page rewritten from college-level to 8th-grade level, increasing reader engagement
- Legal disclaimer clarified from 12th-grade to 9th-grade level for wider comprehension
- Technical manual shortened: average sentence length reduced and complex terms replaced
- Customer support article improved with higher Flesch Reading Ease and lower Flesch-Kincaid Grade
- Educational handout aligned to 6th-7th grade to reach a broader classroom audience
