clear-writing
Skill1 starsChanged 18 days agoMITView on GitHub
Finds sentences in Markdown, text and templ files that are long, tangled or sound machine-written, rewrites only those in place in plain English, and reports the flagged sentences it kept. Use when the user wants docs, a README or page copy easier to read, asks to simplify, shorten or tighten wordy sentences, to deslop or humanize text, to remove AI writing tells, or to check the writing in a branch before a pull request.
17 other projects use a version of this.
Adopted by
Most recently taken up by
- rediche/skillstheir own version, first seen Nov 16, 2026
- emadabdulrahim/claude-skillstheir own version, first seen Nov 16, 2026
- PanQiWei/pqw-skillstheir own version, first seen Nov 15, 2026
- liao666brant/skillstheir own version, first seen Nov 15, 2026
- wanderingspirit03/clear-writing-skilltheir own version, first seen Nov 15, 2026
- sodejm/portable-agent-repository-kittheir own version, first seen Nov 8, 2026
Other versions17 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 17
- wanderingspirit03/clear-writing-skill★ 48same name
- wpank/ai★ 11same name
- rediche/skills★ 3same name
- liao666brant/skills★ 1same name
- PanQiWei/pqw-skills★ 1same name
- pinkpixel-dev/agent-context-kit★ 1same name
- pinkpixel-dev/skills★ 1same name
- sglibiciuc/skills★ 1same name
- sgrzincich/skills★ 1same name
- sodejm/portable-agent-repository-kit★ 1same name
7 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- openkata-eval-runnerSkill
- openkata-optimize-skillsSkill
- openkata-review-ruleSkill
- openkata-review-skillSkill
- openkata-rule-conventionsSkill
- openkata-ryu-releaseSkill
- openkata-skill-conventionsSkill
- commit-conventionsSkill
- create-adrSkill
- create-evalsSkill
- create-profileSkill
- create-ruleSkill
- create-skillSkill
- critical-thinkingSkill
- github-create-prSkill
- git-worktreeSkill
- grill-meSkill
- grill-with-docsSkill
- makefile-conventionsSkill
- spec-workflowSkill
The file
We split this skill into the rules it gives an agent
12 rules. 0 are common, 10 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 14 edited versions we read keep these.
10
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Pick the scope: Use the files, folder or pasted text the user names.
- Distinctive: line 44
If Python 3 is not available, read the text yourself and flag these:
- Distinctive: line 54
Judge each flagged sentence: Read it in its paragraph and decide whether it is really hard to read.
- Very specific: line 61
Leave a (weak) reason alone unless it makes the sentence harder to read, or the sentence has other reasons too.
- Distinctive: line 67
Put a condition before the instruction it limits.
- Distinctive: line 69
Watch-list term: use the plain alternative from the watch list, or delete the term when the list says so.
- Distinctive: line 71
Dash or semicolon: use a period, a comma or a colon.
- Distinctive: line 74
When you split a sentence, name the subject again instead of starting with "it" or "this" when the reader could lose track.
- Distinctive: line 76
Keep the facts, terms, tone and contractions of the original.
- Distinctive: line 77
Keep the file's line wrapping.
- Distinctive: line 79
Check again: Run the script on the same scope.
- Distinctive: line 137
NEVER "improve" a sentence the check did not flag.
“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Clear Writing
Make writing easy to read for every reader, including people who read English as a second language. A script finds the sentences that need work, you judge each one, and you rewrite only the ones that need it. Every other sentence stays exactly as the author wrote it.
Workflow
- Pick the scope. Use the files, folder or pasted text the user
names. For "the branch" or "before a PR", use the changed lines:
--changed <base>, where<base>is the branch the work will merge into, such asmain. Run the check. The script is
scripts/check.pyin this skill's folder. Run it from the project root:python3 <skill-folder>/scripts/check.py [--changed main] <paths>In
.templfiles only the page text inside components is read, not the Go code or the attributes.Pasted text goes in on standard input with
-as the path. Each output line ispath:line: reasons | sentence. Exit status 1 means sentences were flagged and 0 means none were.If Python 3 is not available, read the text yourself and flag these:
- sentences of more than 25 words
- sentences of three or more clauses
- the terms in the watch list
- clauses joined by a dash, unless at most three words come before it
- clauses joined by a semicolon (weak)
- asides of more than eight words in parentheses (weak)
- Judge each flagged sentence. Read it in its paragraph and
decide whether it is really hard to read.
- Fix every sentence flagged
longortangled. - Fix a watch-list term unless it is the precise word in this
context, such as
robustfor a statistical method. - Fix a dash that joins clauses, unless the sentence is a slogan or tagline, or a quote.
- Leave a
(weak)reason alone unless it makes the sentence harder to read, or the sentence has other reasons too.
- Fix every sentence flagged
Rewrite in place. Edit the file directly. For each sentence you fix, apply only the fixes its reasons call for:
- Long or tangled: split it so each sentence holds one idea. Put a condition before the instruction it limits. Turn three or more parallel items into a list.
- Watch-list term: use the plain alternative from the watch list, or delete the term when the list says so.
- Dash or semicolon: use a period, a comma or a colon.
- Long aside: make it its own sentence.
When you split a sentence, name the subject again instead of starting with "it" or "this" when the reader could lose track. Keep the facts, terms, tone and contractions of the original. Keep the file's line wrapping.
- Check again. Run the script on the same scope. Fix any sentence your rewrite made long. A flagged sentence you decided to keep stays flagged.
- Report. Tell the user how many sentences you rewrote. List each flagged sentence you kept, with the reason. Leave the changes for the user to review in the diff.
To run the check on every commit, set up the git hooks in references/git-hooks.md. Do this only when the user asks for it.
Example
Input docs/skills.md:
Skills are context-efficient by design. Your agent reads a one-line
description at session start — the full workflow only loads when
it's actually triggered.Check output:
docs/skills.md:1: phrase 'by design' | Skills are context-efficient by design.
docs/skills.md:1: word 'actually', dash joins clauses | Your agent reads a one-line description at session start — the full workflow only loads when it's actually triggered.Rewritten in place:
Skills are context-efficient. Your agent reads a one-line
description at session start. It loads the full workflow only when
the skill is triggered.by design and actually were deleted as the watch list says, and
the dash became a period.
Boundaries
DOES:
- Find long, tangled and machine-sounding sentences with a script
- Rewrite flagged sentences in place, keeping meaning and tone
- Work on files, folders, pasted text or a branch's changed lines
Does NOT:
- Rewrite sentences the check did not flag
- Change code blocks, inline code, commands, paths, links, headings, frontmatter, tables or quoted text
- Fix spelling or grammar, translate, or change the document's structure
- Try to hide that text was written with AI
Common Failures
- Rewriting unflagged text. The whole point is a small diff. NEVER "improve" a sentence the check did not flag.
- Losing a fact when splitting. Each number, name, condition and limit in the original MUST appear in the rewrite.
- Telegraph style. Short does not mean clipped. Keep articles, verbs and "that". "Run check. Fix output." is worse than the original.
- Breaking Markdown. Splitting across a link or inline code breaks it. Keep each link and code span whole.
- Breaking markup. In a templ file, change only the text between
tags. Keep every tag, attribute and
{ expression }as it was.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

