Readability Scorer

I assess how easy text is to read and understand for different audiences.

How to Use This Skill

When analyzing text readability, execute the readability scorer script:

python /home/ywatanabe/dev/agent-patterns/.claude/skills/readability-scorer/run.py "text to analyze"

The script returns JSON results with readability scores, audience fit, and improvement suggestions.

What I Measure

Readability Metrics

• Flesch Reading Ease: 0-100 scale (higher = easier)
• Flesch-Kincaid Grade Level: U.S. school grade equivalent
• Average Sentence Length: Words per sentence
• Average Word Length: Syllables per word
• Complex Words: Percentage of 3+ syllable words

Structural Analysis

• Sentence variety (simple, compound, complex)
• Paragraph length and structure
• Use of transition words
• Logical flow and organization

Vocabulary Assessment

• Technical jargon usage
• Common vs. rare words
• Active vs. passive voice ratio
• Concrete vs. abstract language

Audience Fit

• Recommended audience (general public, professionals, experts)
• Education level required
• Domain expertise needed

When This Skill Activates

Activate when user requests:

• "Check readability" or "reading level"
• "Is this too complex/simple?"
• "What audience is this for?"
• "Simplify this text" or "make more accessible"
• Any request about comprehension difficulty

Analysis Process

1. Calculate Metrics: Compute readability scores
2. Analyze Structure: Evaluate sentence and paragraph patterns
3. Assess Vocabulary: Identify complex/technical terms
4. Determine Audience Fit: Match to reader profiles
5. Provide Recommendations: Suggest improvements

Output Format

Provide structured readability report:

Readability Scores:

• Flesch Reading Ease: [Score] ([Interpretation])
• Flesch-Kincaid Grade: [Level] ([Equivalent])
• Overall Assessment: [Very Easy/Easy/Moderate/Difficult/Very Difficult]

Structural Analysis:

• Average sentence length: [X words] ([Assessment])
• Sentence variety: [Good/Needs improvement]
• Paragraph structure: [Assessment]
• Logical flow: [Clear/Confusing]

Vocabulary Analysis:

• Complex words: [X%]
• Technical jargon: [Examples]
• Passive voice: [X%]
• Recommendations: [Specific suggestions]

Audience Fit:

• Best suited for: [Audience description]
• Education level: [Grade level or equivalent]
• Domain expertise: [None/Basic/Intermediate/Advanced]

Improvement Suggestions:

• Specific recommendations to improve readability
• Examples of simplifications

Example Analysis

Input: "The implementation of our sophisticated algorithmic framework necessitates comprehensive documentation to facilitate subsequent modifications and enhancements."

Output:

Readability Scores:
- Flesch Reading Ease: 12 (Very Difficult)
- Flesch-Kincaid Grade: 18+ (College graduate level)
- Overall Assessment: Very Difficult

Structural Analysis:
- Average sentence length: 19 words (Long)
- Single complex sentence - needs variety
- Heavy noun stacking

Vocabulary Analysis:
- Complex words: 65%
- Technical jargon: "algorithmic framework"
- Passive voice: 0% (good)
- Unnecessarily complex: "implementation", "necessitates", "facilitate", "subsequent"

Audience Fit:
- Best suited for: Technical experts
- Education level: College graduate+
- Domain expertise: Advanced programming/CS

Improvement Suggestions:
1. Break into multiple sentences
2. Replace complex words:
   - "implementation" → "use"
   - "necessitates" → "requires" or "needs"
   - "facilitate" → "enable" or "help"
   - "subsequent" → "future" or "later"

Simplified version:
"Our algorithm framework needs good documentation. This will help us make changes and improvements later."

New scores:
- Flesch Reading Ease: 72 (Fairly Easy)
- Grade Level: 7th grade

Tone

• Educational and constructive
• Data-driven
• Audience-aware
• Practical recommendations