readability — Claude Code skill: score how readable your text is
Runs Flesch-Kincaid, Gunning Fog, SMOG and other readability metrics on your text. Useful when you need to know who can actually read a draft.
npx skills add humanizerai/agent-skills --skill readability -a claude-codeWhat readability does
The skill takes the text you pass as an argument and returns four scores: Flesch Reading Ease, Flesch-Kincaid Grade, Gunning Fog and SMOG. Each comes with a plain reading — grade level, years of education, who finds the text easy. Pass nothing and it asks for the text.
Alongside the scores you get statistics: word and sentence counts, average sentence length in words, average word length in characters, the share of complex words (three syllables or more) and an estimate of passive voice. Then recommendations follow — which sentences to shorten, which words to simplify, where to switch passive to active, with examples.
The formulas are applied as written, so the numbers depend on how sentences and syllables get counted. On a two-paragraph draft the metrics jump around: SMOG, for instance, assumes a sample of at least 30 sentences, so a five-line note gets a rough grade. Treat the score as a hint rather than a verdict.
What it helps with
- check what grade level a draft article lands at
- find sentences over 20 words and cut them down
- measure the share of complex words in a text
- see whether passive voice is piling up
- compare readability of two versions of a document
Example prompts for the agent
- /readability <text to analyze>
- score the readability of this text: <paste a paragraph>
- run my draft through Flesch-Kincaid and Gunning Fog
How to install readability
1Skills CLI (Vercel)
npx skills add humanizerai/agent-skills --skill readability -a claude-code2Manually: put the files in place
~/.claude/skills/readability/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/readability/
1Skills CLI (Vercel)
npx skills add humanizerai/agent-skills --skill readability -a codex2Manually: put the files in place
.agents/skills/readability/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add humanizerai/agent-skills --skill readability -a cursor2Manually: put the files in place
.cursor/skills/readability/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install humanizerai/agent-skills readability2Manually: put the files in place
.github/skills/readability/SKILL.md1Skills CLI (Vercel)
npx skills add humanizerai/agent-skills --skill readability -a gemini-cli2Platform CLI
gemini skills install https://github.com/humanizerai/agent-skills --path skills/readabilityManually: put the files in place
.devin/skills/readability/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add humanizerai/agent-skills --skill readability -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about readability
How do I install readability in Claude?
Run npx skills add humanizerai/agent-skills --skill readability -a claude-code. The skill lands in ~/.claude/skills/readability/SKILL.md.
What does readability do?
It calculates Flesch Reading Ease, Flesch-Kincaid Grade, Gunning Fog and SMOG for your text, adds word and sentence statistics, and suggests what to simplify.
Which platforms does readability support?
Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. Each has its own install path, for Cursor it is npx skills add humanizerai/agent-skills --skill readability -a cursor.
Source text
SKILL.md · MIT
--- 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
© humanizerai · MIT · humanizerai/agent-skills
