readability-check

Score prose with five readability formulas and list the sentences to rewrite.

Updated Sep 9, 2026
One-click install
npx skills add https://github.com/lyndonkl/hermesworld --skill readability-check-lyndonkl
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: readability-check
Source: https://github.com/lyndonkl/hermesworld/tree/main/shared/skills/readability-check
Command: npx skills add https://github.com/lyndonkl/hermesworld --skill readability-check-lyndonkl

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires textstat, and includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve? Drafts and documents often read as dense or convoluted, but subjective review cannot tell you which sentences cause it or whether the text hits a target reading level. This Skill scores prose objectively and names the exact sentences to fix. ## Core Features & Use Cases - Five-formula scoring: Computes Flesch Reading Ease, Flesch-Kincaid Grade, SMOG, Gunning Fog, and Dale-Chall, mapping each to one shared grade band with a consensus reading level. - Actionable offender list: Reports the specific over-length sentences driving failures, so revision starts with the worst sentence rather than guesswork. - Audience-based profiles: Enforces technical, general, or public thresholds on markdown files, directories, or piped draft text, with markdown-aware stripping of code, tables, and headings. - Use Case: Before shipping a design document, pipe the draft through the script at the technical profile, rewrite the flagged 60-word sentences using the revision moves, and re-run until it passes. ## Quick Start Ask the agent to run the readability check on your draft file with the general profile and rewrite the flagged sentences until it passes.

Frequently Asked Questions about readability-check

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check the readability of a markdown file in Python?

Run readability.py with the file path and a profile, for example python3 readability.py doc.md --profile general. It prints five formula scores with grade bands, a pass/fail verdict, and the longest sentences to rewrite.

What readability formulas should I use for technical writing?

Use Flesch Reading Ease, Flesch-Kincaid, Gunning Fog, SMOG, and Dale-Chall together. Dale-Chall uses a familiar-word list rather than syllables, so it catches dense jargon that syllable-based formulas miss on technical prose.

Why is my Dale-Chall score high when other formulas pass?

Dale-Chall counts any word outside its familiar-word list as difficult, so specialist vocabulary scores hard even in short sentences. The fix is defining terms on first use or accepting the score for an expert audience, not shortening sentences.

Does the readability script work on text piped from stdin?

Yes, pass --stdin and pipe draft text directly, which is the common way to check prose before sending it. The script strips markdown formatting before scoring and exits 0 on pass, 1 on fail.

What are the limitations of readability formulas?

Formulas measure sentence length and word difficulty, not correctness or coherence, so text can pass every threshold and still be wrong. SMOG needs at least 30 sentences, nothing under 40 words is scored, and the formulas only work for English.