Clarity skill
Addy Osmani skill for clearer writing: an interview and draft from your own words, a rewrite of existing text, a review that leaves the file alone
- 281 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The skill reads the draft files you name and edits them in rewrite mode, while review and lint modes leave the file unchanged
- The strip_markdown.py and prose_stats.py scripts run locally on your machine and only print diagnostics
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/clarityDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The skill reads the draft files you name and edits them in rewrite mode, while review and lint modes leave the file unchanged
- The strip_markdown.py and prose_stats.py scripts run locally on your machine and only print diagnostics
This is third-party code. Review the repository files before installing.
What it does
Clarity is an Addy Osmani skill for agents that applies clear-writing rules when you draft, rewrite or review prose. The mode is the first word after /clarity. interview runs an interview on a topic and writes text from your examples and wording, rewrite edits an existing draft, review gives a critique and leaves the file alone, and lint and stats run diagnostics without changing the text. With no mode word the skill infers the task from the request. Before touching style the skill asks questions about substance: who the text is for, what the reader already knows and what they should take away. It does not invent facts, numbers, quotes or personal experience, keeps attribution in place and does not promise an AI detector result. Each mode loads its own reference: interview.md, edit.md, review.md, with longform.md added for essays and articles and medium.md for documentation, emails and interface text. The Python scripts strip_markdown.py and prose_stats.py show where a text has familiar tells but output no overall score.
Who it is for. For authors of blogs, newsletters, documentation and talks who write with an agent and want to keep their own voice and facts.
Good fit when
- You have an essay or article draft that sounds smooth and empty: the skill strips generic wording without inventing details
- You want to write from scratch but have little material: interview mode pulls out your examples and position with questions
- You need a critique of a draft that does not change the file: review mode
- You want to check a newsletter, a launch post or documentation for signs of machine text
- You want text statistics, sentence length and repetition, through prose_stats.py
Not a fit when
- You need to pass an AI detector: the skill does not optimize for detectors and does not promise their result
- You want examples and stories added that are not in your material: the skill invents nothing
- You need translation or spell checking: the skill modes are about structure, substance and style of prose
- You need rules for Russian text: the references and samples are written in English
Example request
/clarity review draft.md: critique my article draft about our incident reviews and tell me where it says nothing specific, do not change the fileLimitations
The references, samples and examples in the repository are in English, and the author does not describe testing on Russian text. The linter scripts need Python 3. The skill does not guarantee an AI detector result or prove authorship, and the author says so directly. The author promises to publish evaluation results in the evals folder along with model versions, and the repository claims no benchmark win.
The browser version at clarity.addy.ie does not upload your draft to a server.
How to disable. Delete the clarity folder from the project skills directory or from ~/.claude/skills/. If you copied the wrappers, delete clarity-interview.md, clarity-rewrite.md and clarity-review.md from ~/.claude/commands/.
FAQ
How do I install Clarity in Claude Code?
Run npx skills add addyosmani/clarity or pnpm dlx skills add addyosmani/clarity. After that /clarity takes the mode as its first word: rewrite draft.md, review draft.md or interview <topic>. The separate /clarity-interview, /clarity-rewrite and /clarity-review commands appear after you copy the files from commands/ to ~/.claude/commands/.
How is interview mode different from simply asking for a text?
The skill first asks for your examples, wording, doubts and position and then assembles a draft from what you said. That keeps in the text what a model would not invent by itself. The samples/ folder holds the interview transcript beside the finished text, so the provenance can be checked.
Does Clarity fool AI detectors?
No. The skill does not optimize text for detectors, does not fake typos or slang and does not promise a check result. The goal is text that is useful, clear and yours, with honest provenance.
How is Clarity different from skills that strip AI tells?
Those skills clean template phrases by list. Clarity first works through questions of substance, the reader, the main point and specifics, and only then edits style and judges in context whether a pattern is a problem.
Is there an online version of Clarity?
Yes, clarity.addy.ie has a browser editor that looks for AI writing tells, computes readability and asks the broader Clarity questions. The author says your draft is not uploaded. The site also has step-by-step tutorials for Claude Code and Codex.
Discussion
No questions or reviews yet.
Related
SkillsA de-AI writing skill: it repairs the narrative architecture of fiction and edits professional documents by their venue rules
Avoid AI Writing
avoid-ai-writing
A skill that finds typical machine-writing patterns in text and rewrites them, with detect-only and edit-in-place modes
A short skill with strict rules that removes stock AI phrases and structures from prose
A skill that finds AI tells in English prose and edits them surgically; three Python scanners run on their own and the teach command learns your voice
A skill that breaks down an author's articles and derives a reusable style profile: language, structure, topic logic, sourcing and visual presentation
A skill that strips AI writing tells from text using Wikipedia's list, without adding invented facts
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Clarity (this entry) | no | 281 | |
| Stop Slop | no | 18,266 | a short rule set that strips template AI phrases, with no interview or review mode |
| Humanizer | no | 59,836 | removes AI writing tells from the Wikipedia list, while this one focuses on substance, the reader and your material |
| nopus | no | 299 | a plugin that measures language complexity in coding-agent replies |
README in short
The README doubles as an essay on writing. It starts with installing the skill and its modes, then gives eighteen principles in four groups: useful, clear, yours and making it. The second half describes the skill itself: repository contents, three ways to work, what each mode does, behavior checks through evals and running the linter.
README badge
Original SKILL.md
--- name: clarity description: "Draft, rewrite, or review reader-facing prose so it is specific, useful, and recognizably the author's without inventing facts or performing humanness. Use for essays, articles, newsletters, documentation, talks, launch copy, and other important prose that feels generic, hollow, or AI-shaped. Supports co-write, rewrite, review, and lint modes." license: MIT metadata: version: "0.2.1" --- # Clarity Good prose gives a particular reader something worth carrying away. Generic model prose often fails before style enters the picture: it has no specific source, judgment, mechanism, image, or experience behind it. Fix that first. Do not optimize for an AI detector or promise a detector result. Do not manufacture typos, slang, anecdotes, uncertainty, opinions, or awkwardness. The goal is better writing with honest provenance. ## Choose a mode An explicit mode word wins: ```txt interview | write | draft | new Co-write from the author's supplied language. rewrite | edit | fix | humanize Rewrite an existing draft. review | critique | check Critique without rewriting or changing files. lint | stats Run diagnostics without changing prose. ``` Without a mode, infer from the request. Ask only when the user could reasonably mean either a review or a rewrite. Load only the reference the mode needs: ```txt Co-write references/interview.md Rewrite references/edit.md Review references/review.md, then references/edit.md as a pattern reference Lint scripts/strip_markdown.py and scripts/prose_stats.py ``` For essays, articles, newsletters, talks, speeches, narrative, fiction, or other authored long-form prose, also read `references/longform.md`. For academic, legal, medical, safety, reference, procedural, marketing, email, UI, speech,